From 72af2df070c1dfd13732ffbd6018256f11740b74 Mon Sep 17 00:00:00 2001 From: Gareth Rees Date: Wed, 17 Oct 2012 10:26:25 +0100 Subject: [PATCH] Document the persistence of data structures based on reading the code. Copied from Perforce Change: 179909 ServerID: perforce.ravenbrook.com --- mps/manual/source/notes.txt | 102 ++++++++++++++------------ mps/manual/source/reference/index.rst | 28 +++++++ 2 files changed, 85 insertions(+), 45 deletions(-) diff --git a/mps/manual/source/notes.txt b/mps/manual/source/notes.txt index 1d0e2eb8c9a..7c2405cdc3a 100644 --- a/mps/manual/source/notes.txt +++ b/mps/manual/source/notes.txt @@ -1,18 +1,18 @@ TODO 2. Create new types of objects for pools and topics. - - 3. Glossary entries need permalinks. See + + 3. Glossary entries need permalinks. See - + 5. Fix the general index so that (1) aren't interpreted as subentries. - + 7. Re-do the diagrams in vector form and using the colour palette. - + 8. Use a better bibliography extension. See for example - + 9. Hyphenate long function names across line endings (but what if you copy them?) @@ -22,53 +22,33 @@ TODO QUERIES - 1. Does the object format description (struct mps_fmt_A_s etc) have - to be static? Is it OK to throw it away after calling - mps_fmt_create? - - Same question for the generation structure (mps_gen_param_s)? - 2. What is the difference, if any, between mps_word_t and MPS_T_WORD? - + 3. How can I explain why the Scheme example uses sizeof(mps_word_t) as its alignment? Why not MPS_PF_ALIGN (or are client programs not supposed to look at mpstd.h)? Why not something of its own manufacture, like sizeof(union {long, size_t, void*})? - - 4. Why does the Scheme example have a copy method in its object - format when the reference manual says it's obsolete? - I removed it. - 5. What is the difference between the "event stream" and the "telemetry stream"? Are these names for the same thing? Or is there a distinction (for example, "event stream" refers to the internal, unfiltered, stream of events and "telemetry stream" refers to the filtered stream)? - + 6. The location dependency functions all take an arena as an argument. What is the role of this argument? - + 7. What is the role of the third (addr) argument to mps_ld_isstale? LDIsStale says "UNUSED(addr);" so maybe it is unused. - + 8. Is the material in the pool class comparison table at all accurate? - - 9. This code seems a bit confused about what to do: - - assert(0); - fprintf(stderr, "Unexpected object on the heap\n"); - abort(); - return MPS_RES_FAIL; - - I took out the assertion and the return. 10. How does fixing interact with tagged references? Do I need to remove the tag before fixing a reference? Do I need to restore the tag afterwards? I thought that both would be necessary but the critical path documentation has an example from OpenDylan with tagged references that does neither: - + 11. This code from mps_chat in the Scheme example is wrong: @@ -86,18 +66,10 @@ QUERIES ... Collection 47 started. ... - Collection 47 started. - -12. It seems "tricky" to re-use fowarding objects as padding objects - by setting their forwarding pointer to NULL. It would be simpler - to explain if we had TYPE_PAD for multiple-word padding objects. - There's enough to explain as it is! - - I made this change. 13. The Scheme example says, "Adapting it to use the MPS took approximately two hours". I doubt this would be the common case, - and it would be better to under-promise and over-deliver. + and it would be better to under-promise here and over-deliver. 14. I need to document the values in mps_gen_param_s. I believe they are the capacity (size of the generation in kilobytes) and the @@ -106,13 +78,53 @@ QUERIES MPS? And how should one go about choosing values? -DONE +TODO DONE -1. Create a new domain - + 1. Create a new domain + -4. Make (1), (2) etc into superscripts + 4. Make (1), (2) etc into superscripts -6. Identify :term: references that point to "see" cross-references. + 6. Identify :term: references that point to "see" cross-references. 10. Pluralize "Topic" to "Topics" and so on. + + +ANSWERED QUERIES + + 1. Does the object format description (mps_fmt_A_s etc) have to be + static as in the Scheme example? Or is it OK to throw it away + after calling mps_fmt_create? + + Same question for the generation structure (mps_gen_param_s) for a + pool and the size classes (mps_sac_class_s) for a segregated + allocation cache? + + ANSWER: examination of the code shows that all of these structure + are copied into internally allocated MPS control structures, and + so it is OK for the client program to put these structures on the + stack otherwise dispose of them. + + 4. Why does the Scheme example have a copy method in its object + format when the reference manual says it's obsolete? + + ANSWER: It wasn't obsolete when it was written. I removed it. + + 9. This code seems a bit confused about what to do: + + assert(0); + fprintf(stderr, "Unexpected object on the heap\n"); + abort(); + return MPS_RES_FAIL; + + What should it say? + + ANSWER: the assertion and the return seem to be bogus, so I + removed them. + +12. It seems "tricky" to re-use fowarding objects as padding objects + by setting their forwarding pointer to NULL. Wouldn't it be + simpler to explain if we had TYPE_PAD for multiple-word padding + objects? Things are difficult enough to explain as it is! + + ANSWER: It would be simpler, so I made this change. diff --git a/mps/manual/source/reference/index.rst b/mps/manual/source/reference/index.rst index 2e2fa4b78d7..f94b6ee2049 100644 --- a/mps/manual/source/reference/index.rst +++ b/mps/manual/source/reference/index.rst @@ -461,6 +461,9 @@ Declared in ``mps.h`` Returns :c:macro:`MPS_RES_OK` if the arena is created successfully, or another :term:`result code` otherwise. + The arena persists until it is destroyed by calling + :c:func:`mps_arena_destroy`. + .. topics:: :ref:`topic-arena`. @@ -1203,6 +1206,11 @@ Declared in ``mps.h`` some resource in the course of :c:func:`mps_fmt_create_A` and will return an appropriate :term:`result code` if so. + After this function returns, the object format description pointed + to be *fmt_A* is no longer needed and may be discarded. The object + format pointed to by *fmt_o* persists until it is destroyed by + calling :c:func:`mps_fmt_destroy`. + .. topics:: :ref:`topic-format`. @@ -2438,6 +2446,9 @@ Declared in ``mps.h`` description could not be allocated, or another :term:`result code` if there was another error. + The registered root destription persists until it is destroyed by + calling :c:func:`mps_root_destroy`. + .. topics:: :ref:`topic-root`. @@ -2471,6 +2482,9 @@ Declared in ``mps.h`` description could not be allocated, or another :term:`result code` if there was another error. + The registered root destription persists until it is destroyed by + calling :c:func:`mps_root_destroy`. + .. topics:: :ref:`topic-root`. @@ -2512,6 +2526,9 @@ Declared in ``mps.h`` description could not be allocated, or another :term:`result code` if there was another error. + The registered root destription persists until it is destroyed by + calling :c:func:`mps_root_destroy`. + .. topics:: :ref:`topic-root`. @@ -2547,6 +2564,9 @@ Declared in ``mps.h`` description could not be allocated, or another :term:`result code` if there was another error. + The registered root destription persists until it is destroyed by + calling :c:func:`mps_root_destroy`. + .. topics:: :ref:`topic-root`. @@ -2579,6 +2599,9 @@ Declared in ``mps.h`` description could not be allocated, or another :term:`result code` if there was another error. + The registered root destription persists until it is destroyed by + calling :c:func:`mps_root_destroy`. + .. topics:: :ref:`topic-root`. @@ -2851,6 +2874,11 @@ Declared in ``mps.h`` small adjacent classes. Returns :c:macro:`MPS_RES_PARAM` if the pool doesn't support segregated allocation caches. + After this function returns, the array of size classes pointed to + be *classes* is no longer needed and may be discarded. The + segregated allocation cache pointed to by *sac_o* persists until + it is destroyed by calling :c:func:`mps_sac_destroy`. + This function creates an allocation cache whose :term:`free list` is segregated into the given size classes. The cache can get more memory from the given pool, or return memory to it.