.. mode: -*- rst -*-

MPS Design Documents
====================
:Author: Richard Brooksby
:Organization: Ravenbrook Limited
:Date: 2002-05-23
:Revision: $Id$
:Readership: developers
:Confidentiality: public
:Type: index
:Copyright: See `Copyright and License`_.


Introduction
------------

This is the catalogue of design documents of the Memory Pool System
product.

.. warning::

   This is not a complete set of design documents for the MPS.  We have
   many hundreds of documents from before the MPS was acquired by
   Ravenbrook on 2001-08-10, many of which contain confidential
   information [RB_2002-06-18]_.  We are sorting through these and will
   include more as time goes on.  We have tried to select the key
   documents for inclusion in the open source release, by including
   those documents referenced by the source code.

   If there is a document you think might exist and want to see it,
   please write to mps-questions@ravenbrook.com and we will try to dig
   it up.


Designs
-------

.. class:: index

======================  ================================================
abq_                    Fixed-length queues
alloc-frame_            Allocation frame protocol
an_                     Generic modules
arena_                  Arena
arenavm_                Virtual memory arena
bootstrap_              Bootstrapping
bt_                     Bit tables
buffer_                 Allocation buffers and allocation points
cbs_                    Coalescing block structures
check_                  Checking
clock_                  Fast high-resolution clock
collection_             Collection framework
config_                 MPS configuration
critical-path_          The critical path through the MPS
diag_                   Diagnostic feedback
doc_                    Documentation
exec-env_               Execution environment
failover_               Fail-over allocator
finalize_               Finalization
fix_                    The generic fix function
freelist_               Free list allocator
guide.developer_        Guide for new developers
guide.hex.trans_        Transliterating the alphabet into hexadecimal
guide.impl.c.format_    Coding standard: conventions for the general format of C source code in the MPS
guide.impl.c.naming_    Coding standard: conventions for internal names
guide.review_           Review checklist
interface-c_            C interface
io_                     I/O subsystem
keyword-arguments_      Keyword arguments
land_                   Lands (collections of address ranges)
lib_                    Library interface
lock_                   Lock module
locus_                  Locus manager
message_                Client message protocol
message-gc_             GC messages
monitor_                Monitor
nailboard_              Nailboards for ambiguously referenced segments
object-debug_           Debugging features for client objects
pool_                   Pool classes
poolamc_                Automatic Mostly-Copying pool class
poolams_                Automatic Mark-and-Sweep pool class
poolawl_                Automatic Weak Linked pool class
poollo_                 Leaf Object pool class
poolmfs_                Manual Fixed Small pool class
poolmrg_                Manual Rank Guardian pool class
poolmvt_                Manual Variable Temporal pool class
poolmvff_               Manual Variable First-Fit pool class
prmc_                   Mutator context
prot_                   Memory protection
protix_                 POSIX implementation of protection module
protocol_               Protocol inheritance
pthreadext_             POSIX thread extensions
range_                  Ranges of addresses
ring_                   Ring data structure
root_                   Root manager
scan_                   The generic scanner
seg_                    Segment data structure
shield_                 Shield
sig_                    Signatures in the MPS
sp_                     Stack probe
splay_                  Splay trees
stack-scan_             Stack and register scanning
strategy_               Collection strategy
telemetry_              Telemetry
tests_                  Tests
testthr_                Multi-threaded testing
thread-manager_         Thread manager
thread-safety_          Thread safety in the MPS
trace_                  Tracer
transform_              Transforms
type_                   General MPS types
version-library_        Library version mechanism
vm_                     Virtual mapping
walk_                   Walking formatted objects
write-barrier_          Write Barrier
writef_                 The WriteF function
======================  ================================================

.. _abq: abq
.. _alloc-frame: alloc-frame
.. _an: an
.. _arena: arena
.. _arenavm: arenavm
.. _bootstrap: bootstrap
.. _bt: bt
.. _buffer: buffer
.. _cbs: cbs
.. _check: check
.. _clock: clock
.. _collection: collection
.. _config: config
.. _critical-path: critical-path
.. _diag: diag
.. _doc: doc
.. _exec-env: exec-env
.. _failover: failover
.. _finalize: finalize
.. _fix: fix
.. _freelist: freelist
.. _guide.developer: guide.developer
.. _guide.hex.trans: guide.hex.trans
.. _guide.impl.c.format: guide.impl.c.format
.. _guide.impl.c.naming: guide.impl.c.naming
.. _guide.review: guide.review
.. _interface-c: interface-c
.. _io: io
.. _keyword-arguments: keyword-arguments
.. _land: land
.. _lib: lib
.. _lock: lock
.. _locus: locus
.. _message: message
.. _message-gc: message-gc
.. _monitor: monitor
.. _nailboard: nailboard
.. _object-debug: object-debug
.. _pool: pool
.. _poolamc: poolamc
.. _poolams: poolams
.. _poolawl: poolawl
.. _poollo: poollo
.. _poolmfs: poolmfs
.. _poolmrg: poolmrg
.. _poolmvt: poolmvt
.. _poolmvff: poolmvff
.. _prmc: prmc
.. _prot: prot
.. _protix: protix
.. _protocol: protocol
.. _pthreadext: pthreadext
.. _range: range
.. _ring: ring
.. _root: root
.. _scan: scan
.. _seg: seg
.. _shield: shield
.. _sig: sig
.. _sp: sp
.. _splay: splay
.. _stack-scan: stack-scan
.. _strategy: strategy
.. _telemetry: telemetry
.. _tests: tests
.. _testthr: testthr
.. _thread-manager: thread-manager
.. _thread-safety: thread-safety
.. _trace: trace
.. _transform: transform
.. _type: type
.. _version-library: version-library
.. _vm: vm
.. _walk: walk
.. _write-barrier: write-barrier
.. _writef: writef


References
----------

.. [RB_2002-06-18]
   "The Obsolete Memory Management Information System";
   Richard Brooksby;
   Ravenbrook Limited;
   2002-06-18;
   <https://www.ravenbrook.com/project/mps/doc/2002-06-18/obsolete-mminfo>.


Document History
----------------

- 2002-05-23    RB_     Created empty catalogue based on P4DTI design document catalogue.
- 2002-06-07    RB_     Added a bunch of design documents referenced by the source code.
- 2002-06-21    NB_     Remove P4DTI reference, which doesn't fit here. Maybe one day we'll have a corporate design document procedure.
- 2002-06-24    RB_     Added fix, object-debug, thread-manager, and thread-safety.
- 2007-02-08    RHSK    Added message-gc and shield.
- 2007-06-12    RHSK    Added cstyle.
- 2007-06-28    RHSK    Added diag.
- 2008-12-04    RHSK    Added tests.
- 2008-12-10    RHSK    Correct description of message-gc: gc begin or end.
- 2012-09-14    RB_     Added link to critical-path
- 2013-05-10    RB_     Fixed link to sig and added guide.hex.trans
- 2013-05-22    GDR_    Add link to keyword-arguments.
- 2013-05-25    RB_     Replacing "cstyle" with reworked "guide.impl.c.format".
- 2013-06-07    RB_     Converting to reST_.  Linking to [RB_2002-06-18]_.
- 2014-01-29    RB_     The arena no longer manages generation zonesets.
- 2014-01-17    GDR_    Add abq, nailboard, range.
- 2016-03-22    RB_     Add write-barier.
- 2016-03-27    RB_     Goodbye pool MV *sniff*.
- 2020-08-31    GDR_    Add walk.
- 2023-06-16    RB_     Add transform.

.. _RB: https://www.ravenbrook.com/consultants/rb
.. _NB: https://www.ravenbrook.com/consultants/nb
.. _GDR: https://www.ravenbrook.com/consultants/gdr
.. _reST: http://docutils.sourceforge.net/rst.html


Copyright and License
---------------------

Copyright © 2002–2023 `Ravenbrook Limited <https://www.ravenbrook.com/>`_.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
