diff --git a/mps/manual/source/diagrams/overview.svg b/mps/manual/source/diagrams/overview.svg new file mode 100644 index 00000000000..38b7b417128 --- /dev/null +++ b/mps/manual/source/diagrams/overview.svg @@ -0,0 +1,451 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + code (“text”) segments + data segments + heapmanagedby othermemorymanagers + + + + register files + heap managedby the MPS + + + + control stacks + + threads + + + arena + pool + pool + + pool + + + + + + + + + + + diff --git a/mps/manual/source/guide/debug.rst b/mps/manual/source/guide/debug.rst index d4336f50175..387cfcbe383 100644 --- a/mps/manual/source/guide/debug.rst +++ b/mps/manual/source/guide/debug.rst @@ -1,3 +1,5 @@ +.. highlight:: none + .. _guide-debug: Debugging with the Memory Pool System @@ -17,8 +19,8 @@ delayed. And even if it does die, the space it occupies may not be re-allocated for some time. -General advice --------------- +General debugging advice +------------------------ 1. Compile with debugging information turned on (``-g`` on the GCC or Clang command line). @@ -43,15 +45,34 @@ General advice .. _address space layout randomization: http://en.wikipedia.org/wiki/Address_space_layout_randomization -4. Run your test case inside the debugger. Use ``assert`` or ``abort`` - in your error handler (rather than ``exit``) so that you can enter - the debugger with the contents of the control stack available for - inspection. + A fact that assists with reproducibility is that the more frequently + the collector runs, the sooner and more reliably errors are + discovered. So if you have a bug that's hard to reproduce, you may + be able to provoke it more reliably by having a mode for testing in + which you run frequent collections (by calling + :c:func:`mps_arena_collect` followed by + :c:func:`mps_arena_release`), perhaps as frequently as every + allocation. + +4. Run your test case inside the debugger. Use ``assert`` and + ``abort`` in your error handler (rather than ``exit``) so that you + can enter the debugger with the contents of the control stack + available for inspection. + + You may need to make sure that the debugger isn't entered on + :term:`barrier (1)` hits (because the MPS uses barriers to protect + parts of memory). In GDB, use these commands:: + + (gdb) set dont-handle-bad-access 1 + (gdb) handle SIGBUS nostop + + Add them to your ``.gdbinit`` if appropriate. + .. _guide-debug-underscanning: -Underscanning -------------- +Example: underscanning +---------------------- An easy mistake to make is to omit to :term:`fix` a :term:`reference` when :term:`scanning ` a :term:`formatted object`. For example, @@ -75,8 +96,6 @@ end up pointing to the start of a valid object (but the wrong one), or to the middle of a valid object, or to an unused region of memory, or into an MPS internal control structure. -.. highlight:: none - The reproducible test case is simple. Run a garbage collection by calling ``(gc)`` and then evaluate any expression:: @@ -160,6 +179,8 @@ up to the detection of the error, and in order to enable you to do that, the MPS provides its :ref:`topic-telemetry` feature. +.. _guide-debug-telemetry: + Telemetry --------- @@ -238,10 +259,13 @@ There are no events related to this address, so in particular this address was never fixed. -Getting the size wrong ----------------------- +.. _guide-debug-size: -Here's another kind of mistake: an off-by-one error in ``make_string``: +Example: allocating with wrong size +----------------------------------- + +Here's another kind of mistake: an off-by-one error in ``make_string`` +leading to the allocation of string objects with the wrong size: .. code-block:: c :emphasize-lines: 5 diff --git a/mps/manual/source/guide/index.rst b/mps/manual/source/guide/index.rst index 1d0c7a566a4..870cb962740 100644 --- a/mps/manual/source/guide/index.rst +++ b/mps/manual/source/guide/index.rst @@ -9,5 +9,5 @@ Guide build overview lang - perf debug + perf diff --git a/mps/manual/source/guide/overview.rst b/mps/manual/source/guide/overview.rst index 51084d563be..0134f50c8e6 100644 --- a/mps/manual/source/guide/overview.rst +++ b/mps/manual/source/guide/overview.rst @@ -3,4 +3,50 @@ Overview of the Memory Pool System ================================== +The figure below gives a (simplified) picture of a program's memory +from the point of view of the Memory Pool System. + .. figure:: ../diagrams/overview.svg + :align: center + :alt: Diagram: Overview of the Memory Pool System. + + Overview of the Memory Pool System. + +The :term:`arena` is the top-level data structure in the MPS. An arena +is responsible for requesting :term:`memory (3)` from the operating +system (and returning it), making memory available to :term:`pools +`, and for :term:`garbage collection`. It's best to have only +one arena in your program, because the MPS can't collect cyclic +structures that span multiple arenas, but multiple arenas are +supported. (See :ref:`topic-arena`.) + +Within the arena you create one or more :term:`pools `. A pool +is responsible for requesting memory from the :term:`arena` and making +it available to your program. (See :ref:`topic-pool`.) + +Pools belong to :term:`pool classes ` that specify +policies for how their memory is managed. Some pools are +:term:`manually managed ` (you must call +:c:func:`mps_free` to return a block of memory to the pool) and others +are :term:`automatically managed ` (the +:term:`garbage collector` reclaims :term:`unreachable` +blocks). Automatically managed pools need you to tell them how to find +:term:`references ` to allocated blocks. (See +:ref:`topic-format`.) + +The MPS is designed to work with multi-threaded programs. Functions in +the C interface are thread safe, except in a few documented +cases. (See :ref:`topic-thread`.) The :term:`allocation point +protocol` provides fast lock-free allocation on multiple threads +simultaneously. (See :ref:`topic-allocation`.) + +The MPS is designed to co-operate with other memory managers (for +example :term:`malloc` and :term:`free (2)` in :term:`C`, or operators +``new`` and ``delete`` in :term:`C++`), so you need not move all your +memory management to the MPS at once, and you can co-operate with +libraries that use standard allocation mechanisms. + +The garbage collector is :term:`incremental `: it proceeds in small steps interleaved with the execution +of your program, so there are no long waits. (See +:ref:`topic-collection`.)