From 0cd1f009e99aef34f2e35cc48da70a078e220655 Mon Sep 17 00:00:00 2001 From: Gareth Rees Date: Fri, 26 Oct 2012 13:15:56 +0100 Subject: [PATCH] Write debugging pools chapter. Copied from Perforce Change: 180099 ServerID: perforce.ravenbrook.com --- mps/manual/source/guide/debug.rst | 13 ++-- mps/manual/source/guide/perf.rst | 2 +- mps/manual/source/pool/pool-ams.rst | 8 +- mps/manual/source/topic/collection.rst | 6 ++ mps/manual/source/topic/debugging.rst | 102 ++++++++++++++----------- mps/manual/source/topic/pattern.rst | 4 +- 6 files changed, 77 insertions(+), 58 deletions(-) diff --git a/mps/manual/source/guide/debug.rst b/mps/manual/source/guide/debug.rst index b3461fcac56..0ae9040ffae 100644 --- a/mps/manual/source/guide/debug.rst +++ b/mps/manual/source/guide/debug.rst @@ -45,12 +45,13 @@ General debugging advice .. _address space layout randomization: http://en.wikipedia.org/wiki/Address_space_layout_randomization - 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 + 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, or + which manifests itself in different ways on different runs, you may + be able to provoke it more reliably, or get a more consistent + result 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. diff --git a/mps/manual/source/guide/perf.rst b/mps/manual/source/guide/perf.rst index 17c684a4293..186eadc3fa4 100644 --- a/mps/manual/source/guide/perf.rst +++ b/mps/manual/source/guide/perf.rst @@ -3,4 +3,4 @@ Tuning the Memory Pool System for performance ============================================= -See +Choice of pools. diff --git a/mps/manual/source/pool/pool-ams.rst b/mps/manual/source/pool/pool-ams.rst index d0c52183a81..f0ce4cb9ceb 100644 --- a/mps/manual/source/pool/pool-ams.rst +++ b/mps/manual/source/pool/pool-ams.rst @@ -28,14 +28,14 @@ AMS symbol reference .. c:function:: mps_class_t mps_class_ams(void) - Return the :term:`pool class` for an AMC (Automatic - Mostly-Copying) :term:`pool`. + Return the :term:`pool class` for an AMS (Automatic Mark & Sweep) + :term:`pool`. - When creating an AMC pool, :c:func:`mps_pool_create` takes two + When creating an AMS pool, :c:func:`mps_pool_create` takes two extra arguments:: mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena, - mps_class_t mps_class_amc(), + mps_class_t mps_class_ams(), mps_fmt_t fmt, mps_chain_t chain) diff --git a/mps/manual/source/topic/collection.rst b/mps/manual/source/topic/collection.rst index 6502302aef6..4757fd5a73e 100644 --- a/mps/manual/source/topic/collection.rst +++ b/mps/manual/source/topic/collection.rst @@ -111,6 +111,12 @@ generation`. When the nursery's "new size" exceeds its capacity, the MPS considers collecting the pool. (Whether it actually does so or not depends on which other collections on other pools are in progress.) +.. note:: + + You can affect the decision as to when to collect the nursery + generation by using the :ref:`ramp allocation pattern + `. + If the MPS decides to collect a pool at all, all generations are collected below the first generation whose "new size" is less than its capacity. diff --git a/mps/manual/source/topic/debugging.rst b/mps/manual/source/topic/debugging.rst index e7bfba35f40..21264d6522c 100644 --- a/mps/manual/source/topic/debugging.rst +++ b/mps/manual/source/topic/debugging.rst @@ -7,47 +7,47 @@ Debugging pools =============== -:: +Several :term:`pool classes ` have debugging counterparts +that provide two features that are useful for debugging: - static mps_pool_debug_option_s debugOptions = { +* :dfn:`fenceposts` are patterns of data that are written before and + after each allocated block. These patterns can be checked, for + example when the block is deallocated, to see that they are + unchanged. This helps detect underwriting and :term:`overwriting + errors `. + +* :dfn:`free space splatting` overwrites recycled space with a pattern + of data. If the pattern is designed so that it does not resemble a + live object (and if code checks the consistency of its data + structues), then this helps to detect :term:`dangling pointer` + dereferences. The pattern can also be checked, for example just + before allocation, or when a block of memory is released from the + pool to the arena, to see that it is unchanged. + +The :term:`client program` specifies templates for both of these +features via the :c:type:`mps_pool_debug_option_s` structure. This +allows it to specify patterns: + +* that mimic illegal data values; + +* that cause bus errors if wrongly interpreted as pointers; + +* that cause assertions to fire if wrongly interpreted as data values; + +* that contain an instruction sequence that wold cause the program to + signal an error or stop if wrongly interpreted as executable code. + +For example:: + + mps_pool_debug_option_s debug_options = { (void *)"postpost", 8, (void *)"freefree", 8, }; - if (mps_pool_create(&pool, arena, mps_class_ams_debug(), - &debugOptions, 8192, 135, 8) - != MPS_RES_OK) - { - printf("Error creating pool!"); - exit(2); - } - - -Interface ---------- - -.. c:function:: void mps_pool_check_fenceposts(mps_pool_t pool) - - Check all the :term:`fenceposts ` in a :term:`pool`. - - ``pool`` is the pool whose fenceposts are to be checked. - - If a corrupted fencepost is found, the MPS will :term:`assert - `. It is only useful to call this on a :term:`debugging - pool` that has fenceposts turned on. It does nothing on - non-debugging pools. - - -.. c:function:: void mps_pool_check_free_space(mps_pool_t mps_pool) - - Check all the free space in a :term:`pool` for :term:`overwriting - errors ` - - ``pool`` is the pool whose free space is to be checked. - - If corrupted free space is found, the MPS will :term:`assert - `. It is only useful to call this on a :term:`debugging - pool` that has free space splatting turned on. It does nothing on - non-debugging pools. + mps_pool_t pool; + mps_res_t res; + res = mps_pool_create(&pool, arena, mps_class_ams_debug(), + &debug_options, &fmt, &chain) + if (res != MPS_RES_OK) error("can't create debug pool"); .. c:type:: mps_pool_debug_option_s @@ -89,17 +89,27 @@ Interface pieces smaller than the given size, for example to pad out part of a block that was left unused because of alignment requirements. - Fencepost and free space templates allow the :term:`client - program` to specify patterns: - * that mimic illegal data values; - - * that cause bus errors if wrongly interpreted as pointers; +.. c:function:: void mps_pool_check_fenceposts(mps_pool_t pool) - * that cause assertions to fire if wrongly interpreted as data values; + Check all the :term:`fenceposts ` in a :term:`pool`. - * that contain an instruction sequence that wold cause the program - to signal an error or stop if wrongly interpreted as executable - code. + ``pool`` is the pool whose fenceposts are to be checked. + + If a corrupted fencepost is found, the MPS will :term:`assert + `. It is only useful to call this on a :term:`debugging + pool` that has fenceposts turned on. It does nothing on + non-debugging pools. +.. c:function:: void mps_pool_check_free_space(mps_pool_t mps_pool) + + Check all the free space in a :term:`pool` for :term:`overwriting + errors ` + + ``pool`` is the pool whose free space is to be checked. + + If corrupted free space is found, the MPS will :term:`assert + `. It is only useful to call this on a :term:`debugging + pool` that has free space splatting turned on. It does nothing on + non-debugging pools. diff --git a/mps/manual/source/topic/pattern.rst b/mps/manual/source/topic/pattern.rst index ca7927fe1bd..774b38af0bc 100644 --- a/mps/manual/source/topic/pattern.rst +++ b/mps/manual/source/topic/pattern.rst @@ -7,7 +7,7 @@ Allocation patterns =================== -An :dfb:`allocation pattern` is a hint to the MPS to expect a +An :dfn:`allocation pattern` is a hint to the MPS to expect a particular pattern of allocation on an :term:`allocation point`. The MPS may use this hint to schedule its decisions as to when and what to collect. @@ -85,6 +85,8 @@ collect. This function may be used to recover from error conditions. +.. _topic-pattern-ramp: + Ramp allocation ---------------