diff --git a/mps/manual/source/extensions/mps.py b/mps/manual/source/extensions/mps.py index e69111e1ddd..5a177fcf79d 100644 --- a/mps/manual/source/extensions/mps.py +++ b/mps/manual/source/extensions/mps.py @@ -167,34 +167,33 @@ all_admonitions = [ SpecificDirective, TopicsDirective] -see_only_ids = set() -xref_ids = defaultdict(list) - class GlossaryTransform(transforms.Transform): + """ + Make transformations to a document that affect the way it refers + to glossary entries: + + 1. Change parenthesized sense numbers (1), (2) etc. to + superscripts in glossary entries and cross-references to + glossary entries. + + 2. Record glossary entries that consist only of "See: XREF" so + that cross-references to them can be reported by + `warn_indirect_terms` once the build is completed. + + 3. Add "term" cross-reference targets for plurals. + """ + + # These are shared between all instances of the class. + see_only_ids = set() + xref_ids = defaultdict(list) default_priority = 999 sense_re = re.compile(r'(.*)\s+(\([0-9]+\))$') - def apply(self): - global see_only_ids, xref_ids - for target in self.document.traverse(nodes.term): - target.children = list(self.edit_children(target)) - for target in self.document.traverse(addnodes.pending_xref): - if target['reftype'] == 'term': - xref_ids['term-{}'.format(target['reftarget'])].append((target.source, target.line)) - c = target.children - if len(c) == 1 and isinstance(c[0], nodes.emphasis): - c[0].children = list(self.edit_children(c[0])) - for target in self.document.traverse(nodes.definition_list_item): - ids = set() - for c in target.children: - if isinstance(c, nodes.term): - ids = set(c['ids']) - if (isinstance(c, nodes.definition) - and len(c.children) == 1 - and isinstance(c.children[0], see)): - see_only_ids |= ids - - def edit_children(self, target): + def superscript_children(self, target): + """ + Edit the children of `target`, changing parenthesized sense + numbers (1), (2) etc. to superscripts. + """ for e in target.children: if not isinstance(e, nodes.Text): yield e @@ -206,10 +205,64 @@ class GlossaryTransform(transforms.Transform): yield nodes.Text(m.group(1)) yield nodes.superscript(text = m.group(2)) + def apply(self): + # Change parenthesized sense numbers to superscripts in + # glossary entries. + for target in self.document.traverse(nodes.term): + target.children = list(self.superscript_children(target)) + + # Change parenthesized sense numbers to superscripts in + # cross-references to glossary entries. + for target in self.document.traverse(addnodes.pending_xref): + if target['reftype'] == 'term': + self.xref_ids['term-{}'.format(target['reftarget'])].append((target.source, target.line)) + c = target.children + if len(c) == 1 and isinstance(c[0], nodes.emphasis): + c[0].children = list(self.superscript_children(c[0])) + + # Record glossary entries consisting only of "See: XREF". + for target in self.document.traverse(nodes.definition_list_item): + ids = set() + for c in target.children: + if isinstance(c, nodes.term): + ids = set(c['ids']) + if (isinstance(c, nodes.definition) + and len(c.children) == 1 + and isinstance(c.children[0], see)): + self.see_only_ids |= ids + + # Add cross-reference targets for plurals. + objects = self.document.settings.env.domaindata['std']['objects'] + endings = [(l, l + 's') for l in 'abcedfghijklmnopqrtuvwxz'] + endings.extend([ + ('ss', 'sses'), + ('ing', 'ed'), + ('y', 'ies'), + ('e', 'ed'), + ('', 'ed'), + ]) + for (name, fullname), value in objects.items(): + if name != 'term': + continue + m = self.sense_re.match(fullname) + if m: + old_fullname = m.group(1) + sense = ' ' + m.group(2) + else: + old_fullname = fullname + sense = '' + if any(old_fullname.endswith(e) for _, e in endings): + continue + for old_ending, new_ending in endings: + if not old_fullname.endswith(old_ending): + continue + new_fullname = '{}{}{}'.format(old_fullname[:len(old_fullname) - len(old_ending)], new_ending, sense) + objects[(name, new_fullname)] = value + def warn_indirect_terms(app, exception): if not exception: - for i in see_only_ids: - for doc, line in xref_ids[i]: + for i in GlossaryTransform.see_only_ids: + for doc, line in GlossaryTransform.xref_ids[i]: print('Warning: cross-reference to {} at {} line {}.'.format(i, doc, line)) def setup(app): diff --git a/mps/manual/source/glossary/a.rst b/mps/manual/source/glossary/a.rst index 3cb0d034d51..ddfc190ff83 100644 --- a/mps/manual/source/glossary/a.rst +++ b/mps/manual/source/glossary/a.rst @@ -30,10 +30,10 @@ Memory Management Glossary: A In a register-based hardware architecture, the current activation record is typically partially stored in registers. - :term:`Closures ` and :term:`continuations - ` are specializations of activation records in - support of particular language features of :term:`LISP`, - :term:`Scheme` and related languages. + :term:`Closures` and :term:`continuations` are specializations + of activation records in support of particular language + features of :term:`LISP`, :term:`Scheme` and related + languages. .. relevance:: @@ -86,9 +86,9 @@ Memory Management Glossary: A address space - An *address space* is the set of possible :term:`addresses -
`. It can also be considered to be a partial function - from addresses to :term:`locations `. + An *address space* is the set of possible :term:`addresses`. + It can also be considered to be a partial function from + addresses to :term:`locations `. Typically, addresses start at zero and run to 2\ :sup:`n`\ −1, where *n* is the address width (for example, 15, 16, 24, 32, @@ -122,9 +122,9 @@ Memory Management Glossary: A aging space In some :term:`generational garbage collection` systems, when - :term:`generations ` are divided into - :term:`buckets `, the aging space is where - :term:`objects ` which survive a :term:`collection + :term:`generations` are divided into + :term:`buckets`, the aging space is where + :term:`objects` which survive a :term:`collection cycle` stay until they are old enough to be :term:`promoted `. @@ -170,7 +170,7 @@ Memory Management Glossary: A A memory manager must take care to :term:`allocate` memory with an appropriate alignment for the object that is going to be stored there. Implementations of :term:`malloc` have - to allocate all :term:`blocks ` at the largest + to allocate all :term:`blocks` at the largest alignment that the processor architecture requires. Other reasons for aligning objects include using the least significant bits of the address for a :term:`tag`. @@ -205,16 +205,15 @@ Memory Management Glossary: A program. Allocation is rarely a simple issue. For example, programs - usually allocate :term:`activation records ` (:term:`automatic variables `, and so on) for functions from a processor - :term:`stack` simply by subtracting a number from their stack - :term:`pointer`. However, in a :term:`virtual memory` - system, this may extend the stack onto a previously unused - :term:`page`, in which case the operating system memory - manager must carry out some quite complex operations in order - to supply the program with :term:`backing store` for the stack - so that the program can continue. + usually allocate :term:`activation records` (:term:`automatic + variables `, and so on) for + functions from a processor :term:`stack` simply by subtracting + a number from their stack :term:`pointer`. However, in a + :term:`virtual memory` system, this may extend the stack onto + a previously unused :term:`page`, in which case the operating + system memory manager must carry out some quite complex + operations in order to supply the program with :term:`backing + store` for the stack so that the program can continue. .. historical:: @@ -278,10 +277,10 @@ Memory Management Glossary: A .. mps:specific:: An allocation point is an interface to a :term:`pool` - which provides fast :term:`buffered ` allocation, - and defers the need for synchronization in a - multi-threaded environment. Allocation points belong to - the type :c:type:`mps_ap_t`. + which provides fast :term:`buffered` allocation, and + defers the need for synchronization in a multi-threaded + environment. Allocation points belong to the type + :c:type:`mps_ap_t`. allocation point protocol @@ -317,8 +316,8 @@ Memory Management Glossary: A patterns of allocation requests to justify an :term:`allocation policy`. - For instance, "do not allow small long-lived :term:`objects - ` to fragment large :term:`free (3)` areas", "allocate + For instance, "do not allow small long-lived :term:`objects` + to fragment large :term:`free (3)` areas", "allocate consecutive objects close together", and so on. The allocation strategy motivates an :term:`allocation policy`, which is implemented by an :term:`allocation mechanism`. @@ -354,7 +353,7 @@ Memory Management Glossary: A ambiguous root An ambiguous root is a :term:`root` containing - :term:`ambiguous references `. + :term:`ambiguous references`. .. opposite:: :term:`exact root`. @@ -378,7 +377,7 @@ Memory Management Glossary: A An arena is the data structure responsible for requesting :term:`memory (3)` from the operating system, making it - available to :term:`pools `, and for :term:`garbage + available to :term:`pools`, and for :term:`garbage collection`. Arenas belong to the type :c:type:`mps_arena_t`. See :ref:`topic-arena`. @@ -387,9 +386,8 @@ Memory Management Glossary: A .. mps:specific:: A value of type :c:type:`mps_arena_class_t` describing a - class of :term:`arenas `. Arena classes include - :term:`client arenas ` and :term:`virtual - memory arenas `. + class of :term:`arenas`. Arena classes include + :term:`client arenas` and :term:`virtual memory arenas`. assertion @@ -400,7 +398,7 @@ Memory Management Glossary: A .. mps:specific:: Memory management mistakes often lead to - :term:`overwriting errors ` that + :term:`overwriting errors` that corrupt the data structures used by the memory manager to maintain memory. Except in the :term:`rash` :term:`variety`, most MPS functions assert the validity of @@ -416,8 +414,7 @@ Memory Management Glossary: A collector will run. This means that the mutator must ensure that :term:`formatted - objects ` are always :term:`scannable - `. + objects` are always :term:`scannable `. .. opposite:: :term:`synchronous garbage collector`. @@ -436,7 +433,7 @@ Memory Management Glossary: A :term:`memory (2)`. It is not possible, in general, to automatically determine - which :term:`objects ` are still :term:`live`. Even if + which :term:`objects` are still :term:`live`. Even if it didn't depend on future input, there can be no general algorithm to prove that an object is live (cf. the Halting Problem). However, effective approximations are possible. @@ -444,10 +441,10 @@ Memory Management Glossary: A In :term:`tracing garbage collection`, the approximation is that an object can't be live unless it is :term:`reachable`. In :term:`reference counting`, the approximation is that an - object can't be live unless it is :term:`referenced - `. Analysis of the program text can reveal where - objects :term:`die `; A notable technique in this vein - is :term:`region inference`. + object can't be live unless it is :term:`referenced`. Analysis + of the program text can reveal where objects :term:`die + `; A notable technique in this vein is :term:`region + inference`. Hybrid algorithms are also possible. @@ -457,14 +454,14 @@ Memory Management Glossary: A automatic storage duration - In :term:`C`, :term:`objects ` that are declared with + In :term:`C`, :term:`objects` that are declared with *automatic storage duration* are :term:`live` for the duration of a block of code. In most implementations of C, objects with automatic storage - duration are :term:`allocated ` on the :term:`stack` - when a function is entered, and :term:`deallocated ` - when it returns. + duration are :term:`allocated` on the :term:`stack` when a + function is entered, and :term:`deallocated ` when + it returns. .. similar:: :term:`stack allocation`, :term:`dynamic extent`. diff --git a/mps/manual/source/glossary/b.rst b/mps/manual/source/glossary/b.rst index dfcf4186cd4..ad280d06265 100644 --- a/mps/manual/source/glossary/b.rst +++ b/mps/manual/source/glossary/b.rst @@ -84,7 +84,7 @@ Memory Management Glossary: B Note that in [BC92A]_, Boehm and Chase define "base pointer" to be "any pointer value directly recognizable by the :term:`collector (1)`", and this may well include - :term:`interior pointers `. + :term:`interior pointers`. .. opposite:: :term:`derived pointer`. @@ -92,12 +92,11 @@ Memory Management Glossary: B The :term:`allocation policy` that always allocates from the smallest suitable :term:`free block`. Suitable - :term:`allocation mechanisms ` include - :term:`sequential fit` searching for a :term:`perfect fit`, - :term:`first fit` on a size-ordered :term:`free block chain`, - :term:`segregated fits `, and :term:`indexed - fits `. Many :term:`good fit` allocators are also - described as :term:`best fit`. + :term:`allocation mechanisms` include :term:`sequential fit` + searching for a :term:`perfect fit`, :term:`first fit` on a + size-ordered :term:`free block chain`, :term:`segregated + fits`, and :term:`indexed fits`. Many :term:`good fit` + allocators are also described as :term:`best fit`. In theory, best fit may exhibit bad :term:`fragmentation`, but in practice this is not commonly observed. @@ -120,7 +119,7 @@ Memory Management Glossary: B BIBOP requires storing only objects of the same type in a block, but this has the same advantages as :term:`segregated - fits ` in general. + fits` in general. .. historical:: @@ -172,20 +171,20 @@ Memory Management Glossary: B Bitmaps are sometimes used to represent the marks in a :term:`mark-sweep` collector, or the used memory in a - :term:`bitmapped fits ` :term:`allocator`. + :term:`bitmapped fits` :term:`allocator`. bitmapped fit - A class of :term:`allocation mechanisms ` that use a :term:`bitmap` to represent the usage - of the :term:`heap`. Each bit in the map corresponds to a part - of the heap, typically a :term:`word`, and is set if that part - is in use. Allocation is done by searching the bitmap for a - run of clear bits. + A class of :term:`allocation mechanisms` that use a + :term:`bitmap` to represent the usage of the :term:`heap`. + Each bit in the map corresponds to a part of the heap, + typically a :term:`word`, and is set if that part is in use. + Allocation is done by searching the bitmap for a run of clear + bits. - Bitmapped fit mechanisms have good :term:`locality `, as they avoid examining :term:`in-band headers - ` when allocating. + Bitmapped fit mechanisms have good :term:`locality of + reference`, as they avoid examining :term:`in-band headers` + when allocating. .. seealso:: :term:`allocation mechanism`, :term:`sequential fit`, :term:`indexed fit`. @@ -202,8 +201,8 @@ Memory Management Glossary: B black - In a :term:`tri-color marking` scheme, black :term:`objects - ` are objects that have been :term:`scanned `. + In a :term:`tri-color marking` scheme, black :term:`objects` + are objects that have been :term:`scanned `. More precisely, black objects have been noted :term:`reachable` and the :term:`collector (2)` has finished @@ -217,14 +216,13 @@ Memory Management Glossary: B A :term:`conservative garbage collector ` can be made more effective by *blacklisting* - values which resemble :term:`addresses
` that may be - :term:`allocated ` at in the future, but are known - not to be :term:`pointers ` . This list is then used - to avoid allocation at those addresses. + values which resemble :term:`addresses` that may be + :term:`allocated` at in the future, but are known not to be + :term:`pointers` . This list is then used to avoid allocation + at those addresses. For example, such values can be gathered by scanning the - :term:`roots ` before any :term:`objects ` have - been allocated. + :term:`roots` before any :term:`objects` have been allocated. .. bibref:: [BOEHM93]_. @@ -232,14 +230,14 @@ Memory Management Glossary: B Block is a vague term for an (often contiguous) area of :term:`memory (1)`. Often used to describe :term:`memory (2)` - :term:`allocated ` by an :term:`allocator` such as + :term:`allocated` by an :term:`allocator` such as :term:`malloc`. .. mps:specific:: The term *block* is used as a general term for a unit of allocation, with *object* being reserved for - :term:`formatted objects `. + :term:`formatted objects`. bounds error @@ -247,13 +245,13 @@ Memory Management Glossary: B boxed - Boxed :term:`objects ` are represented by a - :term:`pointer` to a :term:`block` of :term:`memory (2)` that - contains the object data. Sometimes the pointer is - :term:`tagged ` to distinguish it from an :term:`unboxed` - object, or to represent its type. Only the pointer is - duplicated when the object is passed around, so updates to the - object are reflected everywhere. + Boxed :term:`objects` are represented by a :term:`pointer` to + a :term:`block` of :term:`memory (2)` that contains the object + data. Sometimes the pointer is :term:`tagged ` to + distinguish it from an :term:`unboxed` object, or to represent + its type. Only the pointer is duplicated when the object is + passed around, so updates to the object are reflected + everywhere. .. opposite:: :term:`unboxed`. @@ -275,7 +273,7 @@ Memory Management Glossary: B segment. This limit is known as the *break*. The :term:`C` library implementation of :term:`malloc` usually - :term:`allocates ` :term:`memory (2)` for the + :term:`allocates` :term:`memory (2)` for the :term:`heap` by extending the data segment using ``brk`` or :term:`sbrk`. @@ -294,7 +292,7 @@ Memory Management Glossary: B :term:`Copying garbage collectors ` :term:`move ` - :term:`reachable` :term:`objects ` into another + :term:`reachable` :term:`objects` into another :term:`semi-space`. They leave a :term:`forwarding pointer` in the old :term:`location `, pointing to the new. The object at the old location is known as a broken @@ -306,7 +304,7 @@ Memory Management Glossary: B In a :term:`generational garbage collector `, it is often desirable to divide - :term:`generations ` by the age of the + :term:`generations` by the age of the :term:`object`. These divisions are known as buckets. .. seealso:: :term:`generational garbage collection`, :term:`aging space`, :term:`creation space`. @@ -314,12 +312,12 @@ Memory Management Glossary: B buddy system Buddy systems are a subclass of :term:`strict segregated fit` - :term:`allocation mechanisms ` which + :term:`allocation mechanisms` which make :term:`splitting ` and :term:`coalescing ` fast by pairing each block with a unique adjacent *buddy* block. - There is an array of :term:`free lists `, one for + There is an array of :term:`free lists`, one for each allowable block size. Allocation rounds up the requested size to an allowable size and allocates from the corresponding free list. If the free list is empty, a larger block is @@ -341,29 +339,28 @@ Memory Management Glossary: B :term:`Fibonacci buddies`, :term:`weighted buddies`, and :term:`double buddies`. - .. seealso:: :term:`allocation mechanism`, :term:`segregated free lists `, :term:`segregated fit`, :term:`strict segregated fit`. + .. seealso:: :term:`allocation mechanism`, :term:`segregated free lists`, :term:`segregated fit`, :term:`strict segregated fit`. .. bibref:: [WIL95]_. buffer A *buffer* is a large :term:`block` of :term:`memory (2)` from - which blocks are :term:`allocated ` contiguously, as - a simple technique for fast :term:`allocation `. + which blocks are :term:`allocated` contiguously, as a simple + technique for fast :term:`allocation `. By keeping only a *high-water* mark (that is, a :term:`pointer` to the start of unused memory), the buffer - technique avoids expensive :term:`in-band headers ` and the searching of :term:`free block chains `. Buffers tend to, however, lead to - :term:`external fragmentation`. + technique avoids expensive :term:`in-band headers` and the + searching of :term:`free block chains`. Buffers tend to, + however, lead to :term:`external fragmentation`. .. bibref:: [AEL88]_. .. mps:specific:: - Buffers are implemented using :term:`allocation points - ` attached to :term:`pools `. + Buffers are implemented using :term:`allocation points` + attached to :term:`pools`. bus error @@ -404,8 +401,8 @@ Memory Management Glossary: B .. historical:: - The PDP-10 had 36-bit :term:`words `, and defined - "byte" to be a general sub-:term:`word` bit-field: compare + The PDP-10 had 36-bit :term:`words`, and defined "byte" to + be a general sub-:term:`word` bit-field: compare :term:`byte (3)`. On this machine it was commonplace for characters to be packed four or five to a word using 9- or 7-bit bytes respectively. diff --git a/mps/manual/source/glossary/c.rst b/mps/manual/source/glossary/c.rst index 6f3ef98d913..b48cc31d34e 100644 --- a/mps/manual/source/glossary/c.rst +++ b/mps/manual/source/glossary/c.rst @@ -100,12 +100,11 @@ Memory Management Glossary: C diagrammed, its shape resembles that of a `saguaro cactus `_. - In languages that support :term:`continuations - `, :term:`activation records ` can have :term:`indefinite extent`. One technique for - implementing continuations is not to copy the activation - records that are captured, but rather to create a fork in the - stack below the captured :term:`stack frames `, + In languages that support :term:`continuations`, + :term:`activation records` can have :term:`indefinite extent`. + One technique for implementing continuations is not to copy + the activation records that are captured, but rather to create + a fork in the stack below the captured :term:`stack frames`, so that new frames appear as a parallel branch. Often the process of forking is done lazily: captured frames are only duplicated if they are modified. @@ -115,22 +114,21 @@ Memory Management Glossary: C A card is a division of memory, all cards being of equal size (in a particular area of discourse). A card is usually bigger than a :term:`word` and smaller than a :term:`page`. Cards are - used in a technique called :term:`card-marking ` - whereby :term:`dirty bits ` (which record which - portions of old generations have been written into) are - maintained for each card. Often the use of cards will also - entail the use of a :term:`crossing map`. + used in a technique called :term:`card marking` whereby + :term:`dirty bits` (which record which portions of old + generations have been written into) are maintained for each + card. Often the use of cards will also entail the use of a + :term:`crossing map`. card marking - A technique for managing :term:`pointer` :term:`stores ` into old :term:`generations ` (which in turn - is used to track :term:`inter-generational pointers - `). Each generation is divided - into a number of equal-sized :term:`cards `, and when a + A technique for managing :term:`pointer` :term:`stores (1)` + into old :term:`generations` (which in turn is used to track + :term:`inter-generational pointers`). Each generation is + divided into a number of equal-sized :term:`cards`, and when a generation is written into, the particular card written to is - recorded (often by using a :term:`bitmap`). Subsequently, - when :term:`scanning ` an older generation in order to + recorded (often by using a :term:`bitmap`). Subsequently, when + :term:`scanning ` an older generation in order to collect a younger generation, only the recorded cards (in the old generation) need to be scanned. @@ -146,13 +144,11 @@ Memory Management Glossary: C .. aka:: *Cheney scan*. - A Cheney collector uses the :term:`tospace` of a :term:`two - space collector ` as a queue of objects - remaining to be :term:`scanned `, thus eliminating the - need for recursion when :term:`tracing ` the - :term:`graph` of :term:`objects `. - - .. seealso:: :term:`two space collector `. + A Cheney collector uses the :term:`tospace` of a + :term:`two-space collector` as a queue of objects remaining to + be :term:`scanned `, thus eliminating the need for + recursion when :term:`tracing ` the :term:`graph` of + :term:`objects`. .. bibref:: [CHENEY70]_. @@ -168,10 +164,10 @@ Memory Management Glossary: C others being the :term:`unclamped state` and the :term:`parked state`). In the clamped state, no object motion occurs and the staleness of :term:`location - dependencies ` does not change. - However, a :term:`garbage collection` may be in progress. - Call :c:func:`mps_arena_clamp` to put an arena into the - clamped state. + dependencies` does not change. However, a :term:`garbage + collection` may be in progress. Call + :c:func:`mps_arena_clamp` to put an arena into the clamped + state. client arena @@ -187,9 +183,8 @@ Memory Management Glossary: C A :term:`formatted object` that contains data from the :term:`client program`. One of three types of formatted - objects, the other two being :term:`forwarding objects - ` and :term:`padding objects `. + objects, the other two being :term:`forwarding objects` + and :term:`padding objects`. client program @@ -219,23 +214,22 @@ Memory Management Glossary: C .. relevance:: A closure is typically implemented by saving both the - function and any :term:`activation records ` that contain variables referenced by the - function. The closure creates additional implicit - :term:`references ` to the bindings closed over - and hence must be accounted for in any memory management - scheme. The closure itself is an object that must be - managed and may have either :term:`dynamic extent` or - :term:`indefinite extent` depending on whether it is only - used by inner blocks of the creating block or passed out - of the creating block. + function and any :term:`activation records` that contain + variables referenced by the function. The closure creates + additional implicit :term:`references` to the bindings + closed over and hence must be accounted for in any memory + management scheme. The closure itself is an object that + must be managed and may have either :term:`dynamic extent` + or :term:`indefinite extent` depending on whether it is + only used by inner blocks of the creating block or passed + out of the creating block. .. seealso:: :term:`continuation`. coalesce Coalescing is the act of merging two adjacent :term:`free - blocks `. + blocks`. Coalescing reduces :term:`external fragmentation`, but is not totally effective. @@ -251,8 +245,8 @@ Memory Management Glossary: C collect - An :term:`object` is collected when it is :term:`reclaimed - ` by a :term:`garbage collector`. + An :term:`object` is collected when it is :term:`reclaimed` by + a :term:`garbage collector`. .. similar:: :term:`reclaim`. @@ -269,11 +263,10 @@ Memory Management Glossary: C Each collection cycle includes (not necessarily in strict order) choosing a :term:`condemned set`; :term:`scanning - ` :term:`roots ` and :term:`objects ` that - have not been condemned; :term:`tracing ` the object - graph to find all condemned objects that are - :term:`reachable`; and :term:`reclaiming ` those that - were not reachable. + ` :term:`roots` and :term:`objects` that have not been + condemned; :term:`tracing ` the object graph to find + all condemned objects that are :term:`reachable`; and + :term:`reclaiming ` those that were not reachable. In non-incremental garbage collection, the :term:`mutator` pauses at the start of a collection cycle and cannot continue @@ -290,8 +283,7 @@ Memory Management Glossary: C In a :term:`garbage-collected ` system, the part that executes the garbage collection code, which - discovers unused :term:`memory (1)` and :term:`reclaims - ` it. + discovers unused :term:`memory (1)` and :term:`reclaims` it. For purposes of describing :term:`incremental garbage collection`, the system is divided into the :term:`mutator` @@ -343,7 +335,7 @@ Memory Management Glossary: C .. aka:: *compactifying*. Compaction is the process of :term:`moving ` :term:`live` :term:`objects ` to eliminate + collector>` :term:`live` :term:`objects` to eliminate :term:`dead` space between them. Some people call this *compactifying*, to distinguish it from techniques for compressing data structures. @@ -368,9 +360,8 @@ Memory Management Glossary: C comprehensive A :term:`collector (1)` is *comprehensive* if all - :term:`garbage` (or, all :term:`unreachable` :term:`objects - `) is :term:`reclaimed ` in one - :term:`collection cycle`. + :term:`garbage` (or, all :term:`unreachable` :term:`objects`) + is :term:`reclaimed` in one :term:`collection cycle`. .. seealso:: :term:`garbage collection`. @@ -382,7 +373,7 @@ Memory Management Glossary: C .. aka:: *threatened set*. - *Condemned* :term:`objects ` are those which are + *Condemned* :term:`objects` are those which are candidates for :term:`recycling ` within a :term:`collection cycle`. @@ -390,13 +381,13 @@ Memory Management Glossary: C may choose to condemn some objects (the *condemned set* or *threatened set*) but not to condemn others (the :term:`immune set`). Objects that are not condemned are assumed to be - :term:`live` and behave as :term:`roots ` for the + :term:`live` and behave as :term:`roots` for the purposes of that collection cycle. Many simple :term:`tracing garbage collection` algorithms begin by condemning all objects, but :term:`generational garbage collectors ` will - condemn individual :term:`generations ` or + condemn individual :term:`generations` or combinations of generations. Often young generations are condemned but older ones are not, because objects in older generations are less likely to have become @@ -410,7 +401,7 @@ Memory Management Glossary: C connected - :term:`Objects ` are connected if and only if one + :term:`Objects` are connected if and only if one contains a :term:`reference` to the other. .. seealso:: :term:`graph`. @@ -432,7 +423,7 @@ Memory Management Glossary: C conservative garbage collection In conservative :term:`garbage collection`, the layout of - :term:`objects ` and :term:`roots ` is not + :term:`objects` and :term:`roots` is not known, instead the :term:`collector (1)` assumes that any field that looks like a :term:`pointer` *might* be a :term:`reference`. @@ -450,10 +441,10 @@ Memory Management Glossary: C ` of that object. It can't :term:`move ` objects, because then the references to the moved objects would need to be updated, and such - :term:`ambiguous references ` must not be - modified, in case they weren't pointers after all. Therefore, - conservative collectors are usually :term:`mark-sweep - collectors `. + :term:`ambiguous references` must not be modified, in case + they weren't pointers after all. Therefore, conservative + collectors are usually :term:`mark-sweep collectors + `. Because references are ambiguous, some objects may be retained despite being actually :term:`unreachable`. In practice, this @@ -477,16 +468,14 @@ Memory Management Glossary: C constructor (1) - A constructor is a function or method that :term:`allocates - ` and initializes an :term:`object`. + A constructor is a function or method that :term:`allocates` and initializes an :term:`object`. .. opposite:: :term:`destructor (1)`. constructor (2) In :term:`C++`, a *constructor* is a member function that is - used to initialize a newly-:term:`allocated ` - object. + used to initialize a newly-:term:`allocated` object. The actual allocation of :term:`memory (2)` is performed by ``operator new`` or the compiler (for :term:`static ` have + some) :term:`activation records` have to be :term:`heap-allocated `. .. seealso:: :term:`closure`. @@ -515,13 +504,12 @@ Memory Management Glossary: C .. aka:: *activation stack*, *execution stack*. - A :term:`stack` that stores :term:`activation records - `, particularly subroutine return + A :term:`stack` that stores :term:`activation records`, particularly subroutine return information, is known as a *control stack*. Typically the control stack is supported and used by the hardware architecture and the operating system, limiting the - types and sizes of :term:`objects ` that can be stored + types and sizes of :term:`objects` that can be stored on it. Often, only one type of object, a :term:`stack frame`, is permitted, and the layout of that is defined by the hardware architecture. @@ -567,13 +555,13 @@ Memory Management Glossary: C Copying garbage collection is a kind of :term:`tracing garbage collection` that operates by :term:`relocating ` - :term:`reachable` :term:`objects ` (this is sometimes - called *scavenging*) and then :term:`reclaiming ` - objects that are left behind, which must be - :term:`unreachable` and therefore :term:`dead`. + :term:`reachable` :term:`objects` (this is sometimes called + *scavenging*) and then :term:`reclaiming ` objects + that are left behind, which must be :term:`unreachable` and + therefore :term:`dead`. A copying garbage collection relies on being able to find and - correct all :term:`references ` to copied objects. + correct all :term:`references` to copied objects. .. figure:: ../diagrams/copying.svg :align: center @@ -596,9 +584,9 @@ Memory Management Glossary: C creation space In :term:`generational garbage collection`, when - :term:`generations ` are divided into - :term:`buckets `, the creation space is where new - :term:`objects ` are created in each generation. + :term:`generations` are divided into + :term:`buckets`, the creation space is where new + :term:`objects` are created in each generation. This term is sometimes used as a synonym for :term:`nursery space`. @@ -619,19 +607,18 @@ Memory Management Glossary: C crossing map Where :term:`memory (2)` has already been divided into some - fixed-sized unit (for example, :term:`pages ` or - :term:`cards `), a crossing map records where - :term:`objects ` lie across the boundaries of the + fixed-sized unit (for example, :term:`pages` or + :term:`cards`), a crossing map records where + :term:`objects` lie across the boundaries of the fixed-sized units. In other words, which fixed-sized units do not start with the beginning of an object. - A system which implements :term:`remembered sets ` by :term:`page-marking ` or - :term:`card-marking ` needs to scan all the - :term:`pointers ` in the page or card. If the system - can not :term:`scan` partial objects (or requires information - in the object :term:`header ` in order to scan - a partial object), a crossing map is necessary to find the + A system which implements :term:`remembered sets` by + :term:`page marking` or :term:`card marking` needs to scan all + the :term:`pointers` in the page or card. If the system can + not :term:`scan` partial objects (or requires information in + the object :term:`header ` in order to scan a + partial object), a crossing map is necessary to find the beginning of the first object in the unit. .. relevance:: @@ -643,6 +630,6 @@ Memory Management Glossary: C cyclic data structure - A data structure is cyclic if some of its :term:`references - ` form a loop; that is, there's an :term:`object` - that can be reached by following references from itself. + A data structure is cyclic if some of its :term:`references` + form a loop; that is, there's an :term:`object` that can be + reached by following references from itself. diff --git a/mps/manual/source/glossary/d.rst b/mps/manual/source/glossary/d.rst index 54b122b0cda..76c319bce9a 100644 --- a/mps/manual/source/glossary/d.rst +++ b/mps/manual/source/glossary/d.rst @@ -18,7 +18,7 @@ Memory Management Glossary: D typically arise from one of: 1. A :term:`premature free`, where an object is :term:`freed - `, but a reference is retained; + (1)`, but a reference is retained; 2. Retaining a reference to a :term:`stack-allocated ` object, after the relevant :term:`stack frame` @@ -27,17 +27,17 @@ Memory Management Glossary: D Dangling pointers can occur under :term:`automatic memory management`, because of a :term:`garbage collection` bug (such as premature collection, or :term:`moving ` without updating all :term:`references - `), but this is much rarer because garbage - collection code is usually a single common core of reused - code in which these bugs can be fixed systematically. + collector>` without updating all :term:`references`), but this + is much rarer because garbage collection code is usually a + single common core of reused code in which these bugs can be + fixed systematically. data stack A :term:`stack` used to manage the storage of - :term:`stack-allocated ` :term:`objects - `, other than :term:`activation records `, often under program control. + :term:`stack-allocated ` :term:`objects`, + other than :term:`activation records`, often under program + control. Because of the limitations that may be imposed on the :term:`control stack`, or to support stack-like semantics for @@ -54,11 +54,11 @@ Memory Management Glossary: D when the :term:`mutator` cannot reach any state in which it accesses the object. - It is not possible, in general, for :term:`garbage collectors - ` to determine exactly which :term:`objects - ` are dead and which are live. Instead, they use some - approximation to detect objects that are provably dead, such - as those that are :term:`unreachable`. + It is not possible, in general, for :term:`garbage collectors` + to determine exactly which :term:`objects` are dead and which + are live. Instead, they use some approximation to detect + objects that are provably dead, such as those that are + :term:`unreachable`. .. opposite:: :term:`live`. @@ -74,18 +74,18 @@ Memory Management Glossary: D A :term:`pool` that performs extra checking in order to find errors in the :term:`client program`. It uses - :term:`fenceposts ` to detect - :term:`overwriting errors ` and it + :term:`fenceposts` to detect + :term:`overwriting errors` and it writes patterns over reclaimed blocks in order to detect :term:`use after free ` or missing references during :term:`scanning `. deferred coalescing - Deferred coalescing is a policy which :term:`coalesces - ` :term:`free blocks ` some time after - the blocks are freed, as opposed to coalescing free blocks - immediately as they are freed. + Deferred coalescing is a policy which :term:`coalesces` + :term:`free blocks` some time after the blocks are freed, as + opposed to coalescing free blocks immediately as they are + freed. Adjacent free blocks can be coalesced to form larger free blocks; deferred coalescing is a catch-all for policies which @@ -110,10 +110,10 @@ Memory Management Glossary: D :term:`heap` objects. This requires compiler support, but can lead to substantial performance improvements. - :term:`Objects ` cannot be :term:`reclaimed ` - as soon as their reference count becomes zero, because there - might still be references to them from the stack. Such objects - are added to a :term:`zero count table` (ZCT) instead. If a + :term:`Objects` cannot be :term:`reclaimed ` as soon + as their reference count becomes zero, because there might + still be references to them from the stack. Such objects are + added to a :term:`zero count table` (ZCT) instead. If a reference to an object with a count of zero is stored into the heap, then the object is removed from the ZCT. Periodically the stack is :term:`scanned `, and any objects in the @@ -189,7 +189,7 @@ Memory Management Glossary: D themselves. Direct :term:`garbage collection` can allow :term:`memory (2)` - to be :term:`reclaimed ` as soon as it becomes + to be :term:`reclaimed` as soon as it becomes :term:`unreachable`. However, the stored information must be updated as the :term:`graph` of objects changes; this may be an expensive operation, especially in :term:`distributed @@ -206,18 +206,17 @@ Memory Management Glossary: D A dirty bit is a flag indicating that a :term:`page` (or similar) has been written to since it was last examined. - Dirty bits are used by :term:`caches (2) ` to - determine which pages must be written out, and by garbage - collectors in conjunction with :term:`write barriers `. + Dirty bits are used by :term:`cache (2)` to determine which + pages must be written out, and by garbage collectors in + conjunction with :term:`write barriers`. distributed garbage collection .. aka:: *DGC*. Distributed garbage collection is :term:`garbage collection` - in a system where :term:`objects ` might not reside in - the same :term:`address space` or even on the same machine. + in a system where :term:`objects` might not reside in the same + :term:`address space` or even on the same machine. Distributed garbage collection is difficult to achieve in widely-distributed systems (over wide-area networks) because @@ -238,7 +237,7 @@ Memory Management Glossary: D powers-of-two (for example, 3, 6, 12, …). This resembles :term:`weighted buddies`, but the two buddy systems are treated independently: blocks cannot be :term:`split` or - :term:`coalesced ` from one to the other. + :term:`coalesced` from one to the other. .. bibref:: [WISE78]_. @@ -251,12 +250,12 @@ Memory Management Glossary: D two parts of a program believe they are responsible for the management of the same block. - Many manual :term:`memory managers ` have - great trouble with double frees, because they cannot cheaply - determine that :term:`deallocated ` blocks were - already free. Instead, they corrupt their :term:`free block - chain`, which leads to mysterious problems when the same block - is subsequently :term:`allocated `. + Many manual :term:`memory managers` have great trouble with + double frees, because they cannot cheaply determine that + :term:`deallocated ` blocks were already free. + Instead, they corrupt their :term:`free block chain`, which + leads to mysterious problems when the same block is + subsequently :term:`allocated`. .. seealso:: :term:`premature free`. @@ -265,7 +264,7 @@ Memory Management Glossary: D .. aka:: *longword*. A *doubleword* is a unit of memory consisting of two adjacent - :term:`words `. + :term:`words`. .. historical:: diff --git a/mps/manual/source/glossary/e.rst b/mps/manual/source/glossary/e.rst index 9b5fcad0958..734fe4343f6 100644 --- a/mps/manual/source/glossary/e.rst +++ b/mps/manual/source/glossary/e.rst @@ -15,7 +15,7 @@ Memory Management Glossary: E edge In a :term:`graph`, an edge is a connection between two - :term:`nodes `. + :term:`nodes`. In a directed graph (digraph), edges have a direction; otherwise the start and end nodes are interchangeable. By @@ -35,18 +35,17 @@ Memory Management Glossary: E entry table (1) - An entry table is a table of :term:`references ` - into a set of :term:`objects ` used to indirect + An entry table is a table of :term:`references` + into a set of :term:`objects` used to indirect references from the outside. The Lieberman-Hewitt :term:`collector (1)` represented - references from older :term:`generations ` to - younger ones by indirect pointers through an entry table in - the younger generation that contained the actual - :term:`address` of the young object. This is fairly expensive - without special hardware; other :term:`generational - ` collectors generally use - :term:`remembered sets `. + references from older :term:`generations` to younger ones by + indirect pointers through an entry table in the younger + generation that contained the actual :term:`address` of the + young object. This is fairly expensive without special + hardware; other :term:`generational ` collectors generally use :term:`remembered sets`. .. seealso:: :term:`generational garbage collection`, :term:`exit table`. @@ -56,8 +55,8 @@ Memory Management Glossary: E An entry table is an implementation of a :term:`remembered set`, where, for a given :term:`generation`, there is a list - of :term:`objects ` in older generations which contain - :term:`references ` into that generation. + of :term:`objects` in older generations which contain + :term:`references` into that generation. One could also store the actual :term:`locations ` of the references, which would save time when @@ -72,11 +71,11 @@ Memory Management Glossary: E .. aka:: *precise garbage collection*, *type-accurate garbage collection*. :term:`Garbage collection` is exact (or precise) if it deals - only with :term:`exact references `. + only with :term:`exact references`. An exact :term:`collector (1)` needs to know the - :term:`format` of the :term:`objects ` and the - :term:`roots `, so that it can tell which fields are + :term:`format` of the :term:`objects` and the + :term:`roots`, so that it can tell which fields are references. .. opposite:: :term:`conservative garbage collection`. @@ -98,7 +97,7 @@ Memory Management Glossary: E .. aka:: *precise root*. An exact or precise root is a :term:`root` that contains only - :term:`exact references `. + :term:`exact references`. .. opposite:: :term:`ambiguous root`. @@ -125,8 +124,8 @@ Memory Management Glossary: E exit table - An exit table is a table of all :term:`references ` - from a set of :term:`objects ` to objects outside the + An exit table is a table of all :term:`references` + from a set of :term:`objects` to objects outside the set. .. seealso:: :term:`entry table (1)`, :term:`entry table (2)`. @@ -141,17 +140,17 @@ Memory Management Glossary: E External :term:`fragmentation` is the inability to use :term:`memory (1)` because :term:`free (3)` memory is divided - into many small :term:`blocks `. + into many small :term:`blocks`. - If :term:`live` :term:`objects ` are scattered, the - free blocks cannot be :term:`coalesced `, and hence - no large blocks can be :term:`allocated `. + If :term:`live` :term:`objects` are scattered, the + free blocks cannot be :term:`coalesced`, and hence + no large blocks can be :term:`allocated`. Common solutions to external fragmentation include: 1. :term:`Moving garbage collection `; - 2. :term:`Handles `; + 2. :term:`Handles`; 3. Making all your objects the same size. diff --git a/mps/manual/source/glossary/f.rst b/mps/manual/source/glossary/f.rst index 92a3c44a42d..2746f030fdc 100644 --- a/mps/manual/source/glossary/f.rst +++ b/mps/manual/source/glossary/f.rst @@ -12,8 +12,7 @@ Memory Management Glossary: F fence post A fencepost is spare :term:`memory (1)` between - :term:`allocated ` :term:`blocks ` for - checking purposes. + :term:`allocated` :term:`blocks` for checking purposes. Some :term:`memory management` systems leave spare memory between allocated blocks and store special values in it. If a @@ -67,7 +66,7 @@ Memory Management Glossary: F FIFO-ordered first fit The :term:`allocation policy` that always uses the - least-recently :term:`freed ` suitable :term:`free + least-recently :term:`freed (1)` suitable :term:`free block`. Commonly implemented by adding freed blocks to the end of a :term:`free block chain`, and then using :term:`first fit` allocation on this chain. :term:`free (1)` can be very @@ -93,7 +92,7 @@ Memory Management Glossary: F In :term:`garbage-collected ` languages, it is often necessary to perform actions on some - :term:`objects ` after they are no longer in use and + :term:`objects` after they are no longer in use and before their :term:`memory (2)` can be :term:`recycled `. These actions are known as *finalization* or *termination*. @@ -114,8 +113,7 @@ Memory Management Glossary: F 5, and :term:`Smalltalk`. The term *finalization* is sometimes used to refer to the use - of :term:`destructors `, for example in - Ada. + of :term:`destructors (1)`, for example in Ada. .. mps:specific:: See :ref:`topic-finalization`. @@ -143,14 +141,13 @@ Memory Management Glossary: F free list. The first fit mechanism provides a class of first fit - :term:`allocation policies `, depending on - the order in which the free list is stored. - :term:`Address-ordered first fit` stores the list in order of - (usually increasing) address. :term:`LIFO-ordered first fit` - puts blocks on the front of the free list when they are - :term:`freed `. :term:`FIFO-ordered first fit` puts - blocks on the end of the free list when they are :term:`freed - `. + :term:`allocation policies`, depending on the order in which + the free list is stored. :term:`Address-ordered first fit` + stores the list in order of (usually increasing) address. + :term:`LIFO-ordered first fit` puts blocks on the front of the + free list when they are :term:`freed (1)`. :term:`FIFO-ordered + first fit` puts blocks on the end of the free list when they + are :term:`freed (1)`. .. seealso:: :term:`address-ordered first fit`, :term:`LIFO-ordered first fit`, :term:`FIFO-ordered first fit`, :term:`sequential fit`, :term:`next fit`, :term:`best fit`, :term:`worst fit`. @@ -171,7 +168,7 @@ Memory Management Glossary: F flip The instant in a :term:`two-space collector` when the roles of - the two :term:`semi-spaces ` are reversed. What + the two :term:`semi-spaces` are reversed. What was the :term:`tospace` is now marked as :term:`fromspace` and :term:`condemned `. What was the fromspace becomes the site for all new :term:`allocations @@ -188,7 +185,7 @@ Memory Management Glossary: F floating garbage Floating garbage is :term:`garbage` that is not - :term:`recycled ` promptly due to some approximation + :term:`recycled` promptly due to some approximation or optimization in the :term:`garbage collector`. Floating garbage results from conservatively estimating an @@ -245,9 +242,8 @@ Memory Management Glossary: F program, or the MPS), which is not aware of and does not co-operate with the MPS. The client program must take care that foreign code is not passed the address of a block in - a :term:`moving ` :term:`pools - `, or which contain references to blocks in moving - pools. + a :term:`moving ` :term:`pools`, or + which contain references to blocks in moving pools. The :ref:`pool-lo` :term:`pool class` is designed for this use case: blocks allocated from this pool do not move and @@ -267,7 +263,7 @@ Memory Management Glossary: F If formats are provided by a language or the application program, :term:`exact garbage collection` can be used, because the :term:`collector (1)` can determine which - fields are :term:`references `. + fields are :term:`references`. .. seealso:: :term:`conservative garbage collection`. @@ -303,9 +299,9 @@ Memory Management Glossary: F forwarding object forwarding pointer - Some :term:`garbage collectors ` + Some :term:`garbage collectors` :term:`move ` :term:`reachable` - :term:`objects ` into another space. They leave a + :term:`objects` into another space. They leave a forwarding pointer, a special :term:`reference` pointing to the new :term:`location `, in the old location. @@ -319,8 +315,8 @@ Memory Management Glossary: F The term *forwarding object* is used. This is a :term:`formatted object` that has been replaced by a :term:`forwarding marker`. One of three types of formatted - objects, the other two being :term:`client objects ` and :term:`padding objects `. + objects, the other two being :term:`client objects` and + :term:`padding objects`. fragmentation @@ -342,7 +338,7 @@ Memory Management Glossary: F In :term:`manual memory management`, to free or deallocate an :term:`object` is to tell the :term:`memory manager` that it is no longer needed. The :term:`memory (1)` may then be - :term:`recycled ` by being used for subsequent + :term:`recycled` by being used for subsequent :term:`allocation `, or by being returned to the operating system. @@ -358,15 +354,15 @@ Memory Management Glossary: F free (3) :term:`Memory (2)` is *free* if it is not currently - :term:`allocated `. + :term:`allocated`. .. historical:: The term *available* was commonly used to mean "free". - .. opposite:: :term:`allocated `. + .. opposite:: :term:`allocated`. - .. seealso:: :term:`allocate`, :term:`free (1)`. + .. seealso:: :term:`free (1)`. free (4) @@ -377,11 +373,10 @@ Memory Management Glossary: F A single contiguous area of :term:`memory (2)` available to satisfy an :term:`allocation ` request. - For the purpose of discussing :term:`allocation mechanisms - `, two adjacent free blocks are not - considered to be a single free block, until they are - :term:`coalesced `. Free blocks may be - :term:`split`. + For the purpose of discussing :term:`allocation mechanisms`, + two adjacent free blocks are not considered to be a single + free block, until they are :term:`coalesced`. Free blocks may + be :term:`split`. .. seealso:: :term:`allocation mechanism`, :term:`free list`. @@ -393,9 +388,9 @@ Memory Management Glossary: F chain. Usually the links are stored within the :term:`free (3)` - :term:`blocks `. This means that all :term:`allocated - ` blocks must be large enough to store these, and - implies a minimum size. + :term:`blocks`. This means that all :term:`allocated` blocks + must be large enough to store these, and implies a minimum + size. Sometimes, the free block chain is ordered by :term:`address`. This makes :term:`coalescence ` considerably @@ -405,16 +400,15 @@ Memory Management Glossary: F free list - The free list is the set of :term:`free blocks `. + The free list is the set of :term:`free blocks`. Originally this term meant the single linked list of all free - blocks, but as :term:`allocation mechanisms ` have become more varied, it has become more - generic, and now may be implemented as a tree or other data - structure rather than a linked list. If the implementation - actually is a linked list of free blocks, this is called a - :term:`free block chain` to distinguish it from the abstract - term. + blocks, but as :term:`allocation mechanisms` have become more + varied, it has become more generic, and now may be implemented + as a tree or other data structure rather than a linked list. + If the implementation actually is a linked list of free + blocks, this is called a :term:`free block chain` to + distinguish it from the abstract term. There may be several free lists, classed by size or other characteristic. For instance, :term:`segregated free list` diff --git a/mps/manual/source/glossary/g.rst b/mps/manual/source/glossary/g.rst index 9a31ede6215..d7327d87f2d 100644 --- a/mps/manual/source/glossary/g.rst +++ b/mps/manual/source/glossary/g.rst @@ -10,7 +10,7 @@ Memory Management Glossary: G garbage - Garbage consists of :term:`objects ` that are + Garbage consists of :term:`objects` that are :term:`dead`. In :term:`tracing garbage collection`, the term is sometimes @@ -32,12 +32,11 @@ Memory Management Glossary: G Garbage collection is a tried and tested memory management technique that has been in use since its invention in the 1950s. It avoids the need for the programmer to - :term:`deallocate ` memory :term:`blocks ` + :term:`deallocate ` memory :term:`blocks` explicitly, thus avoiding a number of problems: :term:`memory - leaks `, :term:`double frees `, and - :term:`premature frees `. The burden on the - programmer is reduced by not having to investigate such - problems, thereby increasing productivity. + leaks`, :term:`double frees`, and :term:`premature frees`. The + burden on the programmer is reduced by not having to + investigate such problems, thereby increasing productivity. Garbage collection can also dramatically simplify programs, chiefly by allowing modules to present cleaner interfaces to @@ -45,18 +44,17 @@ Memory Management Glossary: G is unnecessary. It is not possible, in general, for a :term:`garbage - collector` to determine exactly which :term:`objects ` - are still :term:`live`. Even if it didn't depend on future - input, there can be no general algorithm to prove that an - object is live (cf. the Halting Problem). All garbage - collectors use some efficient approximation to liveness. In - :term:`tracing garbage collection`, the approximation is that - an object can't be live unless it is :term:`reachable`. In - :term:`reference counting`, the approximation is that an - object can't be live unless it is :term:`referenced - `. Hybrid algorithms are also possible. Often the - term *garbage collection* is used narrowly to mean only - tracing garbage collection. + collector` to determine exactly which :term:`objects` are + still :term:`live`. Even if it didn't depend on future input, + there can be no general algorithm to prove that an object is + live (cf. the Halting Problem). All garbage collectors use + some efficient approximation to liveness. In :term:`tracing + garbage collection`, the approximation is that an object can't + be live unless it is :term:`reachable`. In :term:`reference + counting`, the approximation is that an object can't be live + unless it is :term:`referenced`. Hybrid algorithms are also + possible. Often the term *garbage collection* is used narrowly + to mean only tracing garbage collection. There is a large body of published work on particular and general garbage collection algorithms. @@ -110,7 +108,7 @@ Memory Management Glossary: G generation - A generation is a set of :term:`objects ` of similar + A generation is a set of :term:`objects` of similar *age*. A :term:`generational garbage collector `. + :term:`lifetimes`. .. seealso:: :term:`bucket`. @@ -142,7 +140,7 @@ Memory Management Glossary: G .. mps:specific:: A data structure that specifies the structure of the - :term:`generations ` in a :term:`pool`. See + :term:`generations` in a :term:`pool`. See :ref:`topic-collection`. generation scavenging @@ -155,8 +153,8 @@ Memory Management Glossary: G Generational garbage collection is :term:`tracing garbage collection` that makes use of the :term:`generational - hypothesis`. :term:`Objects ` are gathered together in - :term:`generations `. New objects are allocated in + hypothesis`. :term:`Objects` are gathered together in + :term:`generations`. New objects are allocated in the *youngest* or *nursery* generation, and :term:`promoted ` to *older* generations if they survive. Objects in older generations are :term:`condemned ` @@ -164,11 +162,11 @@ Memory Management Glossary: G It is typically rare for an object to refer to a younger object. Hence, objects in one generation typically have few - :term:`references ` to objects in younger + :term:`references` to objects in younger generations. This means that the :term:`scanning ` of old generations in the course of collecting younger generations can be done more efficiently by means of - :term:`remembered sets `. + :term:`remembered sets`. In some purely functional languages (that is, without update), all references are backwards in time, in which case remembered @@ -181,9 +179,8 @@ Memory Management Glossary: G .. aka:: *infant mortality*. *Infant mortality* or *the generational hypothesis* is the - observation that, in most cases, young :term:`objects - ` are much more likely to :term:`die ` than old - objects. + observation that, in most cases, young :term:`objects` are + much more likely to :term:`die ` than old objects. Strictly, the hypothesis is that the probability of death as a function of age falls faster than exponential decay (inverse @@ -195,20 +192,19 @@ Memory Management Glossary: G .. aka:: *GB*. - A gigabyte is 1024 :term:`megabytes `, or 1073741824 - :term:`bytes (1) `. + A gigabyte is 1024 :term:`megabytes`, or 1073741824 + :term:`bytes (1)`. See :term:`byte (1)` for general information on this and related quantities. good fit - The class of :term:`allocation policies ` - which approximate :term:`best fit`. Strict best fit may be - costly to implement (depending on the details of the - :term:`allocation mechanism`), so some implementors - approximate it, choosing a block which is close in size to the - allocation request. + The class of :term:`allocation policies` which approximate + :term:`best fit`. Strict best fit may be costly to implement + (depending on the details of the :term:`allocation + mechanism`), so some implementors approximate it, choosing a + block which is close in size to the allocation request. .. seealso:: :term:`best fit`, :term:`allocation policy`, :term:`next fit`, :term:`worst fit`. @@ -230,12 +226,12 @@ Memory Management Glossary: G graph - A graph is a set of :term:`nodes ` together with a set - of :term:`edges ` connecting nodes. + A graph is a set of :term:`nodes` together with a set + of :term:`edges` connecting nodes. If the edges have direction like arrows (for example, - :term:`references ` in a graph of :term:`objects - `), then the graph is said to be a *directed graph*. + :term:`references` in a graph of :term:`objects`), then the + graph is said to be a *directed graph*. .. figure:: ../diagrams/graph.svg :align: center @@ -246,19 +242,19 @@ Memory Management Glossary: G .. relevance:: Graphs are used to model :term:`reachability ` - for :term:`tracing garbage collection`. The :term:`objects - ` are considered to form a graph, with the nodes - of the graph being the objects and the edges of the graph - being the references from one object to another. Usually, - there is a single, distinguished :term:`root` to which the - :term:`mutator` has *direct* access, and the nodes - strongly connected to it are the reachable modes. + for :term:`tracing garbage collection`. The + :term:`objects` are considered to form a graph, with the + nodes of the graph being the objects and the edges of the + graph being the references from one object to another. + Usually, there is a single, distinguished :term:`root` to + which the :term:`mutator` has *direct* access, and the + nodes strongly connected to it are the reachable modes. gray grey - In a :term:`tri-color marking` scheme, gray :term:`objects - ` are objects that are proved or assumed (see + In a :term:`tri-color marking` scheme, gray :term:`objects` + are objects that are proved or assumed (see :term:`generational ` and :term:`condemn `) to be :term:`reachable`, but have not yet been :term:`scanned `. @@ -274,7 +270,7 @@ Memory Management Glossary: G gray list grey list - The gray list is the set of :term:`objects ` that a + The gray list is the set of :term:`objects` that a :term:`tracing garbage collector ` has noted :term:`reachable`, but hasn't :term:`scanned ` yet. diff --git a/mps/manual/source/glossary/h.rst b/mps/manual/source/glossary/h.rst index 98df67c6b82..dd2fe720621 100644 --- a/mps/manual/source/glossary/h.rst +++ b/mps/manual/source/glossary/h.rst @@ -67,11 +67,11 @@ Memory Management Glossary: H :term:`allocation ` and :term:`deallocation ` of :term:`memory (1)` in arbitrary order. - Dynamic allocation is usually for :term:`objects ` + Dynamic allocation is usually for :term:`objects` whose size, quantity, or :term:`lifetime` could not be determined at compile-time. It is necessary to implement modern data structures, such as recursive trees and full - :term:`closures `. + :term:`closures`. Objects on the :term:`heap` can be managed :term:`manually `, as in :term:`C`, or diff --git a/mps/manual/source/glossary/i.rst b/mps/manual/source/glossary/i.rst index 8e1fc7928de..684163cbe55 100644 --- a/mps/manual/source/glossary/i.rst +++ b/mps/manual/source/glossary/i.rst @@ -11,7 +11,7 @@ Memory Management Glossary: I immediate data Immediate data is the representation of a :term:`value object` - as one or more machine :term:`words `, as a register, or + as one or more machine :term:`words`, as a register, or as a field in an instruction. Immediate data takes its name from the value of the object @@ -24,14 +24,14 @@ Memory Management Glossary: I immune set - The set of :term:`objects ` which are not + The set of :term:`objects` which are not :term:`condemned `. .. opposite:: :term:`condemned set`. immutable - In some programming languages, :term:`objects ` of + In some programming languages, :term:`objects` of some types are immutable, that is, they cannot be modified. For example, in Standard :term:`ML`, only arrays and refs are mutable; all other objects are immutable. @@ -62,7 +62,7 @@ Memory Management Glossary: I .. aka:: *frame*, *header*. - Some :term:`memory managers ` :term:`allocate` + Some :term:`memory managers` :term:`allocate` a fixed amount more than is necessary for each :term:`block` and use it to store information such as the size of the block or a :term:`tag`. This extra memory is known as an *in-band @@ -127,9 +127,9 @@ Memory Management Glossary: I Incremental-update algorithms for :term:`tracing `, :term:`incremental garbage collection` note changes made by - the :term:`mutator` to the :term:`graph` of :term:`objects - ` and update the :term:`collector (2)` state to make - it correctly trace the new graph. + the :term:`mutator` to the :term:`graph` of :term:`objects` + and update the :term:`collector (2)` state to make it + correctly trace the new graph. In order for the collector to miss a :term:`reachable` :term:`object`, the following two conditions need to hold at @@ -183,12 +183,12 @@ Memory Management Glossary: I indexed fit - A class of :term:`allocation mechanisms ` that use an indexing data structure, such as a - tree or hash table, to identify suitable :term:`free blocks - `, according to the :term:`allocation policy`. For - instance, a tree ordered by block size may be used to - implement the :term:`best fit` policy. + A class of :term:`allocation mechanisms` that use an indexing + data structure, such as a tree or hash table, to identify + suitable :term:`free blocks`, according to the + :term:`allocation policy`. For instance, a tree ordered by + block size may be used to implement the :term:`best fit` + policy. .. seealso:: :term:`allocation mechanism`, :term:`allocation policy`, :term:`sequential fit`, :term:`bitmapped fit`. @@ -198,7 +198,7 @@ Memory Management Glossary: I Indirect methods of :term:`automatic memory management` are those in which the information necessary to determine whether - an :term:`object` can be :term:`reclaimed ` is not + an :term:`object` can be :term:`reclaimed` is not stored in or associated with that object, but is derived from other objects. @@ -238,7 +238,7 @@ Memory Management Glossary: I Allocation of child objects inside their parent, as opposed to allocating child objects on the :term:`heap` and storing - :term:`pointers ` to them in the parent. + :term:`pointers` to them in the parent. inter-generational pointer @@ -258,10 +258,9 @@ Memory Management Glossary: I that must be scanned are the ones that contain inter-generational pointers. :term:`Generational garbage collectors ` make use of - :term:`write-barriers ` and data structures - like :term:`entry tables (2) `, :term:`exit - tables `, and :term:`remembered sets ` to track those objects at run-time. + :term:`write barriers` and data structures like :term:`entry + tables (2)`, :term:`exit tables`, and :term:`remembered sets` + to track those objects at run-time. Inter-generational pointers can cause :term:`floating garbage`: even if both referrer and referent die, the @@ -302,10 +301,9 @@ Memory Management Glossary: I internal fragmentation Internal :term:`fragmentation` is where the :term:`memory - manager` :term:`allocates ` more for each allocation + manager` :term:`allocates` more for each allocation than is actually requested. There are three reasons for this: - :term:`padding`; :term:`buddy system`; :term:`in-band headers - `. + :term:`padding`; :term:`buddy system`; :term:`in-band headers`. .. seealso:: :term:`external fragmentation`. @@ -326,12 +324,12 @@ Memory Management Glossary: I inverted page-table In a :term:`virtual memory` system, conventional - :term:`page tables ` have an entry for every + :term:`page tables` have an entry for every :term:`page` in the :term:`virtual address space`. An *inverted page table* has only as many entries as there are pages in :term:`physical memory (1)`, and uses a hash lookup - to translate :term:`virtual addresses ` to - :term:`physical addresses ` in nearly + to translate :term:`virtual addresses` to + :term:`physical addresses` in nearly constant time. The entire virtual address space of each process is described @@ -342,7 +340,7 @@ Memory Management Glossary: I (1)` resources. Inverted page tables are ideal for schemes that store - information about :term:`objects ` in the high-order + information about :term:`objects` in the high-order bits of their :term:`address`. Such schemes may perform poorly with conventional page tables as the sparse address space may cause the page table structures to become so large as to @@ -362,8 +360,7 @@ Memory Management Glossary: I .. mps:specific:: A :term:`format method` that is called by a :term:`moving - ` :term:`pool ` to - determine if a :term:`formatted object` is a - :term:`forwarding object`, and if so, to return the address - where the object was moved to. See - :c:type:`mps_fmt_isfwd_t`. + ` :term:`pool` to determine if a + :term:`formatted object` is a :term:`forwarding object`, + and if so, to return the address where the object was + moved to. See :c:type:`mps_fmt_isfwd_t`. diff --git a/mps/manual/source/glossary/k.rst b/mps/manual/source/glossary/k.rst index ff4b18c2694..87b349d527e 100644 --- a/mps/manual/source/glossary/k.rst +++ b/mps/manual/source/glossary/k.rst @@ -16,7 +16,7 @@ Memory Management Glossary: K .. aka:: *kB*. - A kilobyte is 1024 :term:`bytes (1) `. + A kilobyte is 1024 :term:`bytes (1)`. See :term:`byte (1)` for general information on this and related quantities. diff --git a/mps/manual/source/glossary/l.rst b/mps/manual/source/glossary/l.rst index 352b8a40cec..21d32ec8f8f 100644 --- a/mps/manual/source/glossary/l.rst +++ b/mps/manual/source/glossary/l.rst @@ -11,7 +11,7 @@ Memory Management Glossary: L large object area An :term:`allocation mechanism` designed to optimize the - management of large :term:`objects ` by separating + management of large :term:`objects` by separating them from small ones. Large objects, typically objects one or more orders of @@ -38,24 +38,23 @@ Memory Management Glossary: L the header is fixed size and the bulk of the object is in the body. See [UNGAR88]_. - 4. By using a page-based :term:`read-barrier `, - large objects can be initialized incrementally. For - example, each page of the large object is initialized to - zero when it is first read, rather than all at once at - creation time. + 4. By using a page-based :term:`read barrier`, large objects + can be initialized incrementally. For example, each page of + the large object is initialized to zero when it is first + read, rather than all at once at creation time. 5. In a copying collector, large objects can be copied incrementally using a similar technique (the new copy is initialized from the old copy). See [BAKER78]_. - 6. Large objects are often :term:`leaf objects `, + 6. Large objects are often :term:`leaf objects`, so do not need to be :term:`scanned `, or are known to have a fixed :term:`format` with only a few - :term:`references ` so they can be scanned more + :term:`references` so they can be scanned more efficiently by a specialized scanner. 7. Large objects often have longer than average - :term:`lifetimes `, so are not allocated in a + :term:`lifetimes`, so are not allocated in a :term:`nursery space` of a :term:`generational garbage collector `. @@ -77,7 +76,7 @@ Memory Management Glossary: L If leaf objects can be identified, a :term:`garbage collector` can make certain optimizations: leaf objects do not have to be :term:`scanned ` for references nor - are :term:`barriers (1) ` needed to detect + are :term:`barrier (1)` needed to detect and maintain references in the object. leak @@ -100,12 +99,11 @@ Memory Management Glossary: L LIFO-ordered first fit The :term:`allocation policy` that always uses the - most-recently :term:`freed ` suitable :term:`free - block`. Commonly implemented by pushing freed blocks on the - front of a :term:`free block chain`, and then using - :term:`first fit` allocation on this chain. :term:`free (1)` - can be very quick, depending on the :term:`coalescing - ` policy. + most-recently :term:`freed (1)` suitable :term:`free block`. + Commonly implemented by pushing freed blocks on the front of a + :term:`free block chain`, and then using :term:`first fit` + allocation on this chain. :term:`free (1)` can be very quick, + depending on the :term:`coalescing ` policy. This policy may suffer from severe :term:`fragmentation` in the presence of short-lived large objects of a single size. As @@ -121,7 +119,7 @@ Memory Management Glossary: L .. aka:: *sticky reference count*. A :term:`reference counting` technique whereby the field used - to store the number of :term:`references ` to an + to store the number of :term:`references` to an :term:`object` has a limited size. In particular, the field is not large enough to represent the maximum possible number of references to an object. @@ -131,9 +129,9 @@ Memory Management Glossary: L only store the count accurately up to a certain maximum value. If an object has more references than the maximum then the count "sticks" at the maximum and is never decremented. Such - objects are expected to be rare, but their :term:`memory (1)` can - never be :term:`reclaimed ` using reference counting. - A separate (infrequently run) :term:`tracing garbage collector + objects are expected to be rare, but their :term:`memory (1)` + can never be :term:`reclaimed` using reference counting. A + separate (infrequently run) :term:`tracing garbage collector ` is often employed to reclaim this storage. @@ -144,7 +142,7 @@ Memory Management Glossary: L linear addressing - In linear addressing, :term:`addresses
` form a + In linear addressing, :term:`addresses` form a single, continuous :term:`address space`. This term is used mostly in opposition to :term:`segmented addressing`. @@ -158,11 +156,11 @@ Memory Management Glossary: L will read from it in future. The term is often used more broadly to mean :term:`reachable`. - It is not possible, in general, for :term:`garbage collectors - ` to determine exactly which :term:`objects - ` are still live. Instead, they use some approximation - to detect objects that are provably :term:`dead`, such as - those that are not :term:`reachable`. + It is not possible, in general, for :term:`garbage collectors` + to determine exactly which :term:`objects` are still live. + Instead, they use some approximation to detect objects that + are provably :term:`dead`, such as those that are not + :term:`reachable`. .. similar:: :term:`reachable`. @@ -173,7 +171,7 @@ Memory Management Glossary: L load To transfer data from :term:`memory (2)` to a processor's - :term:`registers `. + :term:`registers`. Load can also be used in the more general sense of moving data from a part of the :term:`memory hierarchy` that is slow to @@ -214,12 +212,12 @@ Memory Management Glossary: L .. relevance:: A :term:`mutator` may exhibit predictable properties such - as accessing in turn :term:`objects ` which were - :term:`allocated ` in turn, or accessing in turn - objects which have :term:`references ` to each - other. An intelligent :term:`allocator` or :term:`copying - garbage collector ` can use - this observation to improve locality of reference. + as accessing in turn :term:`objects` which were + :term:`allocated` in turn, or accessing in turn objects + which have :term:`references` to each other. An + intelligent :term:`allocator` or :term:`copying garbage + collector ` can use this + observation to improve locality of reference. .. bibref:: [GZH93]_, [WLM92]_. @@ -233,7 +231,7 @@ Memory Management Glossary: L A *location dependency* records the fact that the :term:`client program` depends on the bit patterns of some - :term:`references ` (and not merely on the + :term:`references` (and not merely on the identity of the :term:`block` to which the reference refers), and provides a function (:c:func:`mps_ld_isstale`) to find out whether any of diff --git a/mps/manual/source/glossary/m.rst b/mps/manual/source/glossary/m.rst index f7374f321fb..a92776da6b3 100644 --- a/mps/manual/source/glossary/m.rst +++ b/mps/manual/source/glossary/m.rst @@ -26,9 +26,8 @@ Memory Management Glossary: M cache). Main memory is the middle level of the :term:`memory - hierarchy`: it is slower and cheaper than :term:`caches (1) - `, but faster and more expensive than - :term:`backing store`. + hierarchy`: it is slower and cheaper than :term:`caches (1)`, + but faster and more expensive than :term:`backing store`. It is common to refer only to the main memory of a computer; for example, "This box has 16 MB of memory" and "Word for @@ -72,11 +71,10 @@ Memory Management Glossary: M difficult bookkeeping task C++ programmers face, that leads to two opposite problems: firstly, an object can be :term:`deallocated ` prematurely, while valid - :term:`references ` still exist - (:term:`dangling pointers `); secondly, + :term:`references` still exist + (:term:`dangling pointers`); secondly, :term:`dead` objects might not be deallocated, leading to - memory filling up with dead objects (:term:`memory leaks - `). Attempts to correct either problem can + memory filling up with dead objects (:term:`memory leaks`). Attempts to correct either problem can lead to overcompensation and the opposite problem occurring. A correct system is a fine balance. @@ -93,15 +91,15 @@ Memory Management Glossary: M .. mps:specific:: - Manual memory management can be used with :term:`pools - ` such as :ref:`pool-mvff` via the functions + Manual memory management can be used with :term:`pools` + such as :ref:`pool-mvff` via the functions :c:func:`mps_alloc` and :c:func:`mps_free`. mapped .. aka:: *committed*. - A range of :term:`virtual addresses ` is said + A range of :term:`virtual addresses` is said to be *mapped* (*committed* on Windows) if there is :term:`physical memory (2)` associated with the range. @@ -121,7 +119,7 @@ Memory Management Glossary: M mapping A *mapping* is a correspondence between a range of - :term:`virtual addresses ` and some + :term:`virtual addresses` and some :term:`memory (1)` (or a :term:`memory-mapped ` object). The physical location of the memory will be managed by the :term:`virtual memory` system. @@ -148,7 +146,7 @@ Memory Management Glossary: M Mark-compact collection is a kind of :term:`tracing garbage collection` that operates by :term:`marking` :term:`reachable` - :term:`objects `, then :term:`compacting ` + :term:`objects`, then :term:`compacting ` the marked objects (which must include all the :term:`live` objects). @@ -158,14 +156,13 @@ Memory Management Glossary: M objects and update references. As a result of compaction, all the marked objects are moved into a single contiguous :term:`block` of memory (or a small number of such blocks); - the memory left unused after compaction is :term:`recycled - `. + the memory left unused after compaction is :term:`recycled`. Mark-compact collection can be regarded as a variation of :term:`mark-sweep collection `, with extra effort spent to eliminate the resulting :term:`fragmentation`. Compaction also allows the use of more efficient - :term:`allocation mechanisms `, by + :term:`allocation mechanisms`, by making large free blocks available. .. bibref:: [EDWARDS]_. @@ -175,7 +172,7 @@ Memory Management Glossary: M Mark-sweep collection is a kind of :term:`tracing garbage collection` that operates by :term:`marking` :term:`reachable` - :term:`objects `, then :term:`sweeping` over + :term:`objects`, then :term:`sweeping` over :term:`memory (2)` and :term:`recycling ` objects that are unmarked (which must be :term:`unreachable`), putting them on a :term:`free list`. @@ -199,9 +196,9 @@ Memory Management Glossary: M Marking is the first phase ("the mark phase") of the :term:`mark-sweep` algorithm or :term:`mark-compact` - algorithm. It follows all :term:`references ` from - a set of :term:`roots ` to mark all the - :term:`reachable` :term:`objects `. + algorithm. It follows all :term:`references` from + a set of :term:`roots` to mark all the + :term:`reachable` :term:`objects`. Marking follows :term:`reference` chains and makes some sort of mark for each object it reaches. @@ -222,8 +219,8 @@ Memory Management Glossary: M .. aka:: *MB*. - A megabyte is 1024 :term:`kilobytes `, or 1048576 - :term:`bytes (1) `. + A megabyte is 1024 :term:`kilobytes`, or 1048576 + :term:`byte (1)`. See :term:`byte (1)` for general information on this and related quantities. @@ -247,7 +244,8 @@ Memory Management Glossary: M .. historical:: - "Store" is old-fashioned, but survives in expressions such as ":term:`backing store`". + "Store" is old-fashioned, but survives in expressions such + as ":term:`backing store`". memory (2) @@ -289,20 +287,19 @@ Memory Management Glossary: M .. aka:: *leak*, *space leak*, *space-leak*. - A memory leak is where :term:`allocated ` - :term:`memory (2)` is not :term:`freed ` although it - is never used again. + A memory leak is where :term:`allocated` :term:`memory (2)` is + not :term:`freed (1)` although it is never used again. In :term:`manual memory management`, this usually occurs - because :term:`objects ` become :term:`unreachable` - without being :term:`freed `. + because :term:`objects` become :term:`unreachable` without + being :term:`freed (1)`. In :term:`tracing garbage collection`, this happens when objects are :term:`reachable` but not :term:`live`. In :term:`reference counting`, this happens when objects are - :term:`referenced ` but not :term:`live`. (Such - objects may or may not be :term:`reachable`.) + :term:`referenced` but not :term:`live`. (Such objects may or + may not be :term:`reachable`.) Repeated memory leaks cause the memory usage of a process to grow without bound. @@ -314,7 +311,7 @@ Memory Management Glossary: M Each separately-:term:`addressable
` unit of :term:`memory (2)` in which data can be stored is called a *memory location*. Usually, these hold a :term:`byte (2)`, but - the term can refer to :term:`words `. + the term can refer to :term:`words`. memory management @@ -326,10 +323,11 @@ Memory Management Glossary: M Memory management can be divided into three areas: - 1. Memory management hardware (:term:`MMUs `, + 1. Memory management hardware (:term:`MMUs`, :term:`RAM`, etc.); - 2. Operating system memory management (:term:`virtual memory`, :term:`protection`); + 2. Operating system memory management (:term:`virtual memory`, + :term:`protection`); 3. Application memory management (:term:`allocation `, :term:`deallocation `, :term:`garbage @@ -338,8 +336,8 @@ Memory Management Glossary: M Memory management hardware consists of the electronic devices and associated circuitry that store the state of a computer. These devices include RAM, MMUs (memory management units), - :term:`caches (1) `, disks, and processor - :term:`registers `. The design of memory hardware is + :term:`cache (1)`, disks, and processor + :term:`registers`. The design of memory hardware is critical to the performance of modern computer systems. In fact, :term:`memory bandwidth` is perhaps the main limiting factor on system performance. @@ -444,7 +442,7 @@ Memory Management Glossary: M .. mps:specific:: - A queue of :term:`messages ` posted by an + A queue of :term:`messages` posted by an :term:`arena`. It can be queried by calling :c:func:`mps_message_poll`, :c:func:`mps_message_queue_type`, or @@ -487,12 +485,12 @@ Memory Management Glossary: M the proportion of accesses which :term:`miss`. Because misses are very costly, each level is designed to - minimize the miss rate. For instance, in :term:`caches (1) - `, miss rates of about 0.01 may be acceptable, - whereas in :term:`virtual memory` systems, acceptable miss - rates are much lower (say 0.00005). If a system has a miss - rate which is too high, it will spend most of its time - servicing the misses, and is said to :term:`thrash`. + minimize the miss rate. For instance, in :term:`caches (1)`, + miss rates of about 0.01 may be acceptable, whereas in + :term:`virtual memory` systems, acceptable miss rates are much + lower (say 0.00005). If a system has a miss rate which is too + high, it will spend most of its time servicing the misses, and + is said to :term:`thrash`. Miss rates may also be given as a number of misses per unit time, or per instruction. @@ -503,7 +501,7 @@ Memory Management Glossary: M ``mmap`` is a system call provided on many Unix systems to create a :term:`mapping` for a range of :term:`virtual - addresses `. + addresses`. MMU @@ -514,10 +512,10 @@ Memory Management Glossary: M by the main processor. This typically involves translation of :term:`virtual - addresses ` to :term:`physical addresses - `, :term:`cache (1)` control, bus - arbitration, :term:`memory protection`, and the generation of - various exceptions. Not all processors have an MMU. + addresses` to :term:`physical addresses`, :term:`cache (1)` + control, bus arbitration, :term:`memory protection`, and the + generation of various exceptions. Not all processors have an + MMU. .. seealso:: :term:`virtual memory`, :term:`page fault`, :term:`segmentation violation`. @@ -526,9 +524,8 @@ Memory Management Glossary: M A type of :term:`semi-conservative ` :term:`tracing garbage collection` which permits - :term:`objects ` to :term:`move ` if no :term:`ambiguous references ` point to them. + :term:`objects` to :term:`move ` if + no :term:`ambiguous references` point to them. The techniques used are a hybrid of :term:`copying garbage collection` and :term:`mark-sweep`. @@ -553,8 +550,8 @@ Memory Management Glossary: M moving memory manager A memory manager (often a :term:`garbage collector`) is said - to be *moving* if :term:`allocated ` :term:`objects - ` can move during their lifetimes. + to be *moving* if :term:`allocated` :term:`objects` can move + during their lifetimes. .. relevance:: @@ -580,8 +577,7 @@ Memory Management Glossary: M .. aka:: *client program*. In a :term:`garbage-collected ` system, - the part that executes the user code, which :term:`allocates - ` :term:`objects ` and modifies, or + the part that executes the user code, which :term:`allocates` :term:`objects` and modifies, or *mutates*, them. For purposes of describing :term:`incremental garbage @@ -595,8 +591,7 @@ Memory Management Glossary: M collector is to perform a little of it at every allocation. While the mutator mutates, it implicitly :term:`frees ` :term:`memory (1)` by overwriting :term:`references - `. + (1)>` :term:`memory (1)` by overwriting :term:`references`. .. historical:: diff --git a/mps/manual/source/glossary/n.rst b/mps/manual/source/glossary/n.rst index 3b0bf2af184..a472e103cde 100644 --- a/mps/manual/source/glossary/n.rst +++ b/mps/manual/source/glossary/n.rst @@ -15,7 +15,7 @@ Memory Management Glossary: N natural alignment Natural alignment is an :term:`alignment` constraint such that - all :term:`objects ` must be aligned to an address + all :term:`objects` must be aligned to an address that is a multiple of their size. Natural alignment is not usually required for objects larger @@ -33,19 +33,19 @@ Memory Management Glossary: N nepotism In :term:`generational garbage collection` nepotism is the - tendency for :term:`dead` :term:`objects ` in old - :term:`generations ` to preserve younger dead + tendency for :term:`dead` :term:`objects` in old + :term:`generations` to preserve younger dead objects that are referenced by them. In other words, dead parents can cause their children to get promoted. This happens when an object gets :term:`promoted ` to an old generation and dies there, but does not get - :term:`reclaimed ` because the generation it is in - does not get considered for garbage collection very often. The - old object might refer to objects in younger generations that - are also dead; until the old object is reclaimed the younger - objects will be preserved by virtue of the :term:`reference` - from the older, assumed alive, object. + :term:`reclaimed` because the generation it is in does not get + considered for garbage collection very often. The old object + might refer to objects in younger generations that are also + dead; until the old object is reclaimed the younger objects + will be preserved by virtue of the :term:`reference` from the + older, assumed alive, object. This is a form of :term:`floating garbage` introduced by partitioning the objects into generations. @@ -83,8 +83,7 @@ Memory Management Glossary: N node In a :term:`graph`, a node is a representation of an - :term:`object` at the junction of zero or more :term:`edges - `. + :term:`object` at the junction of zero or more :term:`edges`. .. opposite:: :term:`edge`. @@ -94,8 +93,8 @@ Memory Management Glossary: N non-moving memory manager A memory manager is said to be *non-moving* if - :term:`allocated ` :term:`objects ` do not - move during their lifetimes. + :term:`allocated` :term:`objects` do not move during their + lifetimes. Non-moving memory management techniques include :term:`mark-sweep` collection, :term:`reference counting`, and diff --git a/mps/manual/source/glossary/o.rst b/mps/manual/source/glossary/o.rst index a2dccfd0141..12c4f55f8da 100644 --- a/mps/manual/source/glossary/o.rst +++ b/mps/manual/source/glossary/o.rst @@ -23,7 +23,7 @@ Memory Management Glossary: O .. mps:specific:: The MPS documentation generally reserves the term *object* - for :term:`formatted objects `. For + for :term:`formatted objects`. For units of allocation in general, it uses the term :term:`block`. @@ -34,8 +34,8 @@ Memory Management Glossary: O A data structure provided by the :term:`client program` which describes the format of :term:`objects ` allocated in a :term:`pool`. The MPS uses the - :term:`format methods ` to find - :term:`references ` in an object, replace an + :term:`format methods` to find + :term:`references` in an object, replace an object with :term:`padding`, replace an object with a :term:`forwarding marker`, and other essential :term:`garbage collection` tasks. See :ref:`topic-format`. @@ -55,9 +55,9 @@ Memory Management Glossary: O .. aka:: *ecru*. In a :term:`treadmill` :term:`garbage collector`, the - :term:`color` off-white is used to describe :term:`objects - ` which are :term:`free (3)`. Henry Baker used the - term *ecru* in [BAKER92C]_. + :term:`color` off-white is used to describe :term:`objects` + which are :term:`free (3)`. Henry Baker used the term *ecru* + in [BAKER92C]_. .. opposite:: :term:`white`, :term:`gray`, :term:`black`. @@ -77,10 +77,10 @@ Memory Management Glossary: O The one-bit reference count is a special case of the :term:`limited-field reference count`. A single bit in an object, called the MRB (Multiple Reference Bit), is cleared - when the object is :term:`allocated `. Whenever - another :term:`reference` to the object is created, the bit is - set. Thus, MRB=0 indicates that there is exactly one reference - to the object, and MRB=1 indicates that there may be more than + when the object is :term:`allocated`. Whenever another + :term:`reference` to the object is created, the bit is set. + Thus, MRB=0 indicates that there is exactly one reference to + the object, and MRB=1 indicates that there may be more than one reference to the object. The MRB can be stored in the reference rather than in the @@ -142,27 +142,26 @@ Memory Management Glossary: O out-of-band header - In some :term:`memory managers `, each - :term:`allocated ` :term:`block` has additional - information (such as the size of the block or a :term:`tag`) - stored in a separate block; this is called *an out-of-band - header*. + In some :term:`memory managers`, each :term:`allocated` + :term:`block` has additional information (such as the size of + the block or a :term:`tag`) stored in a separate block; this + is called *an out-of-band header*. .. opposite:: :term:`in-band header`. overcommit In some circumstances, although a range of :term:`virtual - addresses ` has been :term:`mapped` as far as - the user program is concerned, the :term:`physical storage` - might not be allocated until it is accessed. This is called + addresses` has been :term:`mapped` as far as the user program + is concerned, the :term:`physical storage` might not be + allocated until it is accessed. This is called *overcommitting*. Overcommitting shares :term:`swap space` resources more - flexibly, especially when crude :term:`suballocators - ` are involved, but it can lead to an - out-of-resource error during a :term:`memory (2)` access; few - environments deal with this situation gracefully. + flexibly, especially when crude :term:`suballocators` are + involved, but it can lead to an out-of-resource error during a + :term:`memory (2)` access; few environments deal with this + situation gracefully. Unix systems such as IRIX and AIX can do this on :term:`sbrk` and :term:`mmap` calls. diff --git a/mps/manual/source/glossary/p.rst b/mps/manual/source/glossary/p.rst index 9f9291e1e19..837d6002d36 100644 --- a/mps/manual/source/glossary/p.rst +++ b/mps/manual/source/glossary/p.rst @@ -11,9 +11,9 @@ Memory Management Glossary: P padding Padding is redundant :term:`memory (2)` within the memory - :term:`allocated ` to an :term:`object`. It is - usually inserted because of :term:`alignment` restrictions on - the fields of the object or on the object itself. + :term:`allocated` to an :term:`object`. It is usually inserted + because of :term:`alignment` restrictions on the fields of the + object or on the object itself. Padding is a form of :term:`internal fragmentation`. @@ -31,13 +31,13 @@ Memory Management Glossary: P A :term:`formatted object` that consists of :term:`padding`. One of three types of formatted objects, - the other two being :term:`client objects ` - and :term:`forwarding objects `. + the other two being :term:`client objects` + and :term:`forwarding objects`. page A :term:`virtual memory` system usually deals with - :term:`memory (1)` :term:`blocks ` of fixed size as + :term:`memory (1)` :term:`blocks` of fixed size as units for :term:`paging`. These are known as *pages*. Pages are often 4 :term:`kB ` or 8 kB in size. This @@ -49,8 +49,8 @@ Memory Management Glossary: P usually resulting in a :term:`page` being fetched from disk. A page fault is an exception occurring during the translation - of :term:`virtual addresses ` to - :term:`physical addresses `. "Page fault" + of :term:`virtual addresses` to + :term:`physical addresses`. "Page fault" usually means an access to a page that has been :term:`paged out` and hence requires fetching from disk, but it is sometimes also used to mean :term:`invalid page fault` or @@ -68,15 +68,15 @@ Memory Management Glossary: P .. see:: :term:`protection`. Many operating systems support protection of :term:`memory - (2)` :term:`pages `. Individual pages may be protected + (2)` :term:`pages`. Individual pages may be protected against a combination of read, write or execute accesses by a process. page table In a :term:`virtual memory` system, it is common to map - between :term:`virtual addresses ` and - :term:`physical addresses ` by means of a + between :term:`virtual addresses` and + :term:`physical addresses` by means of a data structure called a *page table*. The :term:`page` number of an address is usually found from @@ -125,7 +125,7 @@ Memory Management Glossary: P paging In a :term:`virtual memory` system, *paging* is the act of - transferring :term:`pages ` between :term:`physical + transferring :term:`pages` between :term:`physical memory (1)` and :term:`backing store` (usually disk). When pages need to be paged out, a heuristic is used to select @@ -139,22 +139,21 @@ Memory Management Glossary: P palimpsest A :term:`block` of :term:`memory (2)` that has been - :term:`allocated `, :term:`freed ` (or - :term:`reclaimed `), and then allocated again. Such - memory may contain data from the previous use if portions of - it remain uninitialised. + :term:`allocated`, :term:`freed (1)` (or :term:`reclaimed`), + and then allocated again. Such memory may contain data from + the previous use if portions of it remain uninitialised. This commonly occurs on the :term:`stack`, especially if the - compiler allocates large :term:`stack frames ` in + compiler allocates large :term:`stack frames` in anticipation of allocating data structures on the stack. If the palimpsest is being :term:`scanned ` :term:`conservatively `, such - left-over data may cause :term:`unreachable` :term:`objects - ` to appear :term:`reachable` and thus become - :term:`floating garbage`. If it is scanned :term:`precisely - `, such left-over data, if treated - as :term:`pointers `, is a bug. + left-over data may cause :term:`unreachable` :term:`objects` + to appear :term:`reachable` and thus become :term:`floating + garbage`. If it is scanned :term:`precisely `, such left-over data, if treated as + :term:`pointers`, is a bug. parallel garbage collection @@ -165,10 +164,10 @@ Memory Management Glossary: P multi-processor machine. Concurrent :term:`garbage collection` must cope with the - mutator changing :term:`objects ` while collection + mutator changing :term:`objects` while collection occurs. The problem is similar to that of :term:`incremental GC `, but harder. The solution - typically involves :term:`barriers (1) `. + typically involves :term:`barrier (1)`. .. similar:: :term:`incremental `. @@ -185,7 +184,7 @@ Memory Management Glossary: P :term:`unclamped state`). In the parked state, no :term:`garbage collection` is in progress, no object motion occurs and the staleness of :term:`location - dependencies ` does not change. Call + dependencies` does not change. Call :c:func:`mps_arena_park` or :c:func:`mps_arena_collect` to put an arena into the parked state. @@ -205,12 +204,12 @@ Memory Management Glossary: P neither :term:`strongly ` nor :term:`softly ` nor :term:`weakly reachable` and has been :term:`finalized ` and there is a - path from the :term:`roots ` to it that contains at + path from the :term:`roots` to it that contains at least one :term:`phantom reference`. When the Java :term:`collector (1)` determines that an object - is phantom reachable, the :term:`reference objects ` containing the phantom references are enqueued. + is phantom reachable, the :term:`reference objects` containing + the phantom references are enqueued. The Java specification says that the phantom reference is not cleared when the reference object is enqueued, but actually, @@ -246,12 +245,12 @@ Memory Management Glossary: P .. aka:: *absolute address*. - Physical :term:`addresses
` are used to index into + Physical :term:`addresses` are used to index into :term:`physical memory (1)`. On some systems, they are called *absolute addresses*. In a :term:`virtual memory` system the application program - handles :term:`virtual addresses ` and these + handles :term:`virtual addresses` and these are translated to physical addresses by the :term:`MMU`. .. opposite:: :term:`virtual address`. @@ -259,7 +258,7 @@ Memory Management Glossary: P physical address space The physical :term:`address space` is the space of - :term:`physical addresses `. + :term:`physical addresses`. .. opposite:: :term:`virtual address space`. @@ -304,14 +303,14 @@ Memory Management Glossary: P In a :term:`generational ` collector, when a large and long-lived :term:`object` is - :term:`allocated ` in :term:`nursery space`, - collection effort will be wasted as that object survives and - is :term:`promoted ` from :term:`generation` to - generation. This is especially noticeable in a :term:`copying - collector `, where the large - object will be copied many times. This difficulty is similar - to that of a python which swallows its prey whole and is - somewhat immobilized as it digests it. + :term:`allocated` in :term:`nursery space`, collection effort + will be wasted as that object survives and is :term:`promoted + ` from :term:`generation` to generation. This is + especially noticeable in a :term:`copying collector `, where the large object will be copied + many times. This difficulty is similar to that of a python + which swallows its prey whole and is somewhat immobilized as + it digests it. Modern collectors permit objects to be allocated directly into appropriate generations or pools to avoid this problem. @@ -392,7 +391,7 @@ Memory Management Glossary: P .. mps:specific:: A value of type :c:type:`mps_class_t` describing a class - of :term:`pools ` that manage memory according to + of :term:`pools` that manage memory according to particular policy. See :ref:`pool`. precise garbage collection @@ -431,14 +430,14 @@ Memory Management Glossary: P .. aka:: *premature promotion*. - When a short-lived :term:`object` :term:`allocated ` - in a :term:`generational garbage collector ` is :term:`promoted ` (due to - poor timing) into a less-frequently collected - :term:`generation`. This *prematurely tenured* object may - become :term:`garbage` very soon after promotion, but will not - be :term:`reclaimed ` for some time because it is now - in a less frequently collected generation. + When a short-lived :term:`object` :term:`allocated` in a + :term:`generational garbage collector ` is :term:`promoted ` (due to poor + timing) into a less-frequently collected :term:`generation`. + This *prematurely tenured* object may become :term:`garbage` + very soon after promotion, but will not be :term:`reclaimed` + for some time because it is now in a less frequently collected + generation. This problem is essentially due to quantization error: all objects in a generation are treated as if they have the same @@ -451,7 +450,7 @@ Memory Management Glossary: P short-lived objects, it can forestall all promotion until it knows it is done with those objects. Thus no objects will be prematurely promoted: they will all be seen as garbage. - Another solution is to create :term:`buckets ` within + Another solution is to create :term:`buckets` within generations to more accurately classify objects by age and only promote those which have reached a certain minimum. @@ -487,7 +486,7 @@ Memory Management Glossary: P .. aka:: *memory protection*, *page protection*. Many operating systems support protection of :term:`memory - (2)` :term:`pages `. Individual pages may be protected + (2)` :term:`pages`. Individual pages may be protected against a combination of read, write or execute accesses by a process. @@ -500,8 +499,8 @@ Memory Management Glossary: P :term:`generational ` or :term:`incremental ` :term:`garbage collector` may want to place :term:`barriers - (1) ` on pages; an operating system may want to - protect pages for security, or to implement "copy-on-write" or + (1)` on pages; an operating system may want to protect pages + for security, or to implement "copy-on-write" or "demand-zero-filled" pages. .. seealso:: :term:`read fault`, :term:`write fault`. @@ -522,9 +521,8 @@ Memory Management Glossary: P .. relevance:: - Some :term:`garbage collectors ` use - handlers for protection faults to provide :term:`barriers - (1) `. + Some :term:`garbage collectors` use handlers for + protection faults to provide :term:`barriers (1)`. .. seealso:: :term:`segmentation violation`, :term:`General Protection Fault`. diff --git a/mps/manual/source/glossary/q.rst b/mps/manual/source/glossary/q.rst index 99bd07b0f97..28a43687083 100644 --- a/mps/manual/source/glossary/q.rst +++ b/mps/manual/source/glossary/q.rst @@ -11,7 +11,7 @@ Memory Management Glossary: Q quadword A *quadword* is a unit of memory consisting of four adjacent - :term:`words `. + :term:`words`. .. historical:: diff --git a/mps/manual/source/glossary/r.rst b/mps/manual/source/glossary/r.rst index 030a583ed9e..67a1869179c 100644 --- a/mps/manual/source/glossary/r.rst +++ b/mps/manual/source/glossary/r.rst @@ -62,16 +62,16 @@ Memory Management Glossary: R An :term:`object` is *reachable* if it is :term:`referred ` to by a :term:`root`, or is referred to by a reachable object; that is, if it can be reached from the roots - by following :term:`references `. + by following :term:`references`. Reachability is used as an approximation to :term:`liveness ` in :term:`tracing garbage collection`. - In :term:`Java`, the :term:`reference objects ` together with ordinary references and - :term:`finalization` generate a hierarchy of reachability that - guides the :term:`collector (1)` on what to do when an object - is about to :term:`die `. There are six strengths: + In :term:`Java`, the :term:`reference objects` together with + ordinary references and :term:`finalization` generate a + hierarchy of reachability that guides the :term:`collector + (1)` on what to do when an object is about to :term:`die + `. There are six strengths: 1. :term:`strongly reachable`; 2. :term:`softly reachable`; @@ -203,7 +203,7 @@ Memory Management Glossary: R Reference counting systems perform :term:`automatic memory management` by keeping a count in each :term:`object`, usually in a :term:`header `, of how many - :term:`references ` there are to the object. + :term:`references` there are to the object. Objects to which there are no references cannot be accessed by the :term:`mutator`; they are therefore :term:`dead` and may be :term:`reclaimed `. @@ -324,7 +324,7 @@ Memory Management Glossary: R region inference Region inference is a technique for determining when - :term:`objects ` become :term:`dead` (even if they are + :term:`objects` become :term:`dead` (even if they are :term:`reachable`) by a static analysis of the program. Region inference infers a *region* for each object. When a @@ -363,20 +363,20 @@ Memory Management Glossary: R Run-time systems for :term:`garbage-collected ` languages sometimes partition the set of machine - :term:`registers ` *a priori* into two categories: + :term:`registers` *a priori* into two categories: those always :term:`traced ` and updated by the :term:`garbage collector` and those ignored by it. The former are always maintained in a format understood by the - collector; the latter are never used to hold :term:`references - ` to collectable :term:`objects `. More + collector; the latter are never used to hold + :term:`references` to collectable :term:`objects`. More complicated schemes are also possible. This partitioning provides a separation of concerns between the compiler and the :term:`garbage collector`. The compiler can generate code that produces values the garbage collector would not be able to handle (say, because they have no - :term:`tags `), as long as those values are kept in the + :term:`tags`), as long as those values are kept in the ignored registers. The garbage collector can trust that the registers it looks at always contain valid data, and can perform :term:`exact garbage collection`. @@ -388,7 +388,7 @@ Memory Management Glossary: R relocation *Relocating* means moving data from one location to another - and updating all :term:`references `. + and updating all :term:`references`. Relocation is often performed to avoid :term:`external fragmentation`. @@ -402,8 +402,8 @@ Memory Management Glossary: R remembered set A remembered set is the technique of keeping a separate list - of interesting :term:`references ` between two sets - of :term:`objects `, so you don't have to find them by + of interesting :term:`references` between two sets + of :term:`objects`, so you don't have to find them by :term:`scanning `. Many :term:`memory management` algorithms depend on @@ -413,7 +413,7 @@ Memory Management Glossary: R originating partition to find them. A typical use in :term:`generational garbage collection` is - remembering :term:`references ` from an older + remembering :term:`references` from an older :term:`generation` to a younger one. .. similar:: :term:`entry table (2)`. @@ -427,10 +427,10 @@ Memory Management Glossary: R This is useful in an :term:`incremental ` or :term:`concurrent ` :term:`collector (1)`, as no :term:`read-barrier - ` is required; the :term:`mutator` can continue - to use old objects. The collector uses a :term:`write-barrier - ` to replicate the writes to the new copies. + collection>` :term:`collector (1)`, as no :term:`read barrier` + is required; the :term:`mutator` can continue to use old + objects. The collector uses a :term:`write barrier` to + replicate the writes to the new copies. .. seealso:: :term:`copying garbage collection`, :term:`broken heart`. @@ -439,7 +439,7 @@ Memory Management Glossary: R reserved In a :term:`virtual memory` system, it is usually possible - to hold range of :term:`virtual addresses ` + to hold range of :term:`virtual addresses` *reserved* without making it :term:`mapped`. Reserving addresses prevents other components of the program @@ -449,7 +449,7 @@ Memory Management Glossary: R :term:`address space` but only sparsely map it. On some systems there are special calls for reserving; on - others one can create :term:`mappings ` that don't + others one can create :term:`mappings` that don't need :term:`backing store`. For example, on some Unix systems, ``mmap /dev/zero`` with no access. @@ -507,10 +507,9 @@ Memory Management Glossary: R root In :term:`tracing garbage collection`, a root holds a - :term:`reference` or set of references to :term:`objects - ` that are *a priori* :term:`reachable`. The - :term:`root set` is used as the starting point in determining - all reachable data. + :term:`reference` or set of references to :term:`objects` that + are *a priori* :term:`reachable`. The :term:`root set` is used + as the starting point in determining all reachable data. Roots basically comprise the references in the state of the :term:`mutator`. Typical roots are global variables, other @@ -526,8 +525,8 @@ Memory Management Glossary: R .. mps:specific:: The :term:`arena` uses root descriptions to find - :term:`references ` within the :term:`client - program's ` :term:`roots `. Root + :term:`references` within the :term:`client + program's ` :term:`roots`. Root descriptions belong to the type :c:type:`mps_root_t`. root mode @@ -542,7 +541,7 @@ Memory Management Glossary: R root set - The *root set* is the collection of :term:`roots ` that + The *root set* is the collection of :term:`roots` that the :term:`mutator` declares to the :term:`collector (2)`. .. seealso:: :term:`garbage collection`. diff --git a/mps/manual/source/glossary/s.rst b/mps/manual/source/glossary/s.rst index 12c636b9eb0..9ee18b2bc8f 100644 --- a/mps/manual/source/glossary/s.rst +++ b/mps/manual/source/glossary/s.rst @@ -30,10 +30,9 @@ Memory Management Glossary: S .. relevance:: - The objects of a scalar data type are :term:`leaf objects - `. Scalar data types with bounded magnitude - can be represented compactly using :term:`value objects - `. + The objects of a scalar data type are :term:`leaf + objects`. Scalar data types with bounded magnitude can be + represented compactly using :term:`value objects`. .. historical:: @@ -48,7 +47,7 @@ Memory Management Glossary: S scan The examination of an :term:`object` or an area of - :term:`memory (2)` to find :term:`references `, + :term:`memory (2)` to find :term:`references`, typically as part of :term:`tracing `. Scanning examines memory that has been decided to be @@ -64,7 +63,7 @@ Memory Management Glossary: S .. mps:specific:: A function that examines a block of memory to find - :term:`references ` and indicate them to the + :term:`references` and indicate them to the MPS. A scan method forms part of an :term:`object format`. See :c:type:`mps_fmt_scan_t`. @@ -75,7 +74,7 @@ Memory Management Glossary: S A scan state represents the state of the current :term:`scan`. The MPS passes a scan state to the :term:`scan method` of an :term:`object format` when it - needs to :term:`scan` for :term:`references ` + needs to :term:`scan` for :term:`references` within a region of memory. Scan states belong to the type :c:type:`mps_ss_t`. @@ -108,7 +107,7 @@ Memory Management Glossary: S segmented addressing - In segmented addressing, :term:`addresses
` are in + In segmented addressing, :term:`addresses` are in two parts: a segment identifier and an offset into that segment. @@ -119,9 +118,10 @@ Memory Management Glossary: S address. Segment identifiers may be implicit; for instance, they may be obtained from a *current segment* register. - Segmentation may be layered on top of :term:`virtual memory`, in which case the unsegmented address is a - :term:`virtual address`, or not, in which case it is a - :term:`physical address`. + Segmentation may be layered on top of :term:`virtual memory`, + in which case the unsegmented address is a :term:`virtual + address`, or not, in which case it is a :term:`physical + address`. Note that, in segmented architectures, you can have a two-dimensional :term:`address space`. @@ -150,9 +150,9 @@ Memory Management Glossary: S segregated fit One of the :term:`segregated free list` class of - :term:`allocation mechanisms `. There is - an array of :term:`free lists `, each holding - :term:`free blocks ` of a particular range of + :term:`allocation mechanisms`. There is + an array of :term:`free lists`, each holding + :term:`free blocks` of a particular range of sizes. The :term:`allocator` identifies the appropriate free list and allocates from it (often using a :term:`sequential fit` mechanism such as :term:`first fit`). If this fails, a @@ -173,7 +173,7 @@ Memory Management Glossary: S A class of :term:`allocation mechanism` which divides the :term:`free list` into several subsets, according to the size - of the :term:`free blocks `. A :term:`freed ` or :term:`coalesced ` block is placed on the appropriate list. An allocation request is serviced from the appropriate list. @@ -182,8 +182,7 @@ Memory Management Glossary: S :term:`best fit` policy. Variations within this class include :term:`simple segregated - storage`, :term:`segregated fit`, and :term:`buddy systems - `. + storage`, :term:`segregated fit`, and :term:`buddy systems`. .. bibref:: [WIL95]_. @@ -192,11 +191,11 @@ Memory Management Glossary: S .. aka:: *mostly-precise garbage collection*, *mostly-exact garbage collection*. A variant of :term:`conservative garbage collection` which - deals with :term:`exact references ` as well - as :term:`ambiguous references `. + deals with :term:`exact references` as well + as :term:`ambiguous references`. For example, references from the :term:`root set` might be - ambiguous, but :term:`objects ` on the :term:`heap` + ambiguous, but :term:`objects` on the :term:`heap` might be fully described and precisely :term:`scanned `. .. seealso:: :term:`mostly-copying garbage collection`. @@ -214,13 +213,13 @@ Memory Management Glossary: S collector>`, but can be used for :term:`generational collection `. - The semi-space where :term:`objects ` reside at the - start of the collection is known as the :term:`fromspace`; the + The semi-space where :term:`objects` reside at the start of + the collection is known as the :term:`fromspace`; the :term:`tospace` is where objects will reside, and where new - objects will be :term:`allocated `, when the - collection is complete. + objects will be :term:`allocated`, when the collection is + complete. - .. seealso:: :term:`two space collector `. + .. seealso:: :term:`two-space collector`. semi-space collector @@ -228,11 +227,10 @@ Memory Management Glossary: S sequential fit - A class of :term:`allocation mechanisms ` that maintain the :term:`free list` as a single - linear list of :term:`free blocks ` (a :term:`free - block chain`). Sequential fit mechanisms include :term:`first - fit` and :term:`next fit`. + A class of :term:`allocation mechanisms` that maintain the + :term:`free list` as a single linear list of :term:`free + blocks` (a :term:`free block chain`). Sequential fit + mechanisms include :term:`first fit` and :term:`next fit`. To quote [WIL95]_: @@ -243,12 +241,11 @@ Memory Management Glossary: S considering sequential fits, it is probably most important to keep strategy and policy issues in mind. The classic linear-list implementations may not scale well to large - :term:`heaps `, in terms of time costs; as the + :term:`heaps`, in terms of time costs; as the number of free blocks grows the time to search the list may become unacceptable. More efficient and scalable techniques are available, using totally or partially - ordered trees, or :term:`segregated fits `. + ordered trees, or :term:`segregated fits`. .. seealso:: :term:`bitmapped fit`, :term:`indexed fit`. @@ -259,19 +256,17 @@ Memory Management Glossary: S .. aka:: *SSB*. A sequential store buffer is a technique for dividing the cost - of a :term:`write-barrier ` by remembering - which :term:`objects ` are modified and updating - :term:`remembered sets ` (and so on) at a - later stage. + of a :term:`write barrier` by remembering which + :term:`objects` are modified and updating :term:`remembered + sets` (and so on) at a later stage. This turns out to be extremely efficient on pipelined architectures with branch prediction. shared memory - :term:`Memory locations ` are *shared* if - they are in the range of multiple :term:`address spaces -
`. + :term:`Memory locations` are *shared* if + they are in the range of multiple :term:`address spaces`. simple object @@ -288,8 +283,8 @@ Memory Management Glossary: S simple segregated storage A :term:`segregated free list` :term:`allocation mechanism` - which divides :term:`memory (1)` into :term:`pages ` or - other areas and only allocates :term:`objects ` of a + which divides :term:`memory (1)` into :term:`pages` or + other areas and only allocates :term:`objects` of a single size, or small range of sizes, within each area. This makes allocation fast and avoids :term:`headers `, but may lead to high :term:`external fragmentation`, @@ -303,7 +298,7 @@ Memory Management Glossary: S .. mps:specific:: The term *size* in the documentation always refers to a - size that is measured in :term:`bytes `. The term + size that is measured in :term:`bytes (1)`. The term *count* is used for the number of elements in an array. size class @@ -311,9 +306,9 @@ Memory Management Glossary: S .. mps:specific:: A :term:`segregated allocation cache` maintains a reserve - of :term:`blocks ` in a set of :term:`sizes - `: each such size is known as a *size class*. When - creating a segregated allocation cache by calling + of :term:`blocks` in a set of :term:`sizes`: each such + size is known as a *size class*. When creating a + segregated allocation cache by calling :c:func:`mps_sac_create`, the :term:`client program` describes the desired set of size classes by passing an array of structures of type :c:type:`mps_sac_class_s`. @@ -323,8 +318,7 @@ Memory Management Glossary: S .. mps:specific:: A :term:`format method` that returns the address of the - "next object" in a block of :term:`formatted objects - `. See :c:type:`mps_fmt_skip_t`. + "next object" in a block of :term:`formatted objects`. See :c:type:`mps_fmt_skip_t`. smart pointer @@ -337,10 +331,10 @@ Memory Management Glossary: S ``operator\*``, ``operator-\>``, etc. can be used as normal. Reference counting allows the objects that are referred to using the smart pointer class to have their :term:`memory (1)` - automatically :term:`reclaimed ` when they are no - longer :term:`referenced `. It is a common - technique used when trying to solve :term:`memory management` - problems in C++ applications. + automatically :term:`reclaimed` when they are no longer + :term:`referenced`. It is a common technique used when trying + to solve :term:`memory management` problems in C++ + applications. However, reference counting is not always an appropriate memory management technique and smart pointers can be hard to @@ -356,8 +350,8 @@ Memory Management Glossary: S In a :term:`copying collector `, when there is a :term:`reference` to an :term:`object` that was :term:`condemned `, but has been - :term:`transported `, snap-out is the adjustment of - that reference to point to the preserved copy. + :term:`transported`, snap-out is the adjustment of that + reference to point to the preserved copy. Typically the first transport leaves a :term:`forwarding pointer` that enables the snap-out. @@ -375,9 +369,9 @@ Memory Management Glossary: S Snapshot-at-the-beginning algorithms for :term:`tracing `, :term:`incremental GC ` note changes made by the :term:`mutator` to the - :term:`graph` of :term:`objects ` and update the + :term:`graph` of :term:`objects` and update the :term:`collector (2)` state to make it trace relevant - :term:`edges ` that the mutator deletes. + :term:`edges` that the mutator deletes. In order for the collector to miss a :term:`reachable` :term:`object`, the following two conditions need to hold at @@ -436,19 +430,19 @@ Memory Management Glossary: S In :term:`Java`, an object is *softly reachable* if it is not :term:`strongly reachable` and there is a path from the - :term:`roots ` to it that contains at least one + :term:`roots` to it that contains at least one :term:`soft reference` but no :term:`weak (2) ` or :term:`phantom references `. + (2)>` or :term:`phantom references`. When the Java :term:`collector (1)` determines that an object is softly reachable, it has the option of clearing the soft references involved, which will usually allow the object to be - :term:`recycled `. The idea is that they will only be - cleared if the process is running short of :term:`memory (2)`. - If it is done, all soft references involved are cleared, so - that the object is no longer softly reachable, and any - affected :term:`reference objects ` which - are registered with a queue are enqueued. + :term:`recycled`. The idea is that they will only be cleared + if the process is running short of :term:`memory (2)`. If it + is done, all soft references involved are cleared, so that the + object is no longer softly reachable, and any affected + :term:`reference objects` which are registered with a queue + are enqueued. .. seealso:: :term:`reachability `, :term:`weakly reachable`, :term:`phantom reachable`. @@ -512,7 +506,7 @@ Memory Management Glossary: S stack A stack is a LIFO (last in, first out) collection: - :term:`objects ` may be *pushed* onto the stack, and + :term:`objects` may be *pushed* onto the stack, and *popped* off it in reverse order of pushing. When people say "the stack", they usually mean the @@ -594,7 +588,7 @@ Memory Management Glossary: S prescribe the size and type of data that can be stored in a stack frame. Knowledge of the layout of each stack frame may assist a :term:`garbage collector` in finding - :term:`roots `. + :term:`roots`. .. similar:: :term:`activation record`. @@ -610,7 +604,7 @@ Memory Management Glossary: S :term:`memory (1)` before the program starts and retention until the end. - The locations of :term:`objects ` are basically + The locations of :term:`objects` are basically decided at compile-time, although they might be :term:`relocated ` at load-time. This implies the sizes of the objects must be known then. @@ -659,7 +653,7 @@ Memory Management Glossary: S ` objects are stored is sometimes known as *static memory*. In the context of :term:`garbage collection`, the term is used mean memory used to store :term:`static - objects `. + objects`. .. seealso:: :term:`static storage duration`. @@ -679,14 +673,13 @@ Memory Management Glossary: S In :term:`C` and :term:`C++`, the ``static`` keyword applied to a file scope variable or function means it is local to the file; the ``static`` keyword applied to a function or a block - scope variable means it is :term:`allocated ` and - initialized once only. + scope variable means it is :term:`allocated` and initialized + once only. - Objects declared locally in blocks with the - ``static`` keyword are :term:`allocated ` - in :term:`static memory (2)`, and initialized once (usually by - the compiler/linker) instead of each time the block is - entered. + Objects declared locally in blocks with the ``static`` keyword + are :term:`allocated` in :term:`static memory (2)`, and + initialized once (usually by the compiler/linker) instead of + each time the block is entered. Static variables within functions retain their value between function invocations, and therefore must form part of the @@ -706,7 +699,7 @@ Memory Management Glossary: S collection. For example, a stepper function of type :c:type:`mps_formatted_objects_stepper_t` can be passed to :c:func:`mps_arena_formatted_objects_walk` and it will be - called on all :term:`formatted objects ` + called on all :term:`formatted objects` in an :term:`arena`. sticky reference count @@ -740,8 +733,7 @@ Memory Management Glossary: S hierarchy*, in which the topmost levels (those nearest the processor) are fastest, most expensive and smallest. - Levels typically include processor :term:`registers - `, possibly some levels of :term:`cache (1)`, + Levels typically include processor :term:`registers`, possibly some levels of :term:`cache (1)`, :term:`main memory`, and possibly some levels of :term:`backing store`. @@ -770,8 +762,7 @@ Memory Management Glossary: S store (1) - To transfer data from a processor's :term:`registers - ` to :term:`memory (2)`. + To transfer data from a processor's :term:`registers` to :term:`memory (2)`. Store can also be used in the more general sense of transferring data from a part of the :term:`memory hierarchy` @@ -819,8 +810,7 @@ Memory Management Glossary: S strong root A strong root is a :term:`root` such that all - :term:`references ` in it are :term:`strong - references `. + :term:`references` in it are :term:`strong references`. A strong root is the usual sort of root. The term is usually used to draw a contrast with :term:`weak root`. @@ -863,9 +853,9 @@ Memory Management Glossary: S strongly reachable In :term:`Java`, an object is *strongly reachable*, if there - is a path from the :term:`roots ` to it that contains - only :term:`strong references `, that is, - contains no :term:`reference objects `. + is a path from the :term:`roots` to it that contains + only :term:`strong references`, that is, + contains no :term:`reference objects`. .. seealso:: :term:`reachability `, :term:`softly reachable`, :term:`weakly reachable`, :term:`phantom reachable`. @@ -879,7 +869,7 @@ Memory Management Glossary: S another allocator. Suballocators work by :term:`allocating ` large - :term:`blocks ` and :term:`splitting ` them for + :term:`blocks` and :term:`splitting ` them for use, or by :term:`recycling ` blocks locally. Application programmers sometimes write their own @@ -898,8 +888,8 @@ Memory Management Glossary: S subgraph A subgraph S of a :term:`graph` G is a graph such that all the - :term:`nodes ` in S are also in G and all the - :term:`edges ` in S are also in G; that is, it is a part + :term:`nodes` in S are also in G and all the + :term:`edges` in S are also in G; that is, it is a part of a graph. sure reference @@ -955,7 +945,7 @@ Memory Management Glossary: S blocks. Sweeping typically gathers all unmarked blocks into one or - more :term:`free lists `. + more :term:`free lists`. .. seealso:: :term:`marking`. @@ -966,8 +956,7 @@ Memory Management Glossary: S only when a collection function is called. This means that mutator need not ensure that :term:`formatted - objects ` are always :term:`scannable - `, as long as it makes them scannable before the - collector runs. + objects` are always :term:`scannable `, as long as it + makes them scannable before the collector runs. .. opposite:: :term:`asynchronous garbage collector`. diff --git a/mps/manual/source/glossary/t.rst b/mps/manual/source/glossary/t.rst index 9e555e429f7..158930f51be 100644 --- a/mps/manual/source/glossary/t.rst +++ b/mps/manual/source/glossary/t.rst @@ -41,7 +41,9 @@ Memory Management Glossary: T :align: center :alt: Diagram: Example of reference tagging, using the least significant bits. - Example of reference tagging, with objects aligned to addresses that are multiples of four, and the tag stored in the least significant two bits of the reference. + Example of reference tagging, with objects aligned to + addresses that are multiples of four, and the tag stored + in the least significant two bits of the reference. In :term:`C`, when a structure contains a union, it is common to add a field to the structure to indicate which union member @@ -106,7 +108,7 @@ Memory Management Glossary: T An indentifier representing a string, returned from :c:func:`mps_telemetry_intern`, that can be associated - with certain :term:`addresses
`, and so appear in + with certain :term:`addresses`, and so appear in the :term:`telemetry stream` attached to events concerning those addresses. See :ref:`topic-telemetry`. @@ -127,8 +129,8 @@ Memory Management Glossary: T .. aka:: *TB*. - A terabyte is 1024 :term:`gigabytes `, or - 1099511627776 :term:`bytes (1) `. + A terabyte is 1024 :term:`gigabytes`, or + 1099511627776 :term:`bytes (1)`. See :term:`byte (1)` for general information on this and related quantities. @@ -141,7 +143,7 @@ Memory Management Glossary: T A :term:`cache (2)` is said to :term:`thrash` when its :term:`miss rate` is too high, and it spends most of its time - servicing :term:`misses `. Thrashing is bad for + servicing :term:`misses`. Thrashing is bad for performance, particularly :term:`virtual memory` thrashing, because the relative cost of a miss is so high: it may slow a machine down by a factor of a hundred or more. @@ -169,8 +171,8 @@ Memory Management Glossary: T Access to shared resources such as memory management interface must be thread-safe. Each thread has its own - :term:`control stack` which may contain :term:`references - ` to blocks on the heap. + :term:`control stack` which may contain :term:`references` + to blocks on the heap. .. mps:specific:: @@ -202,7 +204,7 @@ Memory Management Glossary: T trace In :term:`tracing garbage collection`, tracing is the process - of following the :term:`graph` from all :term:`roots ` + of following the :term:`graph` from all :term:`roots` to all :term:`reachable` data. .. similar:: :term:`scan`. @@ -215,11 +217,11 @@ Memory Management Glossary: T Tracing garbage collection relies on the fact that if an :term:`object` is not :term:`reachable`, there is no way the :term:`mutator` could ever access it, and therefore it cannot - be :term:`live`. In each :term:`collection cycle`, some or - all of the objects are :term:`condemned ` and - the :term:`graph` is :term:`traced ` to find which of - the condemned objects are reachable. Those that were not - reachable may be :term:`reclaimed `. + be :term:`live`. In each :term:`collection cycle`, some or all + of the objects are :term:`condemned ` and the + :term:`graph` is :term:`traced` to find which of the condemned + objects are reachable. Those that were not reachable may be + :term:`reclaimed`. translation buffer translation lookaside buffer @@ -229,21 +231,18 @@ Memory Management Glossary: T The *translation lookaside buffer* or *address translation cache* is small piece of associative :term:`memory (1)` within a processor which caches part of the translation from - :term:`virtual addresses ` to :term:`physical - addresses `. + :term:`virtual addresses` to :term:`physical addresses`. - In a :term:`virtual memory` system there is a translation - from :term:`virtual addresses ` to - :term:`physical addresses `. This + In a :term:`virtual memory` system there is a translation from + :term:`virtual addresses` to :term:`physical addresses`. This translation can often be very large and complex and the data - structures that implement the translation (often a - :term:`page-table `) can be too large to store - efficiently on the processor. Instead, a few elements of the - translation are stored in the TLB; the processor can access - the TLB extremely quickly. If a required translation for a - particular virtual address is not present in the TLB then *a - TLB miss* is taken and the address is resolved using the more - general mechanism. + structures that implement the translation (often a :term:`page + table`) can be too large to store efficiently on the + processor. Instead, a few elements of the translation are + stored in the TLB; the processor can access the TLB extremely + quickly. If a required translation for a particular virtual + address is not present in the TLB then *a TLB miss* is taken + and the address is resolved using the more general mechanism. transparent alias transparent type @@ -281,7 +280,7 @@ Memory Management Glossary: T marking`. Every :term:`object` is on the list. The list has four - sections corresponding to :term:`colors `. The + sections corresponding to :term:`colors`. The :term:`black`, :term:`gray` and :term:`white` sections are used for tri-color marking, and an additional :term:`off-white` section is used for :term:`free (3)` @@ -336,7 +335,7 @@ Memory Management Glossary: T (or black) nodes, the node is colored black. When no gray nodes remain, the reachable part of the graph has been discovered and any nodes that are still white may be - :term:`recycled `. + :term:`recycled`. The :term:`mutator` is free to access any part of the graph and allocate new nodes while the :term:`collector (2)` is @@ -375,14 +374,13 @@ Memory Management Glossary: T A two-space :term:`collector (1)` is a simple form of a :term:`copying garbage collector `. The available :term:`memory (2)` is divided into - two halves, called :term:`semi-spaces `. - :term:`Objects ` are allocated in one semi-space until - it is full. The :term:`reachable` objects are then copied into - the other semi-space (usually using a :term:`Cheney scan`) and - the old semi-space is :term:`reclaimed `. - :term:`Allocation ` continues in the new semi-space - until it is full, at which point the process is repeated in - reverse. + two halves, called :term:`semi-spaces`. :term:`Objects` are + allocated in one semi-space until it is full. The + :term:`reachable` objects are then copied into the other + semi-space (usually using a :term:`Cheney scan`) and the old + semi-space is :term:`reclaimed`. :term:`Allocation ` + continues in the new semi-space until it is full, at which + point the process is repeated in reverse. The main disadvantage of a two-space collector is that it only makes use of half of the available memory. This can be diff --git a/mps/manual/source/glossary/u.rst b/mps/manual/source/glossary/u.rst index baeed4c3e3a..36ac7721eb8 100644 --- a/mps/manual/source/glossary/u.rst +++ b/mps/manual/source/glossary/u.rst @@ -16,7 +16,7 @@ Memory Management Glossary: U comply with some :term:`alignment` constraint on it. For example, typically double precision floating point numbers - occupy 8 :term:`bytes (1) ` and have an alignment of + occupy 8 :term:`byte (1)` and have an alignment of 4 bytes; that is, their address must be a multiple of four. If a program tries to access such a number using an address that is not a multiple of four, a :term:`bus error` will result. @@ -27,7 +27,7 @@ Memory Management Glossary: U unboxed - Unboxed :term:`objects ` are represented by an + Unboxed :term:`objects` are represented by an encoding of the data itself, and not by a :term:`pointer` to that data. @@ -71,7 +71,7 @@ Memory Management Glossary: U .. aka:: *free*. - A range of :term:`virtual addresses ` is said + A range of :term:`virtual addresses` is said to be *unmapped* (*free* on Windows) if there is no :term:`physical memory (2)` associated with the range. diff --git a/mps/manual/source/glossary/v.rst b/mps/manual/source/glossary/v.rst index 966cc9f15c4..1c92c7e611d 100644 --- a/mps/manual/source/glossary/v.rst +++ b/mps/manual/source/glossary/v.rst @@ -72,10 +72,10 @@ Memory Management Glossary: V .. relevance:: Vector data types are seldom represented using - :term:`value objects `, but may be - represented using :term:`leaf objects ` if + :term:`value objects`, but may be + represented using :term:`leaf objects` if they are an aggregate of a type that can be represented by - :term:`value objects `. :term:`Scanning + :term:`value objects`. :term:`Scanning ` information for vectors can be compactly encoded in terms of the aggregated type and the vector dimension. @@ -85,24 +85,22 @@ Memory Management Glossary: V .. aka:: *logical address*. - In a :term:`virtual memory` system, the :term:`addresses -
` that application programs deal with are known as - *virtual addresses*. + In a :term:`virtual memory` system, the :term:`addresses` that + application programs deal with are known as *virtual + addresses*. The virtual addresses used by the application program are translated by the virtual memory system (often using - :term:`translation lookaside buffers ` and :term:`page tables `) to - :term:`physical addresses `. It is the - physical address that is used to retrieve the contents from - the :term:`memory (3)`. + :term:`translation lookaside buffers` and :term:`page tables`) + to :term:`physical addresses`. It is the physical address that + is used to retrieve the contents from the :term:`memory (3)`. .. opposite:: :term:`physical address`. virtual address space The virtual :term:`address space` is the space of - :term:`virtual addresses `. + :term:`virtual addresses`. On :term:`virtual memory` systems, user processes see the virtual address space, and commonly have a separate virtual @@ -117,7 +115,7 @@ Memory Management Glossary: V .. aka:: *VM*. In a *virtual memory* (*VM*) system, the program code deals - with :term:`virtual addresses `. Upon use, + with :term:`virtual addresses`. Upon use, the virtual address is translated by the :term:`MMU` to obtain a :term:`physical address` that is used to access :term:`physical memory (1)`. @@ -132,8 +130,8 @@ Memory Management Glossary: V :term:`swapped out` to make room. Each process typically has its own separate :term:`virtual - address space` with its own :term:`mappings ` and - :term:`protections `. + address space` with its own :term:`mappings` and + :term:`protections`. .. figure:: ../diagrams/virtual-memory.svg :align: center @@ -144,8 +142,8 @@ Memory Management Glossary: V store. Virtual memory technology can be used in many useful memory - management techniques, such as :term:`barriers (1) `, copy-on-write, and :term:`memory mapping`. + management techniques, such as :term:`barriers (1)`, + copy-on-write, and :term:`memory mapping`. "Virtual" means never knowing where your next byte is coming from. @@ -172,9 +170,8 @@ Memory Management Glossary: V VM (2) - In the :term:`PostScript` language, *VM* is the - :term:`memory (1)` where the values of the :term:`composite - objects ` reside. + In the :term:`PostScript` language, *VM* is the :term:`memory + (1)` where the values of the :term:`composite objects` reside. VM is short for "virtual memory", but this has nothing to do with the usual sense of the phrase (see :term:`virtual memory`). diff --git a/mps/manual/source/glossary/w.rst b/mps/manual/source/glossary/w.rst index dbba24eca4a..21fd2aa21ce 100644 --- a/mps/manual/source/glossary/w.rst +++ b/mps/manual/source/glossary/w.rst @@ -10,9 +10,9 @@ Memory Management Glossary: W weak-key hash table - A hash table which has :term:`weak references ` to its keys. If the key dies, the value for that key is - automatically deleted from the table too. + A hash table which has :term:`weak references (1)` to its + keys. If the key dies, the value for that key is automatically + deleted from the table too. .. similar:: :term:`doubly weak hash table`, :term:`weak-value hash table`. @@ -20,9 +20,9 @@ Memory Management Glossary: W weak-value hash table - A hash table which has :term:`weak references ` to its value. If the value dies, any keys that refer to - that value are automatically deleted from the table too. + A hash table which has :term:`weak references (1)` to its + value. If the value dies, any keys that refer to that value + are automatically deleted from the table too. .. similar:: :term:`doubly weak hash table`, :term:`weak-key hash table`. @@ -43,13 +43,11 @@ Memory Management Glossary: W continue to refer to the object as long as it remains otherwise alive. When only weak references to the object remain, the weak references can be deleted ("splatted" or - "cleared") and the object :term:`reclaimed `. + "cleared") and the object :term:`reclaimed`. :term:`Java` offers three kinds of weak references, called - :term:`soft references `, :term:`weak - references (2) `, and :term:`phantom - references `, in order of increasing - weakness. + :term:`soft references`, :term:`weak references (2)`, and + :term:`phantom references`, in order of increasing weakness. .. opposite:: :term:`strong reference`. @@ -74,11 +72,10 @@ Memory Management Glossary: W weak root - A weak root is a :term:`root`, such that all :term:`references - ` in it are :term:`weak references (1) `; that is, they do not affect the - :term:`liveness ` of the :term:`objects ` - referred to. + A weak root is a :term:`root`, such that all + :term:`references` in it are :term:`weak references (1)`; that + is, they do not affect the :term:`liveness ` of the + :term:`objects` referred to. .. opposite:: :term:`strong root`. @@ -93,7 +90,7 @@ Memory Management Glossary: W The weak :term:`tri-color invariant` is the property of a :term:`reference` :term:`graph` that all :term:`white` - :term:`nodes ` pointed to by a :term:`black` node are + :term:`nodes` pointed to by a :term:`black` node are also :term:`reachable` from some :term:`gray` node through a chain of white nodes. @@ -118,9 +115,8 @@ Memory Management Glossary: W In :term:`Java`, an object is *weakly reachable* if it is neither :term:`strongly ` nor :term:`softly reachable` and there is a path from the - :term:`roots ` to it that contains at least one - :term:`weak reference (2)` but no :term:`phantom references - `. + :term:`roots` to it that contains at least one + :term:`weak reference (2)` but no :term:`phantom references`. When the Java :term:`collector (1)` determines that an object is weakly reachable, it clears all the weak references @@ -128,7 +124,7 @@ Memory Management Glossary: W `. (Operationally, finalization works as if it was implemented by a class of "final references" that stand between weak and phantom references.) Also, the - :term:`reference objects ` containing the + :term:`reference objects` containing the weak references are enqueued, if they were registered with a queue. @@ -159,32 +155,32 @@ Memory Management Glossary: W use for :term:`distributed garbage collection` because of the low level of inter-process communication it requires. - Inter-process :term:`references ` to :term:`objects - ` are counted, but instead of simply counting the - number of references, each reference is given a weight. When - an object is created, the initial pointer to it is assigned a - weight, which is usually a power of 2 for easy division. The - object records the sum of all the weights of all of its - references. Whenever a reference is copied, its weight is - divided equally between the new and original copies. Since - this operation preserves the weighted reference sum, there is - no need for communication with the object at this time. When a - reference is deleted, the weighted reference sum is - decremented by the weight of the reference. This is - communicated to the object by sending it a message. When the - object detects that the weighted reference sum has dropped to - zero, it may be :term:`reclaimed `. The algorithm is - tolerant of communication protocols which don't guarantee - order of arrival of deletion messages. + Inter-process :term:`references` to :term:`objects` are + counted, but instead of simply counting the number of + references, each reference is given a weight. When an object + is created, the initial pointer to it is assigned a weight, + which is usually a power of 2 for easy division. The object + records the sum of all the weights of all of its references. + Whenever a reference is copied, its weight is divided equally + between the new and original copies. Since this operation + preserves the weighted reference sum, there is no need for + communication with the object at this time. When a reference + is deleted, the weighted reference sum is decremented by the + weight of the reference. This is communicated to the object by + sending it a message. When the object detects that the + weighted reference sum has dropped to zero, it may be + :term:`reclaimed`. The algorithm is tolerant of communication + protocols which don't guarantee order of arrival of deletion + messages. white - In a :term:`tri-color marking` scheme, white :term:`objects - ` are objects that were :term:`condemned ` at the beginning of the :term:`collection cycle` and - have not been shown to be :term:`reachable`. When - :term:`tracing ` is complete, white objects will be - subject to :term:`reclamation `. + In a :term:`tri-color marking` scheme, white :term:`objects` + are objects that were :term:`condemned ` at the + beginning of the :term:`collection cycle` and have not been + shown to be :term:`reachable`. When :term:`tracing ` is + complete, white objects will be subject to :term:`reclamation + `. .. opposite:: :term:`gray`, :term:`black`. @@ -196,13 +192,13 @@ Memory Management Glossary: W size that is handled most efficiently. This is known as the *word size*, and data of that size are known as *words*. The word size is usually a power of two multiple of :term:`bytes - (2) `. + (2)`. Often the platform's word size is used to characterize the architecture by quoting the number of bits in it. For example, a 32-bit platform has a word size of four bytes and a 64-bit platform has eight-byte words (assuming 8-bit bytes). - Typically, :term:`pointers ` are the size of a word, + Typically, :term:`pointers` are the size of a word, and traditionally this determined the word size. Nowadays, word size is usually driven by the need for more accuracy and range in mathematical calculations. @@ -216,14 +212,14 @@ Memory Management Glossary: W working set The working set of a program or system is that :term:`memory - (2)` or set of :term:`addresses
` which it will use + (2)` or set of :term:`addresses` which it will use in the near future. - This term is generally used when discussing :term:`miss rates - ` at some :term:`storage level`; the time scale of - "near future" depends upon the cost of a :term:`miss`. The - working set should fit in the storage level; otherwise the - system may :term:`thrash`. + This term is generally used when discussing :term:`miss rates` + at some :term:`storage level`; the time scale of "near future" + depends upon the cost of a :term:`miss`. The working set + should fit in the storage level; otherwise the system may + :term:`thrash`. .. seealso:: :term:`resident set`, :term:`cache (2)`, :term:`storage hierarchy`. @@ -290,10 +286,9 @@ Memory Management Glossary: W Write barriers are used for :term:`incremental ` or :term:`concurrent ` :term:`garbage collection`. - They are also used to maintain :term:`remembered sets - ` for :term:`generational ` :term:`collectors (1) `. + They are also used to maintain :term:`remembered sets` for + :term:`generational ` + :term:`collectors (1) `. .. seealso:: :term:`read barrier`. diff --git a/mps/manual/source/glossary/z.rst b/mps/manual/source/glossary/z.rst index 47ea3f36401..eb4280f197e 100644 --- a/mps/manual/source/glossary/z.rst +++ b/mps/manual/source/glossary/z.rst @@ -17,8 +17,8 @@ Memory Management Glossary: Z .. aka:: *ZCT*. A *zero count table* is used in :term:`deferred reference - counting` to record :term:`objects ` whose + counting` to record :term:`objects` whose :term:`reference counts ` have dropped to zero but which have not been processed to see if they can be - :term:`reclaimed `. + :term:`reclaimed`. diff --git a/mps/manual/source/guide/lang.rst b/mps/manual/source/guide/lang.rst index 6d7896384cf..6dcb1b109cb 100644 --- a/mps/manual/source/guide/lang.rst +++ b/mps/manual/source/guide/lang.rst @@ -106,18 +106,18 @@ Each constructor allocates memory for the new object by calling } Objects are never freed, because it is necessary to prove that they -are :term:`dead` before their memory can be :term:`reclaimed -`. To prove that they are dead, we need a :term:`tracing -` :term:`garbage collector`. Which the MPS will provide. +are :term:`dead` before their memory can be :term:`reclaimed `. To +prove that they are dead, we need a :term:`tracing ` +:term:`garbage collector`. Which the MPS will provide. Choosing an arena class ----------------------- You'll recall from the :ref:`guide-overview` that the functionality of -the MPS is divided between the :term:`arenas `, which request -memory from (and return it to) the operating system, and :term:`pools -`, which allocate blocks of memory for your program. +the MPS is divided between the :term:`arenas`, which request memory +from (and return it to) the operating system, and :term:`pools`, which +allocate blocks of memory for your program. There are two main classes of arena: the :term:`client arena`, :c:func:`mps_arena_class_cl`, which gets its memory from your program, @@ -195,15 +195,14 @@ The section :ref:`pool-choose` in the :ref:`pool` contains a procedure for choosing a pool class. In the case of the Scheme interpreter, the answers to the questions are (1) yes, the MPS needs to automatically reclaim unreachable blocks; (2) yes, it's acceptable for the MPS to -move blocks in memory and protect them with :term:`barriers `; and (3) the Scheme objects will contain :term:`exact references -` to other Scheme objects in the same pool. +move blocks in memory and protect them with :term:`barriers (1)`; and +(3) the Scheme objects will contain :term:`exact references` to other +Scheme objects in the same pool. The recommended class is :ref:`pool-amc`. This pool class uses automatic memory management, moving garbage collection, -:term:`allocation points ` and :term:`formatted -objects `, so it will provide an introduction to -these features of the MPS. +:term:`allocation points` and :term:`formatted objects`, so it will +provide an introduction to these features of the MPS. .. note:: @@ -222,7 +221,7 @@ Describing your objects In order for the MPS to be able to automatically manage your objects, you need to tell it how to perform various operations on an object -(:term:`scan` it for :term:`references `; replace it with a +(:term:`scan` it for :term:`references`; replace it with a :term:`forwarding ` or :term:`padding object`, and so on). You do this by creating an :term:`object format`. Here's the code for creating the object format for the Scheme interpreter:: @@ -270,14 +269,13 @@ you might try: On all the platforms supported by the MPS, the majority of simple datatypes may be aligned on word boundaries (the possible exceptions being ``double`` on 32-bit platforms, and ``long - double`` and :term:`function pointers ` on 32- and + double`` and :term:`function pointers` on 32- and 64-bit platforms), so in applications where these exceptional types are not used (like the Scheme interpreter), you can use:: #define ALIGNMENT sizeof(mps_word_t) -The other elements of the structure are the :term:`format methods -`, which are described in the following sections. (The +The other elements of the structure are the :term:`format methods`, which are described in the following sections. (The ``NULL`` in the structure is a placeholder for the :term:`copy method`, which is now obsolete.) @@ -570,9 +568,9 @@ The padding method The :term:`padding method` is a function of type :c:type:`mps_fmt_pad_t`. It is called by the MPS to fill a block of memory with a :term:`padding object`: this is an object that fills -gaps in a block of :term:`formatted objects `, for +gaps in a block of :term:`formatted objects`, for example to enable the MPS to pack objects into fixed-size units (such -as operating system :term:`pages `). +as operating system :term:`pages`). A padding object must be scannable and skippable, and not confusable with a :term:`forwarding object`. This means they need a type and a @@ -636,7 +634,7 @@ You create a generation chain by constructing an array of structures of type :c:type:`mps_gen_param_s`, one for each generation, and passing them to :c:func:`mps_chain_create`. Each of these structures contains two values, the *capacity* of the generation in -:term:`kilobytes `, and the *mortality*, the proportion of +:term:`kilobytes`, and the *mortality*, the proportion of objects in the generation that you expect to survive a collection of that generation. @@ -721,19 +719,18 @@ And finally the :term:`pool`:: Roots ----- -The :term:`object format` tells the MPS how to find :term:`references -` from one object to another. This allows the MPS to +The :term:`object format` tells the MPS how to find :term:`references` from one object to another. This allows the MPS to extrapolate the reachability property: if object *A* is :term:`reachable`, and the :term:`scan method` fixes a reference from *A* to another object *B*, then *B* is reachable too. But how does this process get started? How does the MPS know which objects are reachable *a priori*? Such objects are known as -:term:`roots `, and you must register them with the MPS, +:term:`roots`, and you must register them with the MPS, creating root descriptions of type :c:type:`mps_root_t`. The most important root consists of the contents of the -:term:`registers ` and the :term:`control stack` of each +:term:`registers` and the :term:`control stack` of each :term:`thread` in your program: this is covered in :ref:`Threads `, below. Other roots may be found in static variables in your program, or in @@ -803,10 +800,10 @@ of references in the root. ":term:`Exact `" means that: 1. all references in the root point to another object (there are no - :term:`ambiguous references `); and + :term:`ambiguous references`); and 2. each reference keeps the target of the reference alive (unlike - :term:`weak references `). + :term:`weak references (1)`). The fourth argument is the :term:`root mode`, which tells the MPS whether it is allowed to place a :term:`barrier (1)` on the root. The @@ -919,8 +916,7 @@ Threads ------- In a multi-threaded environment where :term:`incremental garbage -collection` is used, you must register each of your :term:`threads -` with the MPS so that the MPS can examine their state. +collection` is used, you must register each of your :term:`threads` with the MPS so that the MPS can examine their state. Even in a single-threaded environment (like the Scheme interpreter) it may also be necessary to register the (only) thread if either of these @@ -929,7 +925,7 @@ conditions apply: 1. you are using :term:`moving garbage collection ` (as with the :ref:`pool-amc` pool); -2. the thread's :term:`registers ` and :term:`control stack` +2. the thread's :term:`registers` and :term:`control stack` constitute a :term:`root` (that is, objects may be kept alive via references in local variables: this is almost always the case for programs written in :term:`C`). @@ -1150,7 +1146,7 @@ these rules: 3. All objects in automatically managed pools that are :term:`reachable` by your code must always be provably reachable - from a root via a chain of :term:`references ` that are + from a root via a chain of :term:`references` that are :term:`fixed ` by a scanning function. See the discussion of the :ref:`global symbol table @@ -1176,9 +1172,8 @@ detects. It also causes the MPS to flush its :term:`telemetry stream`. MPS data structures must be destroyed or deregistered in the reverse order to that in which they were registered or created. So you must -destroy all :term:`allocation points ` created in a -:term:`pool` before destroying the pool; destroy all :term:`roots -` and pools, and deregister all :term:`threads `, that +destroy all :term:`allocation points` created in a +:term:`pool` before destroying the pool; destroy all :term:`roots` and pools, and deregister all :term:`threads`, that were created in an :term:`arena` before destroying the arena, and so on. diff --git a/mps/manual/source/guide/overview.rst b/mps/manual/source/guide/overview.rst index 57b64c53e01..e9362945958 100644 --- a/mps/manual/source/guide/overview.rst +++ b/mps/manual/source/guide/overview.rst @@ -11,7 +11,7 @@ management`, :term:`inline allocation `, :term:`finalization`, :term:`weakness `, and multiple concurrent co-operating :term:`incremental ` :term:`generational ` :term:`garbage collections `. It also +collection>` :term:`garbage collections`. It also includes a library of :term:`memory pool classes ` implementing specialized memory management policies. @@ -48,7 +48,7 @@ the point of view of the Memory Pool System. The **arena** is the top-level data structure in the MPS. An :term:`arena` is responsible for requesting :term:`memory (3)` from the operating system (and returning it), for making memory available -to :term:`pools `, and for :term:`garbage collection`. Multiple +to :term:`pools`, and for :term:`garbage collection`. Multiple arenas are supported, but it's usually best to have only one arena in your program, because the MPS can't collect cyclic structures that span multiple arenas. See :ref:`topic-arena`. @@ -71,12 +71,12 @@ managed ` (the :term:`garbage collector` reclaims :term:`unreachable` blocks). See :ref:`pool`. Automatically managed pools need you to tell them how to **scan** for -:term:`references ` to allocated blocks. See +:term:`references` to allocated blocks. See :ref:`topic-scanning`. The arena needs you to tell it how to find your **roots**: references to allocated blocks that are stored in static data, in memory not -managed by the MPS, or on your program's :term:`registers ` or :term:`control stack`. See :ref:`topic-root`. +managed by the MPS, or on your program's :term:`registers` or :term:`control stack`. See :ref:`topic-root`. The MPS is designed to work with multi-threaded programs. Functions in the C interface are thread safe, except in a few documented diff --git a/mps/manual/source/lang.rst b/mps/manual/source/lang.rst index b2f5371c0ad..f50ef87637d 100644 --- a/mps/manual/source/lang.rst +++ b/mps/manual/source/lang.rst @@ -61,11 +61,16 @@ Memory management in various languages 1. Accessing arrays with indexes that are out of bounds; - 2. Using :term:`stack-allocated ` structures beyond their :term:`lifetimes ` (see :term:`use after free`); + 2. Using :term:`stack-allocated ` structures + beyond their :term:`lifetimes` (see :term:`use after + free`); - 3. Using :term:`heap-allocated ` structures after :term:`freeing ` them (see :term:`use after free`); + 3. Using :term:`heap-allocated ` structures + after :term:`freeing ` them (see :term:`use after + free`); - 4. Neglecting to free heap-allocated objects when they are no longer required (see :term:`memory leak`); + 4. Neglecting to free heap-allocated objects when they are no + longer required (see :term:`memory leak`); 5. Failing to allocate memory for a :term:`pointer` before using it; @@ -94,11 +99,11 @@ Memory management in various languages Prior to 2002, COBOL had no :term:`heap allocation`, and did well in its application domain without it. COBOL 2002 has - :term:`pointers ` and heap allocation through - ``ALLOCATE`` and ``FREE``, mainly in order to be able to use - C-style interfaces. It also supports a high level of - abstraction through object-oriented programming and - :term:`garbage collection` (including :term:`finalization`). + :term:`pointers` and heap allocation through ``ALLOCATE`` and + ``FREE``, mainly in order to be able to use C-style + interfaces. It also supports a high level of abstraction + through object-oriented programming and :term:`garbage + collection` (including :term:`finalization`). .. link:: @@ -135,8 +140,8 @@ Memory management in various languages :term:`manual memory management` even harder. Although the standard library provides only manual memory management, with the Boehm-Weiser :term:`collector (1)`, it is now possible to - use :term:`garbage collection`. :term:`Smart pointers ` are another popular solution. + use :term:`garbage collection`. :term:`Smart pointers` are + another popular solution. The language is notorious for fostering memory management bugs, including: @@ -152,8 +157,7 @@ Memory management in various languages 3. Neglecting to free heap-allocated objects when they are no longer required (see :term:`memory leak`); - 4. Excessive copying by copy :term:`constructors `; + 4. Excessive copying by copy :term:`constructors (1)`; 5. Unexpected sharing due to insufficient copying by copy constructors; @@ -213,9 +217,8 @@ Memory management in various languages keys or values, depending on a parameter supplied at allocation time. A hash table entry will be deleted once the garbage collector has determined that there are no - :term:`strong references ` to the key or - value of the entry, for weak key or value tables, - respectively. + :term:`strong references` to the key or value of the entry, + for weak key or value tables, respectively. .. link:: @@ -331,7 +334,7 @@ Memory management in various languages Modern Lisp implementations, such as `LispWorks `_ and `Allegro CL `_, have - advanced :term:`garbage collectors `. + advanced :term:`garbage collectors`. Lisp is now used for all kinds of symbolic programming and other advanced software development. Major dialects today are @@ -362,14 +365,13 @@ Memory management in various languages is in [MOON84]_. The features important for its performance were: - 1. Hardware support for data typing using :term:`tags `; + 1. Hardware support for data typing using :term:`tags`; - 2. Reference-based :term:`read barriers ` for + 2. Reference-based :term:`read barriers` for :term:`incremental ` collecting; - 3. :term:`Write barriers ` for - :term:`remembered sets ` and + 3. :term:`Write barriers` for :term:`remembered sets` and :term:`generational ` collecting; @@ -378,11 +380,11 @@ Memory management in various languages The remembered sets were based on a :term:`BIBOP` division of the virtual :term:`address space`. The Lisp Machine - :term:`page-table `, unlike virtually all modern - virtual memory systems, was a flat, hash-based table - (sometimes called an :term:`inverted page table`), and thus - insensitive to sparsely-populated virtual address spaces - associated with BIBOP schemes. + :term:`page table`, unlike virtually all modern virtual memory + systems, was a flat, hash-based table (sometimes called an + :term:`inverted page table`), and thus insensitive to + sparsely-populated virtual address spaces associated with + BIBOP schemes. These custom processors eventually lost out to rapidly advancing stock hardware. Many of the techniques pioneered on @@ -396,9 +398,9 @@ Memory management in various languages Like other functional languages, ML provides :term:`automatic memory management`. Modern ML implementations usually have - advanced :term:`garbage collectors `. The - combination of clean functional semantics and strong typing - allows advanced techniques, such as :term:`region inference`. + advanced :term:`garbage collectors`. The combination of clean + functional semantics and strong typing allows advanced + techniques, such as :term:`region inference`. The Standard ML of New Jersey (SML/NJ) system, which implements a slight variant of Standard ML, has been important @@ -406,13 +408,13 @@ Memory management in various languages source code is publicly available and widely ported, allowing experimentation with both the :term:`collector (2)` and :term:`mutator`. Secondly, the compiler generates code that - does not use a :term:`control stack`, but :term:`allocates - ` function :term:`activation records ` on the :term:`heap` instead. This means that the - allocation rate is very high (up to one byte per instruction), - and also that the collector has a very small :term:`root set`. - Thirdly, it uses a simple :term:`copying collector ` that is easy to modify. + does not use a :term:`control stack`, but :term:`allocates` + function :term:`activation records` on the :term:`heap` + instead. This means that the allocation rate is very high (up + to one byte per instruction), and also that the collector has + a very small :term:`root set`. Thirdly, it uses a simple + :term:`copying collector ` that is + easy to modify. .. seealso:: :term:`immutable`. @@ -473,9 +475,9 @@ Memory management in various languages Perl's :term:`memory management` is well-hidden, but is based on :term:`reference counts ` and :term:`garbage collection`. It also has *mortal* variables, - whose :term:`lifetimes ` are limited to the current - context. It is possible to :term:`free (1)` the :term:`memory - (2)` assigned to variables (including arrays) explicitly, by + whose :term:`lifetimes` are limited to the current context. It + is possible to :term:`free (1)` the :term:`memory (2)` + assigned to variables (including arrays) explicitly, by ``undef``\-ing the only reference to them. .. link:: @@ -525,11 +527,11 @@ Memory management in various languages Key features of Scheme include symbol and list operations, :term:`heap allocation` and :term:`garbage collection`, lexical scoping with first-class function objects (implying - :term:`closures `), reliable tail-call elimination - (allowing iterative procedures to be described - tail-recursively), the ability to dynamically obtain the - current :term:`continuation` as a first-class object, and a - language description that includes a formal semantics. + :term:`closures`), reliable tail-call elimination (allowing + iterative procedures to be described tail-recursively), the + ability to dynamically obtain the current :term:`continuation` + as a first-class object, and a language description that + includes a formal semantics. Scheme has been gaining popularity as an extension language; Project GNU's extension package of choice, `Guile @@ -552,7 +554,7 @@ Memory management in various languages Simula I, designed in 1962–64 by Kristen Nygaard and Ole-Johan Dahl, was based on :term:`ALGOL` 60, but the :term:`stack allocation` discipline was replaced by a two-dimensional - :term:`free-list `. + :term:`free list`. It was Simula 67 that pioneered classes and inheritance to express behavior. This domain-oriented design was supported by diff --git a/mps/manual/source/pool/amc.rst b/mps/manual/source/pool/amc.rst index 3faa2457b4e..d6a0ad26453 100644 --- a/mps/manual/source/pool/amc.rst +++ b/mps/manual/source/pool/amc.rst @@ -62,8 +62,7 @@ AMC introspection .. c:function:: void mps_amc_apply(mps_pool_t pool, mps_amc_apply_stepper_t f, void *p, size_t s) - Visit all :term:`formatted objects ` in an - AMC pool. + Visit all :term:`formatted objects` in an AMC pool. ``pool`` is the pool whose formatted objects you want to visit. @@ -80,10 +79,10 @@ AMC introspection calling :c:func:`mps_amc_apply`. The function ``f`` will be called on both :term:`client ` and :term:`padding objects `. It is the - job of ``f`` to distinguish, if necessary, between the two. It may - also be called on :term:`dead` objects that the collector has not - recycled or has been unable to recycle. + object>` and :term:`padding objects`. It is the job of ``f`` to + distinguish, if necessary, between the two. It may also be called + on :term:`dead` objects that the collector has not recycled or has + been unable to recycle. The function ``f`` may not allocate memory or access any automatically-managed memory except within ``object``. @@ -101,7 +100,7 @@ AMC introspection .. c:type:: void (*mps_amc_apply_stepper_t)(mps_addr_t object, void *p, size_t s) The type of a :term:`stepper function` for :term:`formatted - objects ` in an AMC pool. + objects` in an AMC pool. ``object`` is the address of an object in the pool. diff --git a/mps/manual/source/pool/index.rst b/mps/manual/source/pool/index.rst index de463bb8dfc..d6a83f32994 100644 --- a/mps/manual/source/pool/index.rst +++ b/mps/manual/source/pool/index.rst @@ -40,17 +40,16 @@ First, answer these questions about your data: management>` :term:`reclaim` :term:`unreachable` blocks? 2. Is it acceptable for the MPS to :term:`move ` blocks in memory and to place :term:`barriers ` on blocks? (For example, it might not be acceptable to move a - block if it has been passed to :term:`foreign code` that remembered - its location.) + manager>` blocks in memory and to place :term:`barriers (1)` on + blocks? (For example, it might not be acceptable to move a block if + it has been passed to :term:`foreign code` that remembered its + location.) -3. Do your blocks contain :term:`references ` to blocks - stored in automatically managed pools (including references to - other blocks in the same pool, if it's automatically managed)? And - if so, are these references :term:`exact `, - :term:`ambiguous ` or :term:`weak `? +3. Do your blocks contain :term:`references` to blocks stored in + automatically managed pools (including references to other blocks + in the same pool, if it's automatically managed)? And if so, are + these references :term:`exact `, :term:`ambiguous + ` or :term:`weak `? Second, look up your answers in this table to find the recommended pool class to use: @@ -75,10 +74,10 @@ no *any* weak :ref:`pool-mvt` [1]_ .. note:: .. [1] :ref:`pool-mvt` doesn't scan for references, but you can - work around this by registering your blocks as :term:`roots - ` (with the appropriate :term:`rank`) just after they - are allocated, and deregistering them just before freeing - them. + work around this by registering your blocks as + :term:`roots` (with the appropriate :term:`rank`) just + after they are allocated, and deregistering them just + before freeing them. .. Sources: @@ -94,9 +93,9 @@ This table summarizes the properties of each :term:`pool class` provided by the MPS. For "block" properties, "yes" means that the property holds for *all* blocks allocated from the pool. An entry "---" indicates that a property makes no sense for a pool class: for -example, if blocks in a pool may not contain :term:`references -`, it makes no sense to ask whether they may contain -:term:`weak references `. +example, if blocks in a pool may not contain :term:`references`, it +makes no sense to ask whether they may contain :term:`weak references +(1)`. ============================================= ===== ===== ===== ===== ===== ===== ===== ===== ===== @@ -134,8 +133,8 @@ Blocks must be formatted? [11]_ yes yes yes yes yes ` and :term:`incrementally `. - .. [3] Pools that may not contain references are suitable for storing - :term:`leaf objects ` only. + .. [3] Pools that may not contain references are suitable for + storing :term:`leaf objects` only. .. [4] Pools "may contain :term:`ambiguous ` / :term:`exact ` / :term:`weak `. + :term:`dependent object` which the client program + guarantees will be accessible during the scanning of the + first object. This may be used in the implementation of + :term:`weak hash tables`. .. [9] "Remote references" are references that are stored outside the block to which they logically belong (for example, in some kind @@ -171,8 +170,8 @@ Blocks must be formatted? [11]_ yes yes yes yes yes that these properties are not mutually exclusive, although the MPS does not provide a pool class that satisfies both. - .. [11] Blocks "are scanned" if the MPS :term:`scans ` them - for references; blocks "must be formatted" if they are + .. [11] Blocks "are scanned" if the MPS :term:`scans` them for + references; blocks "must be formatted" if they are described to the MPS by an :term:`object format`. At present, the MPS only knows how to scan blocks using the :term:`scan method` from an object format, but the MPS diff --git a/mps/manual/source/pool/mv.rst b/mps/manual/source/pool/mv.rst index 447af59ee37..cc51840bdad 100644 --- a/mps/manual/source/pool/mv.rst +++ b/mps/manual/source/pool/mv.rst @@ -6,12 +6,12 @@ MV (Manual Variable) The :term:`pool class` MV (Manual Variable) is a general-purpose class of :term:`manually managed ` pools that -manage :term:`blocks ` of variable size. +manage :term:`blocks` of variable size. It supports allocation via :c:func:`mps_alloc` and deallocation via :c:func:`mps_free`. -It does not support :term:`allocation points `. +It does not support :term:`allocation points`. ------------------- diff --git a/mps/manual/source/pool/mvt.rst b/mps/manual/source/pool/mvt.rst index 46c52519aba..3800d4dbec9 100644 --- a/mps/manual/source/pool/mvt.rst +++ b/mps/manual/source/pool/mvt.rst @@ -116,10 +116,10 @@ MVT symbol reference mps_count_t fragmentation_limit) ``minimum_size``, ``mean_size``, and ``maximum_size`` are the - predicted minimum, mean, and maximum :term:`size` of :term:`blocks - ` expected to be allocated in the pool. Blocks smaller than - ``minimum_size`` and larger than ``maximum_size`` may be - allocated, but the pool is not guaranteed to manage them + predicted minimum, mean, and maximum :term:`size` of + :term:`blocks` expected to be allocated in the pool. Blocks + smaller than ``minimum_size`` and larger than ``maximum_size`` may + be allocated, but the pool is not guaranteed to manage them space-efficiently. Furthermore, partial freeing is not supported for blocks larger than ``maximum_size``; doing so will result in the storage of the block never being reused. ``mean_size`` need diff --git a/mps/manual/source/todo.rst b/mps/manual/source/todo.rst index 943dbf5475c..0daa91ceb72 100644 --- a/mps/manual/source/todo.rst +++ b/mps/manual/source/todo.rst @@ -42,11 +42,6 @@ Outstanding about consistency. Also to demonstrate the "garbage collect frequently to expose errors as soon as possible" advice. -87. Could simplify a lot of glossary references if plurals were - handled automatically. That is, if a glossary entry for "bytes - (1)" is found to be missing, then "byte (1)" should be tried - instead. (Similarly for hyphens versus spaces.) - 95. Bring :ref:`lang` up to date. Add C#, Lua, Python. @@ -717,6 +712,11 @@ Complete .. _change 180031: http://info.ravenbrook.com/infosys/cgi/perfbrowse.cgi?@describe+180031 +87. Could simplify a lot of glossary references if plurals were + handled automatically. That is, if a glossary entry for "bytes + (1)" is found to be missing, then "byte (1)" should be tried + instead. (Similarly for hyphens versus spaces.) + 88. Where glossary entries differ on in hyphens versus spaces there's no need to give both. diff --git a/mps/manual/source/topic/allocation.rst b/mps/manual/source/topic/allocation.rst index f6677efec09..1845addab93 100644 --- a/mps/manual/source/topic/allocation.rst +++ b/mps/manual/source/topic/allocation.rst @@ -15,7 +15,7 @@ Manual allocation .. note:: - Not all :term:`pool classes ` support this interface: + Not all :term:`pool classes` support this interface: :term:`automatically managed ` pools typically support none of it, and even :term:`manually managed ` pools may not support the whole @@ -72,16 +72,16 @@ Manual allocation Allocation points ----------------- -:term:`Allocation points ` provide fast, -:term:`inline `, nearly :term:`lock-free ` allocation. They allow code to allocate without calling an -allocation function: this is vital for performance in languages or -programs that allocate many small objects. They must be used according -to the :ref:`topic-allocation-point-protocol`. +:term:`Allocation points` provide fast, :term:`inline `, nearly :term:`lock-free ` allocation. +They allow code to allocate without calling an allocation function: +this is vital for performance in languages or programs that allocate +many small objects. They must be used according to the +:ref:`topic-allocation-point-protocol`. .. c:type:: mps_ap_t - The type of :term:`allocation points `. It is a + The type of :term:`allocation points`. It is a :term:`transparent alias ` for a pointer to :c:type:`mps_ap_s`. @@ -137,7 +137,7 @@ Allocation point protocol ------------------------- This protocol is designed to work with :term:`incremental garbage -collection` and multiple :term:`threads `, where between any +collection` and multiple :term:`threads`, where between any two instructions in the :term:`client program`, the MPS may run part of a :term:`garbage collection`, :term:`move ` blocks in memory, rewrite pointers, and reclaim space. In order to @@ -147,9 +147,8 @@ least) two steps, a *reserve* followed by a *commit*. .. note:: The description of the protocol assumes that you have declared - your threads' :term:`control stacks ` and - :term:`registers ` to be :term:`ambiguous roots - `, by passing :c:func:`mps_stack_scan_ambig` to + your threads' :term:`control stacks` and + :term:`registers` to be :term:`ambiguous roots`, by passing :c:func:`mps_stack_scan_ambig` to :c:func:`mps_root_create_reg`. This is the simplest way to write a client. Other scenarios are possible, but not yet documented. @@ -378,7 +377,7 @@ Before calling :c:func:`mps_commit`: forwarding object, and so on). 2. All exact references in the new block (references that are - :term:`fixed ` by scanning functions) must contain valid + :term:`fixed` by scanning functions) must contain valid references. 3. The new object must be ambiguously :term:`reachable`. @@ -400,9 +399,9 @@ formatted object (at least in the debugging version of your program). .. note:: - Some :term:`pool classes ` have debugging counterparts - that automatically overwrite free space with a pattern of bytes of - your choosing. See :ref:`topic-debugging`. + Some :term:`pool classes` have debugging counterparts that + automatically overwrite free space with a pattern of bytes of your + choosing. See :ref:`topic-debugging`. Example: inserting into a doubly linked list @@ -589,7 +588,7 @@ branch prediction should work well since the test almost never fails). .. c:type:: mps_ap_s The type of the structure used to represent :term:`allocation - points `:: + points`:: typedef struct mps_ap_s { mps_addr_t init; diff --git a/mps/manual/source/topic/arena.rst b/mps/manual/source/topic/arena.rst index c3d52806598..9955a191054 100644 --- a/mps/manual/source/topic/arena.rst +++ b/mps/manual/source/topic/arena.rst @@ -35,10 +35,10 @@ other. Arenas do not normally interact, but they compete with each other for resources, and references from one arena to another are not - traced, though you *can* declare :term:`roots ` pointing + traced, though you *can* declare :term:`roots` pointing from one arena to another. It is not efficient to have multiple arenas containing :term:`automatically managed ` :term:`pools `: if you find yourself in this + management>` :term:`pools`: if you find yourself in this situation it's best to find a way to move all the automatically managed pools to one arena. @@ -55,16 +55,16 @@ the way that they acquire the memory to be managed. .. c:type:: mps_arena_t - The type of :term:`arenas `. + The type of :term:`arenas`. An arena is responsible for requesting :term:`memory (3)` from - the operating system, making it available to :term:`pools `, + the operating system, making it available to :term:`pools`, and for :term:`garbage collection`. .. c:type:: mps_arena_class_t - The type of :term:`arena classes `. + The type of :term:`arena classes`. .. c:function:: mps_res_t mps_arena_create(mps_arena_t *arena_o, mps_arena_class_t arena_class, ...) @@ -107,15 +107,13 @@ the way that they acquire the memory to be managed. This function checks the consistency of the arena, flushes the :term:`telemetry stream` and destroys the arena's internal control - structures. Additionally, :term:`virtual memory arenas ` return their reserved address space to the - operating system if possible. + structures. Additionally, :term:`virtual memory arenas` return + their reserved address space to the operating system if possible. It is an error to destroy an arena without first destroying all - :term:`generation chains `, :term:`object - formats `, :term:`pools ` and :term:`roots - ` created in the arena, and deregistering all :term:`threads - ` registered with the arena. + :term:`generation chains`, :term:`object formats`, :term:`pools` + and :term:`roots` created in the arena, and deregistering all + :term:`threads` registered with the arena. .. _topic-arena-client: @@ -188,7 +186,7 @@ Virtual memory arenas memory` interface to allocate memory. The chief consequence of this is that the arena can manage many more virtual addresses than it needs to commit memory to. This gives it flexibility as to - where to place :term:`blocks `, which reduces + where to place :term:`blocks`, which reduces :term:`fragmentation` and helps make :term:`garbage collection` more efficient. @@ -200,8 +198,8 @@ Virtual memory arenas size_t size) ``size`` is the initial amount of virtual address space, in - :term:`bytes `, that the arena will reserve (this space - is initially reserved so that the arena can subsequently use it + :term:`bytes (1)`, that the arena will reserve (this space is + initially reserved so that the arena can subsequently use it without interference from other parts of the program, but most of it is not committed, so it don't require any RAM or backing store). The arena may allocate more virtual address space beyond @@ -231,7 +229,7 @@ Arena properties .. c:function:: mps_word_t mps_collections(mps_arena_t arena) - Return the number of :term:`collection cycles ` + Return the number of :term:`collection cycles` that have been completed on an :term:`arena` since it was created. ``arena`` is the arena. @@ -244,9 +242,9 @@ Arena properties ``arena`` is the arena to return the commit limit for. - Returns the commit limit in :term:`bytes `. The commit - limit controls how much memory the MPS can obtain from the - operating system, and can be changed by calling + Returns the commit limit in :term:`bytes (1)`. The commit limit + controls how much memory the MPS can obtain from the operating + system, and can be changed by calling :c:func:`mps_arena_commit_limit_set`. @@ -256,7 +254,7 @@ Arena properties ``arena`` is the arena to change the commit limit for. - ``limit`` is the new commit limit in :term:`bytes `. + ``limit`` is the new commit limit in :term:`bytes (1)`. Returns :c:macro:`MPS_RES_OK` if successful, or another :term:`result code` if not. @@ -294,10 +292,10 @@ Arena properties ``arena`` is the arena. Returns the total amount of memory that has been committed to RAM - by the MPS, in :term:`bytes `. + by the MPS, in :term:`bytes (1)`. The committed memory is generally larger than the sum of the sizes - of the allocated :term:`blocks `. The reasons for this are: + of the allocated :term:`blocks`. The reasons for this are: * some memory is used internally by the MPS to manage its own data structures and to record information about allocated blocks @@ -306,7 +304,7 @@ Arena properties * operating systems (and hardware) typically restrict programs to requesting and releasing memory with a certain granularity (for - example, :term:`pages `), so extra memory is committed + example, :term:`pages`), so extra memory is committed when this rounding is necessary; * there might also be :term:`spare committed memory`: see @@ -335,7 +333,7 @@ Arena properties .. c:function:: size_t mps_arena_reserved(mps_arena_t arena) Return the total :term:`address space` reserved by an - :term:`arena`, in :term:`bytes `. + :term:`arena`, in :term:`bytes (1)`. ``arena`` is the arena. @@ -363,8 +361,8 @@ Arena properties ``arena`` is the arena to return the spare commit limit for. - Returns the spare commit limit in :term:`bytes `. The - spare commit limit can be changed by calling + Returns the spare commit limit in :term:`bytes (1)`. The spare + commit limit can be changed by calling :c:func:`mps_arena_spare_commit_limit_set`. @@ -374,7 +372,7 @@ Arena properties ``arena`` is the arena to change the spare commit limit for. - ``limit`` is the new spare commit limit in :term:`bytes `. + ``limit`` is the new spare commit limit in :term:`bytes (1)`. The spare commit limit is the maximum amount of :term:`spare committed memory` the MPS is allowed to have. Setting it to a @@ -426,15 +424,14 @@ An arena is always in one of three states. 1. In the *unclamped state*, garbage collection may take place, objects may move in memory, references may be updated, - :term:`location dependencies ` may become - stale, virtual memory may be requested from or return to the - operating system, and other kinds of background activity may - occur. This is the normal state. + :term:`location dependencies` may become stale, virtual memory may + be requested from or return to the operating system, and other + kinds of background activity may occur. This is the normal state. 2. In the *clamped state*, objects do not move in memory, references - do not change, the staleness of :term:`location dependencies - ` does not change, and memory occupied by - :term:`unreachable` objects is not recycled. + do not change, the staleness of :term:`location dependencies` does + not change, and memory occupied by :term:`unreachable` objects is + not recycled. However, a :term:`garbage collection` may be in progress and incremental collection may still occur, but it will not be visible @@ -469,10 +466,10 @@ can only be called in this state. ``arena`` is the arena to clamp. In the clamped state, no object motion will occur and the - staleness of :term:`location dependencies ` - will not change. All references to objects loaded while the arena - is clamped will keep the same binary representation until after it - is released by calling :c:func:`mps_arena_release`. + staleness of :term:`location dependencies` will not change. All + references to objects loaded while the arena is clamped will keep + the same binary representation until after it is released by + calling :c:func:`mps_arena_release`. In a clamped arena, incremental collection may still occur, but it will not be visible to the mutator and no new collections will @@ -487,10 +484,9 @@ can only be called in this state. ``arena`` is the arena to park. While an arena is parked, no object motion will occur and the - staleness of :term:`location dependencies ` - will not change. All references to objects loaded while the arena - is parked will keep the same binary representation until after it - is released. + staleness of :term:`location dependencies` will not change. All + references to objects loaded while the arena is parked will keep + the same binary representation until after it is released. Any current collection is run to completion before the arena is parked, and no new collections will start. When an arena is in the @@ -658,9 +654,9 @@ Arena introspection * :c:func:`mps_addr_fmt`: determine the :term:`object format` to which an address belongs; * :c:func:`mps_arena_formatted_objects_walk`: visit all - :term:`formatted objects ` in an arena; + :term:`formatted objects` in an arena; * :c:func:`mps_arena_roots_walk`: visit all references in - :term:`roots ` registered with an arena; and + :term:`roots` registered with an arena; and * :c:func:`mps_addr_pool`: determine the :term:`pool` to which an address belongs. @@ -716,7 +712,7 @@ Protection interface has the same effect as calling :c:func:`mps_arena_park`: all collections are run to completion, and the arena is clamped so that no new collections begin. The MPS also uses barriers to - maintain :term:`remembered sets `, so calling this + maintain :term:`remembered sets`, so calling this function will effectively destroy the remembered sets and any optimization gains from them. @@ -782,8 +778,7 @@ Protection interface remembered when the :term:`client program` called :c:func:`mps_arena_unsafe_expose_remember_protection`. The purpose of remembering and restoring the protection state is to avoid the - need for the MPS to recompute all the :term:`remembered sets - ` by scanning the entire arena, that occurs when + need for the MPS to recompute all the :term:`remembered sets` by scanning the entire arena, that occurs when :c:func:`mps_arena_expose` is used, and which causes the next :term:`garbage collection` to be slow. diff --git a/mps/manual/source/topic/cache.rst b/mps/manual/source/topic/cache.rst index 90904234d81..57f11f13973 100644 --- a/mps/manual/source/topic/cache.rst +++ b/mps/manual/source/topic/cache.rst @@ -168,8 +168,8 @@ Interface ``sac`` is the segregated allocation cache. ``size`` is the :term:`size` of the block to allocate. It does not - have to be one of the :term:`sizes classes ` of the - cache; nor does it have to be aligned. + have to be one of the :term:`size classes` of the cache; nor does + it have to be aligned. ``has_reservoir_permit`` should be false. @@ -194,13 +194,13 @@ Interface The :term:`client program` is responsible for synchronizing the access to the cache, but if the cache decides to access the pool, the MPS will properly synchronize with any other - :term:`threads ` that might be accessing the same + :term:`threads` that might be accessing the same pool. Blocks allocated through a segregated allocation cache should only be freed through a segregated allocation cache with the same class structure. Calling :c:func:`mps_free` on them can - cause :term:`memory leaks `, because the size of + cause :term:`memory leaks`, because the size of the block might be larger than you think. Naturally, the cache must also be attached to the same pool. @@ -225,8 +225,8 @@ Interface .. c:macro:: MPS_SAC_CLASS_LIMIT - The number of :term:`size classes ` that - :c:func:`mps_sac_create` is guaranteed to accept. + The number of :term:`size classes` that :c:func:`mps_sac_create` + is guaranteed to accept. More might be accepted: in fact, there might not be any limit in the implementation on the maximum number of size classes, but if @@ -257,7 +257,7 @@ Interface The :term:`client program` is responsible for synchronizing the access to the cache, but if the cache decides to access the pool, the MPS will properly synchronize with any other - :term:`threads ` that might be accessing the same + :term:`threads` that might be accessing the same pool. There's also a macro :c:func:`MPS_SAC_FREE_FAST` that does the @@ -265,7 +265,7 @@ Interface does no checking. :c:func:`mps_sac_free` does very little checking: it's - optimized for speed. :term:`Double frees ` and + optimized for speed. :term:`Double frees` and other mistakes will only be detected when the cache is flushed (either by calling :c:func:`mps_sac_flush` or automatically), and may not be detected at all, if intervening operations have @@ -321,8 +321,8 @@ Interface ``pool`` is the pool the cache is attached to. - ``classes_count`` is the number of :term:`size classes ` - in the cache. + ``classes_count`` is the number of :term:`size classes` in the + cache. ``classes`` points to an array describing the size classes in the cache. @@ -429,11 +429,10 @@ Interface The :term:`client program` is responsible for synchronizing the access to the cache, but if the cache decides to access the pool, the MPS will properly synchronize with any other - :term:`threads ` that might be accessing the same + :term:`threads` that might be accessing the same pool. .. c:type:: mps_sac_t - The type of :term:`segregated allocation caches `. + The type of :term:`segregated allocation caches`. diff --git a/mps/manual/source/topic/collection.rst b/mps/manual/source/topic/collection.rst index bac467d0815..fcb84fe0843 100644 --- a/mps/manual/source/topic/collection.rst +++ b/mps/manual/source/topic/collection.rst @@ -15,7 +15,7 @@ Generation chains Each :term:`automatically managed ` :term:`pool` has an associated :term:`generation chain` which -describes the structure of the :term:`generations ` in +describes the structure of the :term:`generations` in that pool. You create a generation chain by preparing an array of :c:type:`mps_gen_param_s` structures giving the *capacity* (in kilobytes) and *predicted mortality* (between 0 and 1) of each @@ -42,9 +42,8 @@ For example:: .. c:type:: mps_chain_t - The type of :term:`generation chains `. A - generation chain describes the structure of :term:`generations - ` in a :term:`pool`. + The type of :term:`generation chains`. A + generation chain describes the structure of :term:`generations` in a :term:`pool`. .. c:type:: mps_gen_param_s @@ -58,7 +57,7 @@ For example:: } mps_gen_param_s; ``mps_capacity`` is the capacity of the generation, in - :term:`kilobytes `. When the size of the generation + :term:`kilobytes`. When the size of the generation exceeds this, the MPS will be prepared to start collecting it. ``mps_mortality`` is the predicted mortality of the generation: @@ -80,7 +79,7 @@ For example:: ``arena`` is the arena to which the generation chain will belong. - ``gen_count`` is the number of :term:`generations ` in + ``gen_count`` is the number of :term:`generations` in the chain. ``gen_params`` points to an array describing the generations. @@ -230,7 +229,7 @@ Garbage collection messages * :c:func:`mps_message_gc_not_condemned_size` returns the approximate size of the set of objects that were in collected - :term:`pools `, but were not condemned in the garbage + :term:`pools`, but were not condemned in the garbage collection that generated the message. .. seealso:: @@ -287,7 +286,7 @@ Garbage collection messages :c:func:`mps_message_type_gc`. The "not condemned size" property is the approximate size of the - set of objects that were in collected :term:`pools `, but + set of objects that were in collected :term:`pools`, but were not in the :term:`condemned set` in the :term:`garbage collection` that generated the message. diff --git a/mps/manual/source/topic/critical.rst b/mps/manual/source/topic/critical.rst index e2570b9b676..802a210ba3b 100644 --- a/mps/manual/source/topic/critical.rst +++ b/mps/manual/source/topic/critical.rst @@ -21,8 +21,8 @@ What makes the critical path critical In order to determine which objects can be recycled, the :term:`garbage collector` has to frequently examine a very large number of pointers in the program's objects. It does this by :term:`scanning ` -memory, both allocated objects and :term:`roots ` (such as the -:term:`threads' ` :term:`control stacks `). +memory, both allocated objects and :term:`roots` (such as the +:term:`threads' ` :term:`control stacks`). This means that the scanning functions must loop over pretty much *every word in memory* sooner or later. The MPS takes great pains to @@ -98,8 +98,8 @@ Very briefly, the critical path consists of five stages: 1. The scanner, which iterates over pointers in objects. The MPS has several internal scanners, but the most important ones will be the - :term:`scan methods ` in the client program's - :term:`object formats `. See :ref:`topic-scanning`. + :term:`scan methods` in the client program's + :term:`object formats`. See :ref:`topic-scanning`. 2. The first-stage fix, which filters out pointers inline in the scanner. This is implemented in the :c:func:`MPS_FIX1` macro. diff --git a/mps/manual/source/topic/debugging.rst b/mps/manual/source/topic/debugging.rst index 21264d6522c..2c3fe0f6e94 100644 --- a/mps/manual/source/topic/debugging.rst +++ b/mps/manual/source/topic/debugging.rst @@ -7,14 +7,14 @@ Debugging pools =============== -Several :term:`pool classes ` have debugging counterparts -that provide two features that are useful for debugging: +Several :term:`pool classes` have debugging counterparts that provide +two features that are useful for debugging: * :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 `. + 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 @@ -53,8 +53,7 @@ For example:: .. c:type:: mps_pool_debug_option_s The type of the structure used to pass options to - :c:func:`mps_pool_create` for debugging :term:`pool classes `. :: + :c:func:`mps_pool_create` for debugging :term:`pool classes`. :: typedef struct mps_pool_debug_option_s { void *fence_template; @@ -63,12 +62,11 @@ For example:: size_t free_size; } mps_pool_debug_option_s; - ``fence_template`` points to a template for :term:`fenceposts - `. + ``fence_template`` points to a template for :term:`fenceposts`. ``fence_size`` is the :term:`size` of ``fence_template`` in - :term:`bytes `, or zero if the debugging pool should not - use fenceposts. + :term:`bytes (1)`, or zero if the debugging pool should not use + fenceposts. ``free_template`` points to a template for splatting free space. @@ -92,7 +90,7 @@ For example:: .. c:function:: void mps_pool_check_fenceposts(mps_pool_t pool) - Check all the :term:`fenceposts ` in a :term:`pool`. + Check all the :term:`fenceposts` in a :term:`pool`. ``pool`` is the pool whose fenceposts are to be checked. @@ -105,7 +103,7 @@ For example:: .. 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 ` + errors`. ``pool`` is the pool whose free space is to be checked. diff --git a/mps/manual/source/topic/error.rst b/mps/manual/source/topic/error.rst index d7fe7bbe599..6084f87dc66 100644 --- a/mps/manual/source/topic/error.rst +++ b/mps/manual/source/topic/error.rst @@ -14,8 +14,8 @@ are non-zero. The modular nature of the MPS means that it is not usually possible for a function description to list the possible error codes that it might return. A function in the public interface typically calls -methods of an :term:`arena class` and one or more :term:`pool classes -`, any of which might fail. The MPS is extensible with new +methods of an :term:`arena class` and one or more :term:`pool +classes`, any of which might fail. The MPS is extensible with new arena and pool classes, which might fail in new and interesting ways, so the only future-proof behaviour is for a :term:`client program` to assume that any MPS function that returns a result code can return @@ -24,7 +24,7 @@ assume that any MPS function that returns a result code can return .. c:type:: mps_res_t - The type of :term:`result codes `. It is a + The type of :term:`result codes`. It is a :term:`transparent alias ` for ``int``, provided for convenience and clarity. diff --git a/mps/manual/source/topic/finalization.rst b/mps/manual/source/topic/finalization.rst index 4654ce6b77e..4d4a5b9febe 100644 --- a/mps/manual/source/topic/finalization.rst +++ b/mps/manual/source/topic/finalization.rst @@ -20,10 +20,10 @@ A block requiring finalization must be registered by calling :c:func:`mps_finali A block that been registered for finalization becomes *finalizable* as soon as the :term:`garbage collector` observes that it would otherwise -be :term:`reclaimed ` (that is, the only thing keeping it -alive is the fact that it needs to be finalized). If a block is -finalizable the MPS may choose to finalize it (by posting a -finalization message: see below) at *any* future time. +be :term:`reclaimed` (that is, the only thing keeping it alive is the +fact that it needs to be finalized). If a block is finalizable the MPS +may choose to finalize it (by posting a finalization message: see +below) at *any* future time. .. note:: @@ -31,7 +31,7 @@ finalization message: see below) at *any* future time. then became unconditionally :term:`live` by the creation of a new :term:`strong reference` to it, may still be finalized. -:term:`Weak references ` do not prevent blocks +:term:`Weak references (1)` do not prevent blocks from being finalized. At the point that a block is finalized, weak references will still validly refer to the block. The fact that a block is registered for finalization prevents weak references to that @@ -251,9 +251,9 @@ Cautions deprecated. See Appendix A of [BOEHM02]_ for a discussion of this problem. -4. Not all :term:`pool classes ` support finalization. In - general, only pools that manage objects whose liveness is - determined by garbage collection do so. See the :ref:`pool`. +4. Not all :term:`pool classes` support finalization. In general, only + pools that manage objects whose liveness is determined by garbage + collection do so. See the :ref:`pool`. Finalization interface diff --git a/mps/manual/source/topic/format.rst b/mps/manual/source/topic/format.rst index 60fadad312a..2183e5f1ae7 100644 --- a/mps/manual/source/topic/format.rst +++ b/mps/manual/source/topic/format.rst @@ -10,7 +10,7 @@ Object formats The need for some means of describing objects in the :term:`client program` comes from :term:`tracing ` and :term:`moving `. During tracing, when an object is :term:`scanned -`, all the :term:`references ` in the object must be +`, all the :term:`references` in the object must be identified so that the objects they point to can be scanned in their turn. When an object has moved, references to that object must be identified so that they can be updated to point to the new location of @@ -22,16 +22,15 @@ represented (for example, are they tagged?). *Object formats* provide the means by which the client program communicates this information to the MPS. -An object format is a collection of :term:`format methods ` and other (usually scalar) values which together describe -programatically the layout of objects belonging to the format. Format -methods include the :term:`skip method` (which calculates an object's -size), the :term:`scan method` (which :term:`fixes ` references -in the object), and the :term:`forward method` (which replaces an -object that has moved with a :term:`forwarding object`). +An object format is a collection of :term:`format methods` and other +(usually scalar) values which together describe programatically the +layout of objects belonging to the format. Format methods include the +:term:`skip method` (which calculates an object's size), the +:term:`scan method` (which :term:`fixes ` references in the +object), and the :term:`forward method` (which replaces an object that +has moved with a :term:`forwarding object`). -Not every :term:`pool class` supports :term:`formatted objects -`. +Not every :term:`pool class` supports :term:`formatted objects`. .. c:type:: mps_fmt_t @@ -42,12 +41,12 @@ Not every :term:`pool class` supports :term:`formatted objects Creating an object format ------------------------- -Different :term:`pool classes ` use different sets of -format methods and values (for example, a non-moving pool does not -need forwarding objects, so its object formats do not need to contain -a forward method). To accommodate this variance, it is possible to -construct object formats from different collections of format methods -and values. Such a collection is called a *format variant*. +Different :term:`pool classes` use different sets of format methods +and values (for example, a non-moving pool does not need forwarding +objects, so its object formats do not need to contain a forward +method). To accommodate this variance, it is possible to construct +object formats from different collections of format methods and +values. Such a collection is called a *format variant*. There are three supported format variants. All are suitable for copying and moving pools. @@ -107,7 +106,7 @@ For example:: Broadly speaking, object formats of variant A are suitable for use in :term:`copying ` or :term:`moving - ` :term:`pools `. + ` :term:`pools`. ``align`` is an integer value specifying the alignment of objects allocated with this format. It should be large enough to satisfy @@ -134,8 +133,7 @@ For example:: :c:type:`mps_fmt_isfwd_t`. ``pad`` is a :term:`padding method` that creates :term:`padding - objects ` belonging to this format. See - :c:type:`mps_fmt_pad_t`. + objects` belonging to this format. See :c:type:`mps_fmt_pad_t`. .. c:function:: mps_res_t mps_fmt_create_A(mps_fmt_t *fmt_o, mps_arena_t arena, mps_fmt_A_s *fmt_A) @@ -251,7 +249,7 @@ For example:: Even if the header size is larger than or equal to :term:`alignment`, the :term:`padding method` must still be - able to create :term:`padding objects ` down + able to create :term:`padding objects` down to the alignment size. .. note:: @@ -361,8 +359,7 @@ Format methods object, or a null pointer if this is not possible. It is recommended that a null pointer be returned for - :term:`padding objects ` and :term:`forwarding - objects `. + :term:`padding objects` and :term:`forwarding objects`. .. c:type:: void (*mps_fmt_fwd_t)(mps_addr_t old, mps_addr_t new) @@ -431,7 +428,7 @@ Format methods object. Typically the MPS creates padding objects to fill in otherwise unused gaps in memory; they allow the MPS to pack objects into fixed-size units (such as operating system - :term:`pages `). + :term:`pages`). The padding method must create a padding object of the specified size at the specified address. The size can be any aligned (to the @@ -543,7 +540,7 @@ Object format introspection .. c:function:: void mps_arena_formatted_objects_walk(mps_arena_t arena, mps_formatted_objects_stepper_t f, void *p, size_t s) - Visit all :term:`formatted objects ` in an + Visit all :term:`formatted objects` in an :term:`arena`. ``arena`` is the arena whose formatted objects you want to visit. @@ -561,8 +558,7 @@ Object format introspection visited. During a :term:`trace` this will in general be only the :term:`black` objects, though the :ref:`pool-lo` pool, for example, will walk all objects since they are validly formatted - whether they are black or :term:`white`. :term:`Padding objects - ` may be visited at the pool class's discretion: + whether they are black or :term:`white`. :term:`Padding objects` may be visited at the pool class's discretion: the :term:`client program` should handle this case. The function ``f`` may not allocate memory or access any @@ -579,7 +575,7 @@ Object format introspection .. c:type:: void (*mps_formatted_objects_stepper_t)(mps_addr_t addr, mps_fmt_t fmt, mps_pool_t pool, void *p, size_t s) - The type of a :term:`formatted objects ` + The type of a :term:`formatted objects` :term:`stepper function`. A function of this type can be passed to diff --git a/mps/manual/source/topic/frame.rst b/mps/manual/source/topic/frame.rst index 60459ec91a6..06169148d34 100644 --- a/mps/manual/source/topic/frame.rst +++ b/mps/manual/source/topic/frame.rst @@ -22,7 +22,7 @@ efficiently implement stack-like patterns of allocation. .. c:type:: mps_frame_t - The type of :term:`allocation frames `. + The type of :term:`allocation frames`. .. c:function:: mps_res_t mps_ap_frame_push(mps_frame_t *frame_o, mps_ap_t ap) @@ -44,7 +44,7 @@ efficiently implement stack-like patterns of allocation. .. c:function:: mps_res_t mps_ap_frame_pop(mps_ap_t ap, mps_frame_t frame) - Declare that a set of :term:`blocks ` in a + Declare that a set of :term:`blocks` in a :term:`allocation frame` are :term:`dead` or likely to be dead, and pop the frame from the :term:`allocation point's ` frame stack. diff --git a/mps/manual/source/topic/interface.rst b/mps/manual/source/topic/interface.rst index 0d81c41a1f5..a541f05383c 100644 --- a/mps/manual/source/topic/interface.rst +++ b/mps/manual/source/topic/interface.rst @@ -234,8 +234,8 @@ General types .. c:type:: mps_addr_t - The type of :term:`addresses
` managed by the MPS, and - also the type of :term:`references `. + The type of :term:`addresses` managed by the MPS, and also the + type of :term:`references`. It is a :term:`transparent alias ` for ``void *``. diff --git a/mps/manual/source/topic/location.rst b/mps/manual/source/topic/location.rst index 07c1f176a35..0c248187279 100644 --- a/mps/manual/source/topic/location.rst +++ b/mps/manual/source/topic/location.rst @@ -348,14 +348,14 @@ Location dependency interface .. c:type:: mps_ld_t - The type of :term:`location dependencies `. - It is a :term:`transparent alias ` for a pointer - to :c:type:`mps_ld_s`. + The type of :term:`location dependencies`. It is a + :term:`transparent alias ` for a pointer to + :c:type:`mps_ld_s`. A location dependency records the fact that the :term:`client - program` depends on the bit patterns of some :term:`references - ` (and not merely on the identity of the :term:`block` - to which the reference refers), and provides a function + program` depends on the bit patterns of some :term:`references` + (and not merely on the identity of the :term:`block` to which the + reference refers), and provides a function (:c:func:`mps_ld_isstale`) to find out whether any of these references have been changed because a block has been :term:`moved `. @@ -412,7 +412,7 @@ Location dependency interface :c:func:`mps_ld_reset` on the same location dependency, but it is thread-safe with respect to :c:func:`mps_ld_isstale` operations. This means that calls to :c:func:`mps_ld_add` from - different :term:`threads ` must interlock if they are + different :term:`threads` must interlock if they are using the same location dependency. The practical upshot of this is that there should be a lock associated with each location dependency. diff --git a/mps/manual/source/topic/message.rst b/mps/manual/source/topic/message.rst index 91aa5945e42..a9740cf9c24 100644 --- a/mps/manual/source/topic/message.rst +++ b/mps/manual/source/topic/message.rst @@ -133,7 +133,7 @@ Message types .. c:type:: mps_message_type_t - The type of :term:`message types `. + The type of :term:`message types`. There are three message types: @@ -145,7 +145,7 @@ Message types .. c:function:: void mps_message_type_disable(mps_arena_t arena, mps_message_type_t message_type) Restore an :term:`arena` to the default state whereby - :term:`messages ` of the specified :term:`message type` + :term:`messages` of the specified :term:`message type` are not posted, reversing the effect of an earlier call to :c:func:`mps_message_type_enable`. @@ -164,7 +164,7 @@ Message types .. c:function:: void mps_message_type_enable(mps_arena_t arena, mps_message_type_t message_type) - Enable an :term:`arena` to post :term:`messages ` of a + Enable an :term:`arena` to post :term:`messages` of a specified :term:`message type`. ``arena`` is an arena. @@ -206,7 +206,7 @@ Message interface can be obtained by calling :c:func:`mps_message_get`. An :c:func:`mps_message_t` is a :term:`reference` into MPS managed - memory, and can safely be :term:`fixed `. + memory, and can safely be :term:`fixed`. .. c:function:: mps_clock_t mps_message_clock(mps_arena_t arena, mps_message_t message) @@ -301,8 +301,7 @@ Message queue interface .. c:function:: mps_bool_t mps_message_poll(mps_arena_t arena) - Determine whether there are currently any :term:`messages - ` on a :term:`message queue` for an :term:`arena`. + Determine whether there are currently any :term:`messages` on a :term:`message queue` for an :term:`arena`. ``arena`` is the arena whose message queue will be polled. @@ -317,8 +316,7 @@ Message queue interface .. c:function:: mps_bool_t mps_message_queue_type(mps_message_type_t *message_type_o, mps_arena_t arena) - Determine whether there are currently any :term:`messages - ` on a :term:`message queue` for an :term:`arena`, and + Determine whether there are currently any :term:`messages` on a :term:`message queue` for an :term:`arena`, and return the :term:`message type` of the first message, if any. ``message_type_o`` points to a location that will hold the message diff --git a/mps/manual/source/topic/pattern.rst b/mps/manual/source/topic/pattern.rst index dd7d783e776..2bbcbc450be 100644 --- a/mps/manual/source/topic/pattern.rst +++ b/mps/manual/source/topic/pattern.rst @@ -18,7 +18,7 @@ and :c:func:`mps_alloc_pattern_ramp_collect_all`. .. c:type:: mps_alloc_pattern_t - The type of :term:`allocation patterns `. + The type of :term:`allocation patterns`. .. c:function:: mps_res_t mps_ap_alloc_pattern_begin(mps_ap_t ap, mps_alloc_pattern_t alloc_pattern) diff --git a/mps/manual/source/topic/plinth.rst b/mps/manual/source/topic/plinth.rst index 0a8162b73ed..9761f308dee 100644 --- a/mps/manual/source/topic/plinth.rst +++ b/mps/manual/source/topic/plinth.rst @@ -87,7 +87,7 @@ Declared in ``mpsio.h`` ``buf`` points to the data to write. - ``size`` is the :term:`size` of the data in :term:`bytes `. + ``size`` is the :term:`size` of the data in :term:`bytes (1)`. Returns :c:macro:`MPS_RES_OK` if successful. @@ -120,7 +120,7 @@ Declared in ``mpslib.h`` A :term:`plinth` function similar to the standard :term:`C` function ``memcmp``. - ``s1`` and ``s2`` point to :term:`blocks ` of memory to be + ``s1`` and ``s2`` point to :term:`blocks` of memory to be compared. ``n`` is the :term:`size` of the blocks. diff --git a/mps/manual/source/topic/pool.rst b/mps/manual/source/topic/pool.rst index b89807d283a..9d8fd5344f6 100644 --- a/mps/manual/source/topic/pool.rst +++ b/mps/manual/source/topic/pool.rst @@ -9,7 +9,7 @@ making it available for allocation. .. c:type:: mps_pool_t - The type of :term:`pools `. + The type of :term:`pools`. A pool is responsible for requesting memory from the :term:`arena` and making it available to the :term:`client program` via @@ -63,19 +63,18 @@ making it available for allocation. pool may no longer be used. It is an error to destroy a pool without first destroying all - :term:`allocation points ` and :term:`segregated - allocation caches ` created in the - pool. + :term:`allocation points` and :term:`segregated allocation caches` + created in the pool. Pool classes ------------ -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 +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). See :ref:`pool` for a list of pool classes. @@ -83,7 +82,7 @@ See :ref:`pool` for a list of pool classes. .. c:type:: mps_class_t - The type of :term:`pool classes `. + The type of :term:`pool classes`. .. note:: diff --git a/mps/manual/source/topic/root.rst b/mps/manual/source/topic/root.rst index 838202ded7e..438ff5099a6 100644 --- a/mps/manual/source/topic/root.rst +++ b/mps/manual/source/topic/root.rst @@ -7,14 +7,14 @@ Roots ===== -:term:`Roots ` tell the :term:`garbage collector` where to start +:term:`Roots` tell the :term:`garbage collector` where to start :term:`tracing `. The garbage collector determines which blocks are :term:`reachable` from the roots, and (in :term:`automatically -managed ` :term:`pools `) reclaims +managed ` :term:`pools`) reclaims the :term:`unreachable` blocks. This is quite efficient and can be a very good approximation to :term:`liveness `. -It is therefore important that the all :term:`references ` +It is therefore important that the all :term:`references` that the :term:`client program` can directly access are registered as roots, otherwise the garbage collector might recycle an object that would be used in the future. Some collectors, for example Boehm's, @@ -28,8 +28,8 @@ Registering roots You can register a root at any time by calling one of the ``mps_root_create`` functions. Roots may not be regstered twice, and -no two roots may overlap (that is, each reference is :term:`fixed -` by at most one root). Roots may be: +no two roots may overlap (that is, each reference is :term:`fixed` by +at most one root). Roots may be: 1. on the program's :term:`control stack`; @@ -90,7 +90,7 @@ scan it for references: references; 4. :c:func:`mps_root_create_table_masked` if the root consists of a - table of :term:`tagged references `; + table of :term:`tagged references`; 5. :c:func:`mps_root_create_reg` if the root consists of the registers and control stack of a thread. See @@ -148,25 +148,24 @@ Ranks .. c:type:: mps_rank_t - The type of :term:`ranks `. It is a :term:`transparent alias + The type of :term:`ranks`. It is a :term:`transparent alias ` for ``unsigned int``, provided for convenience and clarity. .. c:function:: mps_rank_t mps_rank_ambig(void) - Return the :term:`rank` of :term:`ambiguous roots `. + Return the :term:`rank` of :term:`ambiguous roots`. .. c:function:: mps_rank_t mps_rank_exact(void) - Return the :term:`rank` of :term:`exact roots `. + Return the :term:`rank` of :term:`exact roots`. .. c:function:: mps_rank_t mps_rank_weak(void) - Return the :term:`rank` of :term:`weak roots `. + Return the :term:`rank` of :term:`weak roots`. Root modes @@ -187,7 +186,7 @@ allowing the MPS to detect whether they have changed. .. c:type:: mps_rm_t - The type of :term:`root modes `. + The type of :term:`root modes`. It should be the sum of some subset of :c:macro:`MPS_RM_CONST` and :c:macro:`MPS_RM_PROT`, or zero (meaning neither constant or @@ -196,10 +195,10 @@ allowing the MPS to detect whether they have changed. .. c:macro:: MPS_RM_CONST - The :term:`root mode` for :term:`constant roots `. + The :term:`root mode` for :term:`constant roots`. This tells the MPS that the :term:`client program` will not change the :term:`root` after it is registered: that is, scanning the - root will produce the same set of :term:`references ` + root will produce the same set of :term:`references` every time. Furthermore, for roots registered by :c:func:`mps_root_create_fmt` and :c:func:`mps_root_create_table`, the client program will not write to the root at all. @@ -207,12 +206,11 @@ allowing the MPS to detect whether they have changed. .. c:macro:: MPS_RM_PROT - The :term:`root mode` for :term:`protectable roots `. This tells the MPS that it may place a :term:`write - barrier` on any :term:`page` which any part of the :term:`root` - covers. No :term:`format method` or :term:`scan method` (except - for the one for this root) may write data in this root. They may - read it. + The :term:`root mode` for :term:`protectable roots`. This tells + the MPS that it may place a :term:`write barrier` on any + :term:`page` which any part of the :term:`root` covers. No + :term:`format method` or :term:`scan method` (except for the one + for this root) may write data in this root. They may read it. .. note:: @@ -236,15 +234,14 @@ Root interface The type of :term:`root` descriptions. - The :term:`arena` uses root descriptions to find :term:`references - ` within the :term:`client program's ` - roots. + The :term:`arena` uses root descriptions to find + :term:`references` within the :term:`client program's ` roots. .. c:function:: mps_res_t mps_root_create(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_root_scan_t root_scan, void *p, size_t s) - Register a :term:`root` that consists of the :term:`references - ` fixed by a scanning function. + Register a :term:`root` that consists of the :term:`references` fixed by a scanning function. ``root_o`` points to a location that will hold the address of the new root description. @@ -294,9 +291,8 @@ Root interface .. c:function:: mps_res_t mps_root_create_fmt(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_fmt_scan_t fmt_scan, mps_addr_t base, mps_addr_t limit) - Register a :term:`root` that consists of the :term:`references - ` fixed by a scanning function in a block of - :term:`formatted objects `. + Register a :term:`root` that consists of the :term:`references` fixed by a scanning function in a block of + :term:`formatted objects`. ``root_o`` points to a location that will hold the address of the new root description. @@ -325,9 +321,8 @@ Root interface .. c:function:: mps_res_t mps_root_create_reg(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_thr_t thr, mps_reg_scan_t reg_scan, void *p, size_t s) - Register a :term:`root` that consists of the :term:`references - ` fixed in a :term:`thread's ` stack by a - scanning function. + Register a :term:`root` that consists of the :term:`references` + fixed in a :term:`thread's ` stack by a scanning function. ``root_o`` points to a location that will hold the address of the new root description. @@ -356,10 +351,9 @@ Root interface .. note:: - It is not supported for :term:`client programs ` to pass their own scanning functions to this - function. The built-in MPS function - :c:func:`mps_stack_scan_ambig` must be used. + It is not supported for :term:`client programs` to pass their + own scanning functions to this function. The built-in MPS + function :c:func:`mps_stack_scan_ambig` must be used. .. c:type:: mps_res_t (*mps_reg_scan_t)(mps_ss_t ss, mps_thr_t thr, void *p, size_t s) @@ -395,7 +389,7 @@ Root interface .. note:: - :term:`Client programs ` are not expected to + :term:`Client programs` are not expected to write scanning functions of this type. The built-in MPS function :c:func:`mps_stack_scan_ambig` must be used. @@ -403,16 +397,16 @@ Root interface .. c:function:: mps_reg_scan_t mps_stack_scan_ambig A root scanning function for :term:`ambiguous ` scanning of :term:`threads `, suitable for + reference>` scanning of :term:`threads`, suitable for passing to :c:func:`mps_root_create_reg`. It scans all integer registers and everything on the stack of the thread given, and can therefore only be used with :term:`ambiguous - roots `. It only scans locations that are at, or - higher on the stack (that is, more recently added), the stack - bottom that was passed to :c:func:`mps_thread_reg`. References - are assumed to be represented as machine words, and are required - to be 4-byte-aligned; unaligned values are ignored. + roots`. It only scans locations that are at, or higher on the + stack (that is, more recently added), the stack bottom that was + passed to :c:func:`mps_thread_reg`. References are assumed to be + represented as machine words, and are required to be + 4-byte-aligned; unaligned values are ignored. .. seealso:: @@ -428,7 +422,7 @@ Root interface .. c:function:: mps_res_t mps_root_create_table(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_addr_t *base, size_t count) Register a :term:`root` that consists of a vector of - :term:`references `. + :term:`references`. ``root_o`` points to a location that will hold the address of the new root description. @@ -455,7 +449,7 @@ Root interface .. c:function:: mps_res_t mps_root_create_table_masked(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_addr_t *base, size_t count, mps_word_t mask) Register a :term:`root` that consists of a vector of :term:`tagged - references `. + references`. ``root_o`` points to a location that will hold the address of the new root description. @@ -515,7 +509,7 @@ Root introspection .. c:function:: void mps_arena_roots_walk(mps_arena_t arena, mps_roots_stepper_t f, void *p, size_t s) - Visit references in registered :term:`roots ` in an + Visit references in registered :term:`roots` in an :term:`arena`. ``arena`` is the arena whose roots you want to visit. diff --git a/mps/manual/source/topic/scanning.rst b/mps/manual/source/topic/scanning.rst index 8639b9828b3..33a7d69c402 100644 --- a/mps/manual/source/topic/scanning.rst +++ b/mps/manual/source/topic/scanning.rst @@ -8,7 +8,7 @@ Scanning ======== :term:`Scanning ` is the process of identifying the -:term:`references ` in a block of memory and +:term:`references` in a block of memory and :term:`"fixing" ` them. It's the process at the heart of the Memory Pool System, and the most critical of the memory management functions that have to be implemented by the :term:`client program`. @@ -176,8 +176,7 @@ reassemble and store the updated reference after calling Unfixed references ------------------ -The MPS does not require you to :term:`fix` all your :term:`references -`. But if a reference is not fixed: +The MPS does not require you to :term:`fix` all your :term:`references`. But if a reference is not fixed: 1. it does not keep its target alive (this might be acceptable if you know that the target is being kept alive for another reason, for @@ -271,12 +270,12 @@ Scanning interface .. c:type:: mps_ss_t - The type of :term:`scan states `. + The type of :term:`scan states`. A scan state represents the state of the current :term:`scan`. The MPS passes a scan state to the :term:`scan method` of an :term:`object format` when it needs to :term:`scan` for - :term:`references ` within a region of memory. The scan + :term:`references` within a region of memory. The scan method must pass the scan state to :c:func:`MPS_SCAN_BEGIN` and :c:func:`MPS_SCAN_END` to delimit a sequence of fix operations, and to the functions :c:func:`MPS_FIX1`, :c:func:`MPS_FIX2` and @@ -343,9 +342,9 @@ Scanning interface Between :c:func:`MPS_SCAN_BEGIN` and :c:func:`MPS_SCAN_END`, the scan state is in a special state, and must not be passed to a function. If you really need to do so, for example because you - have a structure shared between two :term:`object formats `, you must wrap the call with :c:func:`MPS_FIX_CALL` to - ensure that the scan state is passed correctly. + have a structure shared between two :term:`object formats`, you + must wrap the call with :c:func:`MPS_FIX_CALL` to ensure that the + scan state is passed correctly. In example below, the scan method ``obj_scan`` fixes the object's ``left`` and ``right`` references, but delegates the scanning of diff --git a/mps/manual/source/topic/telemetry.rst b/mps/manual/source/topic/telemetry.rst index d80b458974e..551e6f78629 100644 --- a/mps/manual/source/topic/telemetry.rst +++ b/mps/manual/source/topic/telemetry.rst @@ -36,9 +36,9 @@ John McCarthy described the first on-line demonstration of Introduction ------------ -In its :term:`cool` and :term:`hot` :term:`varieties `, the -MPS is capable of outputting a configurable stream of events to assist -with debugging and profiling. +In its :term:`cool` and :term:`hot` :term:`varieties`, the MPS is +capable of outputting a configurable stream of events to assist with +debugging and profiling. The selection of events that appear in the stream is controlled by the environment variable :envvar:`MPS_TELEMETRY_CONTROL` (by default diff --git a/mps/manual/source/topic/thread.rst b/mps/manual/source/topic/thread.rst index dcd5676bf37..05d82edf8cb 100644 --- a/mps/manual/source/topic/thread.rst +++ b/mps/manual/source/topic/thread.rst @@ -13,13 +13,13 @@ Thread safety The MPS is designed to run in an environment with multiple threads all calling into the MPS. Some code is known to operate with exclusive access to the data it manipulates (for example, allocation via -:term:`allocation points `, in the common case where -the buffer does not need to be refilled, and :term:`location -dependencies `), so this code is safe. For the -rest of the code, shared data structures are locked by the use of a -single lock per :term:`arena`. This lock is claimed on entry to the -MPS and released on exit from it. So there is at most a single thread -(per arena) running "inside" the MPS at a time. +:term:`allocation points`, in the common case where the buffer does +not need to be refilled, and :term:`location dependencies`), so this +code is safe. For the rest of the code, shared data structures are +locked by the use of a single lock per :term:`arena`. This lock is +claimed on entry to the MPS and released on exit from it. So there is +at most a single thread (per arena) running "inside" the MPS at a +time. Thread registration @@ -41,9 +41,9 @@ arenas. Signal handling issues ---------------------- -The MPS uses :term:`barriers ` to :term:`protect -` memory from the :term:`client program` and handles the -signals that result from barrier hits. +The MPS uses :term:`barriers (1)` to :term:`protect ` +memory from the :term:`client program` and handles the signals that +result from barrier hits. On some operating systems, barrier hits generate exceptions that have to be caught by a handler that is on the stack. On these operating @@ -100,7 +100,7 @@ Thread interface .. c:function:: void mps_thread_dereg(mps_thr_t thr) - Deregister a :term:`thread `. + Deregister a :term:`thread`. ``thr`` is the description of the thread. @@ -142,7 +142,7 @@ Thread interface time it is called. This is intended to make it easy to pass, for example, an array and its size as parameters. - The MPS relies on :term:`barriers ` to protect memory + The MPS relies on :term:`barriers (1)` to protect memory that is in an inconsistent state. On some operating systems, barrier hits generate exceptions that have to be caught by a handler that is on the stack. On these operating systems, any code