.. mode: -*- rst -*- Generic modules =============== :Tag: design.mps.an :Author: Gareth Rees :Date: 2014-11-02 :Status: complete design :Revision: $Id: //info.ravenbrook.com/project/mps/master/design/an.txt#9 $ :Copyright: See `Copyright and License`_. :Index terms: pair: generic modules; design Introduction ------------ _`.intro`: This is the design of generic modules in the MPS. _`.readership`: Any MPS developer; anyone porting the MPS to a new platform. _`.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. _`.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 ------------ _`.req.port`: The MPS must be portable to new platforms. (Otherwise we can't meet the needs of customers using new platforms.) _`.req.port.rapid`: The MPS should be portable to new platforms rapidly. _`.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. _`.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 ------ _`.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 `.mod`_ for a list of these modules. (This helps meet `.req.port`_ by isolating the platform dependencies, and it helps meet `.req.port.rapid`_ because a porter can mix and match implementations, using existing implementations where possible.) _`.sol.generic`: Each functional module has a generic implementation using only features of the Standard C Library. (This helps meet `.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 `.req.port.rapid.novice`_ by providing clear and illustrative examples.) _`.sol.fallback`: The interfaces to the modules are designed to make it possible to implement `.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 `.sol.fallback.example`_ for an example. (This helps meet `.req.port.rapid`_ by allowing the generic implementations to meet many or most of the functional requirements.) _`.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 ``ProtSync()`` that synchronizes the mutator with the collector. _`.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 `.req.port.rapid`_ by making sure that the generic implementations are working when it is time to use them.) .. _design.mps.config.opt: config#.opt Modules ------- _`.mod`: This section lists the functional modules in the MPS. _`.mod.lock`: Locks. See design.mps.lock_. _`.mod.prmc`: Mutator context. See design.mps.prmc_. _`.mod.prot`: Memory protection. See design.mps.prot_. _`.mod.sp`: Stack probe. See design.mps.sp_. _`.mod.ss`: Stack scanning. See design.mps.stack-scan_. _`.mod.th`: Thread manager. See design.mps.thread-manager_. _`.mod.vm`: Virtual mapping. See design.mps.vm_. .. _design.mps.lock: lock .. _design.mps.prot: prot .. _design.mps.prmc: prmc .. _design.mps.sp: sp .. _design.mps.stack-scan: stack-scan .. _design.mps.thread-manager: thread-manager .. _design.mps.vm: vm Limitations of generic implementations -------------------------------------- _`.lim`: This section summarizes the limitations of the generic implementations of the function modules. _`.lim.lock`: Requires a single-threaded mutator (see design.mps.lock.impl.an_). _`.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_). _`.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_). _`.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_). _`.lim.stack-scan`: Assumes that the stack grows downwards and that ``setjmp()`` reliably captures the registers (see design.mps.stack-scan.sol.stack.platform_). _`.lim.th`: Requires a single-threaded mutator (see design.mps.thread-manager.impl.an.single_). _`.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#.impl.an .. _design.mps.prmc.impl.an.fault: prmc#.impl.an.fault .. _design.mps.prmc.impl.an.suspend: prmc#.impl.an.suspend .. _design.mps.prot.impl.an.sync: prot#.impl.an.sync .. _design.mps.prot.impl.an.sync.issue: prot#.impl.an.sync.issue .. _design.mps.sp.issue.an: sp#.issue.an .. _design.mps.stack-scan.sol.stack.platform: stack-scan#.sol.stack.platform .. _design.mps.thread-manager.impl.an.single: thread-manager#.impl.an.single .. _design.mps.vm.impl.an.reserve: vm#.impl.an.reserve Document History ---------------- - 2014-11-02 GDR_ Initial draft based on design.mps.protan. .. _GDR: https://www.ravenbrook.com/consultants/gdr/ Copyright and License --------------------- Copyright © 2014–2020 `Ravenbrook Limited `_. 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.