.. highlight:: none


.. index::
   pair: generic modules; design

.. _design-an:


Generic modules
===============

.. mps:prefix:: design.mps.an


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

:mps:tag:`intro` This is the design of generic modules in the MPS.

:mps:tag:`readership` Any MPS developer; anyone porting the MPS to a new
platform.

:mps:tag:`overview` Generic modules provide implementations of functional
modules using only the features of the Standard C Library. These
implementations are partially functional or non-functional, but
provide a basis for ports of the MPS to new platforms.

:mps:tag:`name` The name "ANSI" for the generic modules is historical: the C
language was originally standardized by the American National
Standards Institute, and so Standard C used to be known as "ANSI C".


Requirements
------------

:mps:tag:`req.port` The MPS must be portable to new platforms. (Otherwise we
can't meet the needs of customers using new platforms.)

:mps:tag:`req.port.rapid` The MPS should be portable to new platforms
rapidly.

:mps:tag:`req.port.rapid.expert` An expert MPS developer (who may be a
novice on the new platform) should be able to get a minimally useful
implementation of the MPS running on a new platform within a few
hours.

:mps:tag:`req.port.rapid.novice` A novice MPS developer (who is an expert on
the new platform) should be able to get the MPS running on a new
platform within a few days.


Design
------

:mps:tag:`sol.modules` Features of the MPS which can benefit from
platform-specific implementations are divided into *functional
modules*, with clean interfaces to the MPS and to each other. See
:mps:ref:`.mod` for a list of these modules. (This helps meet :mps:ref:`.req.port` by
isolating the platform dependencies, and it helps meet
:mps:ref:`.req.port.rapid` because a porter can mix and match implementations,
using existing implementations where possible.)

:mps:tag:`sol.generic` Each functional module has a generic implementation
using only features of the Standard C Library. (This helps meet
:mps:ref:`.req.port.rapid` because the MPS can be ported in stages, starting
with the generic modules and porting the modules needed to meet the
most urgent requirements. The generic implementations help meet
:mps:ref:`.req.port.rapid.novice` by providing clear and illustrative
examples.)

:mps:tag:`sol.fallback` The interfaces to the modules are designed to make
it possible to implement :mps:ref:`.sol.generic`. When a platform-specific
feature is needed to meet performance (or other attribute)
requirements, the interface also makes it possible to meet the
functional requirements while missing the attribute requirements. See
:mps:ref:`.sol.fallback.example` for an example. (This helps meet
:mps:ref:`.req.port.rapid` by allowing the generic implementations to meet
many or most of the functional requirements.)

:mps:tag:`sol.fallback.example` The MPS normally uses incremental collection
to meet requirements on pause times, but this requires barriers. The
interface to the protection module is designed to make it possible to
write an implementation without barriers, via the function
:c:func:`ProtSync()` that synchronizes the mutator with the collector.

:mps:tag:`sol.test` There are makefiles for the pseudo-platforms ``anangc``,
``ananll`` and ``ananmv`` that compile and test the generic
implementations. See design.mps.config.opt_ for the configuration
options used to implement these platforms. (This supports
:mps:ref:`.req.port.rapid` by making sure that the generic implementations are
working when it is time to use them.)

.. _design.mps.config.opt: config.html#design.mps.config.opt


Modules
-------

:mps:tag:`mod` This section lists the functional modules in the MPS.

:mps:tag:`mod.lock` Locks. See design.mps.lock_.

:mps:tag:`mod.prmc` Mutator context. See design.mps.prmc_.

:mps:tag:`mod.prot` Memory protection. See design.mps.prot_.

:mps:tag:`mod.sp` Stack probe. See design.mps.sp_.

:mps:tag:`mod.ss` Stack scanning. See design.mps.stack-scan_.

:mps:tag:`mod.th` Thread manager. See design.mps.thread-manager_.

:mps:tag:`mod.vm` Virtual mapping. See design.mps.vm_.

.. _design.mps.lock: lock.html
.. _design.mps.prot: prot.html
.. _design.mps.prmc: prmc.html
.. _design.mps.sp: sp.html
.. _design.mps.stack-scan: stack-scan.html
.. _design.mps.thread-manager: thread-manager.html
.. _design.mps.vm: vm.html


Limitations of generic implementations
--------------------------------------

:mps:tag:`lim` This section summarizes the limitations of the generic
implementations of the function modules.

:mps:tag:`lim.lock` Requires a single-threaded mutator (see
design.mps.lock.impl.an_).

:mps:tag:`lim.prmc` Does not support single-stepping of accesses (see
design.mps.prmc.impl.an.fault_) and requires a single-threaded mutator
(see design.mps.prmc.impl.an.suspend_).

:mps:tag:`lim.prot` Does not support incremental collection (see
design.mps.prot.impl.an.sync_) and is not compatible with
implementations of the mutator context module that support
single-stepping of accesses (see design.mps.prot.impl.an.sync.issue_).

:mps:tag:`lim.sp` Only suitable for use with programs that do not handle
stack overflow faults, or do not call into the MPS from the handler
(see design.mps.sp.issue.an_).

:mps:tag:`lim.stack-scan` Assumes that the stack grows downwards and that
:c:func:`setjmp()` reliably captures the registers (see design.mps.stack-scan.sol.stack.platform_).

:mps:tag:`lim.th` Requires a single-threaded mutator (see
design.mps.thread-manager.impl.an.single_).

:mps:tag:`lim.vm` Maps all reserved addresses into main memory (see
design.mps.vm.impl.an.reserve_), thus using more main memory than a
platform-specific implementation.

.. _design.mps.lock.impl.an: lock.html#design.mps.lock.impl.an
.. _design.mps.prmc.impl.an.fault: prmc.html#design.mps.prmc.impl.an.fault
.. _design.mps.prmc.impl.an.suspend: prmc.html#design.mps.prmc.impl.an.suspend
.. _design.mps.prot.impl.an.sync: prot.html#design.mps.prot.impl.an.sync
.. _design.mps.prot.impl.an.sync.issue: prot.html#design.mps.prot.impl.an.sync.issue
.. _design.mps.sp.issue.an: sp.html#design.mps.sp.issue.an
.. _design.mps.stack-scan.sol.stack.platform: stack-scan.html#design.mps.stack-scan.sol.stack.platform
.. _design.mps.thread-manager.impl.an.single: thread-manager.html#design.mps.thread-manager.impl.an.single
.. _design.mps.vm.impl.an.reserve: vm.html#design.mps.vm.impl.an.reserve