.. index::
pair: general types; design
.. _design-type:
General MPS types
=================
.. mps:prefix:: design.mps.type
Introduction
------------
:mps:tag:`intro` See impl.h.mpmtypes.
Rationale
---------
Some types are declared to resolve a point of design, such as the best
type to use for array indexing.
Some types are declared so that the intention of code is clearer. For
example, :c:type:`Byte` is necessarily ``unsigned char``, but it's better to
say :c:type:`Byte` in your code if it's what you mean.
Concrete types
--------------
.. c:type:: unsigned AccessSet
:mps:tag:`access-set` An :c:type:`AccessSet` is a bitset of ``Access`` modes,
which are ``AccessREAD`` and ``AccessWRITE``. ``AccessSetEMPTY`` is
the empty :c:type:`AccessSet`.
.. c:type:: struct AddrStruct *Addr
:mps:tag:`addr` :c:type:`Addr` is the type used for "managed addresses", that is,
addresses of objects managed by the MPS.
:mps:tag:`addr.def` :c:type:`Addr` is defined as ``struct AddrStruct *``, but
:c:type:`AddrStruct` is never defined. This means that :c:type:`Addr` is always an
incomplete type, which prevents accidental dereferencing, arithmetic,
or assignment to other pointer types.
:mps:tag:`addr.use` :c:type:`Addr` should be used whenever the code needs to deal
with addresses. It should not be used for the addresses of memory
manager data structures themselves, so that the memory manager remains
amenable to working in a separate address space. Be careful not to
confuse :c:type:`Addr` with ``void *``.
:mps:tag:`addr.ops` Limited arithmetic is allowed on addresses using
:c:func:`AddrAdd()` and :c:func:`AddrOffset()` (impl.c.mpm). Addresses may also be
compared using the relational operators ``==``, ``!=``, ``<``, ``<=``,
``>``, and ``>=``.
:mps:tag:`addr.ops.mem` We need efficient operators similar to :c:func:`memset()`,
:c:func:`memcpy()`, and :c:func:`memcmp()` on :c:type:`Addr`; these are called :c:func:`AddrSet()`,
:c:func:`AddrCopy()`, and :c:func:`AddrComp()`. When :c:type:`Addr` is compatible with
``void *``, these are implemented through the functions
:c:func:`mps_lib_memset()`, :c:func:`mps_lib_memcpy()`, and :c:func:`mps_lib_memcmp()`
functions in the plinth (impl.h.mpm).
:mps:tag:`addr.conv.c` :c:type:`Addr` is converted to :c:type:`mps_addr_t` in the MPS C
Interface. :c:type:`mps_addr_t` is defined to be the same as ``void *``, so
using the MPS C Interface confines the memory manager to the same
address space as the client data.
:mps:tag:`addr.readonly` For read-only addresses, see :mps:ref:`.readonlyaddr`.
.. c:type:: Word Align
:mps:tag:`align` :c:type:`Align` is an unsigned integral type which is used to
represent the alignment of managed addresses. All alignments are
positive powers of two. :c:type:`Align` is large enough to hold the maximum
possible alignment.
:mps:tag:`align.use` :c:type:`Align` should be used whenever the code needs to
deal with the alignment of a managed address.
:mps:tag:`align.conv.c` :c:type:`Align` is converted to :c:type:`mps_align_t` in the MPS
C Interface.
.. c:type:: unsigned Attr
:mps:tag:`attr` Pool attributes. A bitset of pool class attributes, which
are:
=================== ===================================================
Attribute Description
=================== ===================================================
``AttrFMT`` Contains formatted objects.
Used to decide which pools to walk.
``AttrGC`` Is garbage collecting, that is, parts may be
reclaimed. Used to decide which segments are
condemned.
``AttrMOVINGGC`` Is moving, that is, objects may move in memory.
Used to update the set of zones that might have
moved and so implement location dependency.
=================== ===================================================
There is an attribute field in the pool class (:c:type:`PoolClassStruct`)
which declares the attributes of that class. See `design.mps.class-interface.field.attr`_.
.. _design.mps.class-interface.field.attr: class-interface
.. c:type:: int Bool
:mps:tag:`bool` The :c:type:`Bool` type is mostly defined so that the intention of
code is clearer. In C, Boolean expressions evaluate to ``int``, so
:c:type:`Bool` is in fact an alias for ``int``.
:mps:tag:`bool.value` :c:type:`Bool` has two values, :c:macro:`TRUE` and :c:macro:`FALSE`. These
are defined to be ``1`` and ``0`` respectively, for compatibility with
C Boolean expressions (so one may set a :c:type:`Bool` to the result of a C
Boolean expression).
:mps:tag:`bool.use` :c:type:`Bool` is a type which should be used when a Boolean
value is intended, for example, as the result of a function. Using a
Boolean type in C is a tricky thing. Non-zero values are "true" (when
used as control conditions) but are not all equal to :c:macro:`TRUE`. Use
with care.
:mps:tag:`bool.check` :c:func:`BoolCheck()` simply checks whether the argument is
:c:macro:`TRUE` (``1``) or :c:macro:`FALSE` (``0``).
:mps:tag:`bool.check.inline` The inline macro version of ``BoolCheck`` casts
the ``int`` to ``unsigned`` and checks that it is ``<= 1``. This is
safe, well-defined, uses the argument exactly once, and generates
reasonable code.
:mps:tag:`bool.check.inline.smaller` In fact we can expect that the "inline"
version of :c:func:`BoolCheck()` to be smaller than the equivalent function
call. On IA-32 for example, a function call will be 3 instructions
(total 9 bytes), the inline code for :c:func:`BoolCheck()` will be 1
instruction (total 3 bytes) (both sequences not including the test
which is the same length in either case).
:mps:tag:`bool.check.inline.why` As well as being smaller (see
:mps:ref:`.bool.check.inline.smaller`) it is faster. On 1998-11-16 drj
compared ``w3i3mv\hi\amcss.exe`` running with and without the macro
for ``BoolCheck`` on the PC Aaron. "With" ran in 97.7% of the time
(averaged over 3 runs).
:mps:tag:`bool.bitfield` When a Boolean needs to be stored in a bitfield,
the type of the bitfield must be ``unsigned:1``, not ``Bool:1``.
(That's because the two values of the type ``Bool:1`` are ``0`` and
``-1``, which means that assigning :c:macro:`TRUE` would require a sign
conversion.) To make it clear why this is done, ``misc.h`` provides
the :c:macro:`BOOLFIELD` macro.
:mps:tag:`bool.bitfield.assign` To avoid warnings about loss of data from
GCC with the ``-Wconversion`` option, ``misc.h`` provides the
:c:macro:`BOOLOF` macro for coercing a value to an unsigned single-bit field.
:mps:tag:`bool.bitfield.check` A Boolean bitfield cannot have an incorrect
value, and if you call :c:func:`BoolCheck()` on such a bitfield then GCC 4.2
issues the warning "comparison is always true due to limited range of
data type". When avoiding such a warning, reference this tag.
.. c:type:: unsigned BufferMode
:mps:tag:`buffermode` :c:type:`BufferMode` is a bitset of buffer attributes. See
design.mps.buffer_. It is a sum of the following:
.. _design.mps.buffer: buffer
======================== ==============================================
Mode Description
======================== ==============================================
``BufferModeATTACHED`` Buffer is attached to a region of memory.
``BufferModeFLIPPED`` Buffer has been flipped.
``BufferModeLOGGED`` Buffer emits the events ``BufferReserve`` and
``BufferCommit``.
``BufferModeTRANSITION`` Buffer is in the process of being detached.
======================== ==============================================
.. c:type:: unsigned char Byte
:mps:tag:`byte` :c:type:`Byte` is an unsigned integral type corresponding to the
unit in which most sizes are measured, and also the units of
``sizeof``.
:mps:tag:`byte.use` :c:type:`Byte` should be used in preference to ``char`` or
``unsigned char`` wherever it is necessary to deal with bytes
directly.
:mps:tag:`byte.source` :c:type:`Byte` is a just pedagogic version of ``unsigned
char``, since ``char`` is the unit of ``sizeof``.
.. c:type:: Word Clock
:mps:tag:`clock` :c:type:`Clock` is an unsigned integral type representing clock
time since some epoch.
:mps:tag:`clock.use` A :c:type:`Clock` value is returned by the plinth function
``mps_clock``. It is used to make collection scheduling decisions and
to calibrate the time stamps on events in the telemetry stream.
:mps:tag:`clock.units` The plinth function ``mps_clocks_per_sec`` defines
the units of a :c:type:`Clock` value.
:mps:tag:`clock.conv.c` :c:type:`Clock` is converted to :c:type:`mps_clock_t` in the MPS
C Interface.
.. c:type:: unsigned Compare
:mps:tag:`compare` :c:type:`Compare` is the type of tri-state comparison
values.
================== ====================================================
Value Description
================== ====================================================
``CompareLESS`` A value compares less than another value.
``CompareEQUAL`` Two values compare the same.
``CompareGREATER`` A value compares greater than another value.
================== ====================================================
.. c:type:: Word Count
:mps:tag:`count` :c:type:`Count` is an unsigned integral type which is large
enough to hold the size of any collection of objects in the MPS.
:mps:tag:`count.use` :c:type:`Count` should be used for a number of objects
(control or managed) where the maximum number of objects cannot be
statically determined. If the maximum number can be statically
determined then the smallest unsigned integer with a large enough
range may be used instead (although :c:type:`Count` may be preferable for
clarity).
:mps:tag:`count.use.other` :c:type:`Count` may also be used to count things that
aren't represented by objects (for example, levels), but only where it
can be determined that the maximum count is less than the number of
objects.
.. c:type:: Size Epoch
:mps:tag:`epoch` An :c:type:`Epoch` is a count of the number of flips that have
occurred, in which objects may have moved. It is used in the
implementation of location dependencies.
:c:type:`Epoch` is converted to :c:type:`mps_word_t` in the MPS C Interface, as a
field of :c:type:`mps_ld_s`.
.. c:type:: unsigned FindDelete
:mps:tag:`finddelete` :c:type:`FindDelete` represents an instruction to one of the
*find* methods of a :c:type:`Land` as to what it should do if it finds a
suitable block. See design.mps.land_. It takes one of the following
values:
.. _design.mps.land: land
==================== ==================================================
Value Description
==================== ==================================================
``FindDeleteNONE`` Don't delete after finding.
``FindDeleteLOW`` Delete from low end of block.
``FindDeleteHIGH`` Delete from high end of block.
``FindDeleteENTIRE`` Delete entire block.
==================== ==================================================
.. c:type:: unsigned FrameState
:mps:tag:`framestate` :c:type:`FrameState` represents the current state in a
buffer frame's lifecycle. See design.mps.alloc-frame_. It takes one of
the following values:
.. _design.mps.alloc-frame: alloc-frame
========================== ============================================
State Description
========================== ============================================
``BufferFrameVALID`` Indicates that :c:func:`PushFrame()` can be a
lightweight operation and need not be
synchronized.
``BufferFramePOP_PENDING`` Indicates that there has been a
:c:func:`PopFrame()` operation that the pool
must respond to.
``BufferFrameDISABLED`` Indicates that the pool has disabled
support for lightweight operations for
this buffer.
========================== ============================================
.. c:type:: void (*Fun)(void)
:mps:tag:`fun` :c:type:`Fun` is the type of a pointer to a function about which
nothing more is known.
:mps:tag:`fun.use` :c:type:`Fun` should be used where it's necessary to handle a
function in a polymorphic way without calling it. For example, if you
need to write a function ``g`` which passes another function ``f``
through to a third function ``h``, where ``h`` knows the real type of
``f`` but ``g`` doesn't.
.. c:type:: Word Index
:mps:tag:`index` :c:type:`Index` is an unsigned integral type which is large
enough to hold any array index.
:mps:tag:`index.use` :c:type:`Index` should be used where the maximum size of the
array cannot be statically determined. If the maximum size can be
determined then the smallest unsigned integer with a large enough
range may be used instead.
.. c:type:: unsigned MessageType
:mps:tag:`messagetype` :c:type:`MessageType` is the type of a message. See
design.mps.message_. It takes one of the following values:
.. _design.mps.message: message
=========================== ===========================================
Message type Description
=========================== ===========================================
``MessageTypeFINALIZATION`` A block is finalizable.
``MessageTypeGC`` A garbage collection finished.
``MessageTypeGCSTART`` A garbage collection started.
=========================== ===========================================
.. c:type:: unsigned Rank
:mps:tag:`rank` :c:type:`Rank` is an enumeration which represents the rank of a
reference. The ranks are:
============= ===== ==================================================
Rank Index Description
============= ===== ==================================================
``RankAMBIG`` 0 The reference is ambiguous. That is, it must be
assumed to be a reference, but not updated in
case it isn't.
``RankEXACT`` 1 The reference is exact, and refers to an object.
``RankFINAL`` 2 The reference is exact and final, so special
action is required if only final or weak
references remain to the object.
``RankWEAK`` 3 The reference is exact and weak, so should
be deleted if only weak references remain to the
object.
============= ===== ==================================================
:c:type:`Rank` is stored with segments and roots, and passed around.
:c:type:`Rank` is converted to :c:type:`mps_rank_t` in the MPS C Interface.
The ordering of the ranks is important. It is the order in which the
references must be scanned in order to respect the properties of
references of the ranks. Therefore they are declared explicitly with
their integer values.
.. note:: Could :c:type:`Rank` be an ``unsigned short`` or ``unsigned char``?
.. note::
This documentation should be expanded and moved to its own
document, then referenced from the implementation more thoroughly.
.. c:type:: unsigned RankSet
:mps:tag:`rankset` :c:type:`RankSet` is a set of ranks, represented as a bitset.
.. c:type:: const struct AddrStruct *ReadonlyAddr
:mps:tag:`readonlyaddr` :c:type:`ReadonlyAddr` is the type used for managed
addresses that an interface promises it will only read through, never
write. Otherwise it is identical to :c:type:`Addr`.
.. c:type:: Addr Ref
:mps:tag:`ref` :c:type:`Ref` is a reference to a managed object (as opposed to any
old managed address). :c:type:`Ref` should be used where a reference is
intended.
.. note:: This isn't too clear -- richard
.. c:type:: Word RefSet
:mps:tag:`refset` :c:type:`RefSet` is a conservative approximation to a set of
references. See design.mps.refset_.
.. _design.mps.refset: refset
.. c:type:: int Res
:mps:tag:`res` :c:type:`Res` is the type of result codes. A result code indicates
the success or failure of an operation, along with the reason for
failure. Like Unix error codes, the meaning of the code depends on the
call that returned it. These codes are just broad categories with
mnemonic names for various sorts of problems.
=================== ===================================================
Result code Description
=================== ===================================================
``ResOK`` The operation succeeded. Return parameters may only
be updated if OK is returned, otherwise they must
be left untouched.
``ResCOMMIT_LIMIT`` The arena's commit limit would have been exceeded
as a result of allocation.
``ResFAIL`` Something went wrong which doesn't fall into any of
the other categories. The exact meaning depends
on the call. See documentation.
``ResIO`` An I/O error occurred. Exactly what depends on the
function.
``ResLIMIT`` An internal limitation was reached. For example,
the maximum number of somethings was reached. We
should avoid returning this by not including
static limitations in our code, as far as
possible. (See rule.impl.constrain and
rule.impl.limits.)
``ResMEMORY`` Needed memory (committed memory, not address space)
could not be obtained.
``ResPARAM`` An invalid parameter was passed. Normally reserved
for parameters passed from the client.
``ResRESOURCE`` A needed resource could not be obtained. Which
resource depends on the call. See also
``ResMEMORY``, which is a special case of this.
``ResUNIMPL`` The operation, or some vital part of it, is
unimplemented. This might be returned by
functions which are no longer supported, or by
operations which are included for future
expansion, but not yet supported.
=================== ===================================================
:mps:tag:`res.use` :c:type:`Res` should be returned from any function which might
fail. Any other results of the function should be passed back in
"return" parameters (pointers to locations to fill in with the
results).
.. note:: This is documented elsewhere, I think -- richard
:mps:tag:`res.use.spec` The most specific code should be returned.
.. c:type:: unsigned RootMode
:mps:tag:`rootmode` :c:type:`RootMode` is an unsigned integral type which is used
to represent an attribute of a root:
============================= =========================================
Root mode Description
============================= =========================================
``RootModeCONSTANT`` Client program will not change the root
after it is registered.
``RootModePROTECTABLE`` Root is protectable: the MPS may place
a barrier on any page containing any
part of the root.
``RootModePROTECTABLE_INNER`` Root is protectable: the MPS may place
a barrier on any page completely covered
by part of the root.
============================= =========================================
:mps:tag:`rootmode.const.unused` ``RootModeCONSTANT`` has no effect. This
mode was introduced in the hope of being able to maintain a
:term:`remembered set` for the root without needing a :term:`write
barrier`, but it can't work as described, since you can't reliably
create a valid registered constant root that contains any references.
(If you add the references before registering the root, they may have
become invalid; but you can't add them afterwards because the root is
supposed to be constant.)
:mps:tag:`rootmode.conv.c` :c:type:`RootMode` is converted to :c:type:`mps_rm_t` in the
MPS C Interface.
.. c:type:: int RootVar
:mps:tag:`rootvar` The type :c:type:`RootVar` is the type of the discriminator for
the union within :c:type:`RootStruct`.
.. c:type:: int SegPrefKind
:mps:tag:`segprefkind` The type :c:type:`SegPrefKind` expresses a preference for
addresses within an address space. It takes one of the following
values:
================== ====================================================
Kind Description
================== ====================================================
``SegPrefHigh`` Prefer high addresses.
``SegPrefLow`` Prefer low addresses.
``SegPrefZoneSet`` Prefer addresses in specified zones.
================== ====================================================
.. note::
The name is misleading as this is used to refer to address
preferences in general, not just addresses of segments.
.. c:type:: unsigned Serial
:mps:tag:`serial` A :c:type:`Serial` is a number which is assigned to a structure
when it is initialized. The serial number is taken from a field in the
parent structure, which is incremented. Thus, every instance of a
structure has a unique "name" which is a path of structures from the
global root. For example, "the third arena's fifth pool's second
buffer".
Why? Consistency checking, debugging, and logging. Not well thought
out.
.. c:type:: unsigned Shift
:mps:tag:`shift` :c:type:`Shift` is an unsigned integral type which can hold the
amount by which a :c:type:`Word` can be shifted. It is therefore large
enough to hold the word width (in bits).
:mps:tag:`shift.use` :c:type:`Shift` should be used whenever a shift value (the
right-hand operand of the ``<<`` or ``>>`` operators) is intended, to
make the code clear. It should also be used for structure fields which
have this use.
.. note:: Could :c:type:`Shift` be an ``unsigned short`` or ``unsigned char``?
.. c:type:: unsigned long Sig
:mps:tag:`sig` :c:type:`Sig` is the type of signatures, which are written into
structures when they are created, and invalidated when they are
destroyed. They provide a limited form of run-time type checking and
dynamic scope checking. See design.mps.sig_.
.. _design.mps.sig: sig
.. c:type:: Word Size
:mps:tag:`size` :c:type:`Size` is an unsigned integral type large enough to
hold the size of any object which the MPS might manage.
:mps:tag:`size.byte` :c:type:`Size` should hold a size calculated in bytes.
.. warning::
This is violated by ``GenParams.capacity`` (which is measured in
kilobytes).
:mps:tag:`size.use` :c:type:`Size` should be used whenever the code needs to deal
with the size of managed memory or client objects. It should not be
used for the sizes of the memory manager's own data structures, so
that the memory manager is amenable to working in a separate address
space. Be careful not to confuse it with ``size_t``.
:mps:tag:`size.ops` :c:func:`SizeIsAligned()`, :c:func:`SizeAlignUp()`,
:c:func:`SizeAlignDown()` and :c:func:`SizeRoundUp()`.
:mps:tag:`size.conv.c` :c:type:`Size` is converted to ``size_t`` in the MPS C
Interface. This constrains the memory manager to the same address
space as the client data.
.. c:type:: unsigned TraceId
:mps:tag:`traceid` A :c:type:`TraceId` is an unsigned integer which is less than
``TraceLIMIT``. Each running trace has a different :c:type:`TraceId` which
is used to index into the tables and bitfields that record the state
of that trace. See `design.mps.trace.instance.limit`_.
.. _design.mps.trace.instance.limit: trace#instance.limit
.. c:type:: unsigned TraceSet
:mps:tag:`traceset` A :c:type:`TraceSet` is a bitset of :c:type:`TraceId`,
represented in the obvious way::
member(ti, ts) ⇔ ((1<<ti) & ts) != 0
:c:type:`TraceSet` is used to represent colour in the Tracer. See
design.mps.trace_.
.. _design.mps.trace: trace
.. c:type:: unsigned TraceStartWhy
:mps:tag:`tracestartwhy` :c:type:`TraceStartWhy` represents the reason that a
trace was started. It takes one of the following values:
======================================= ===============================
Reason Description
======================================= ===============================
``TraceStartWhyCHAIN_GEN0CAP`` Generation zero of a chain
reached capacity.
``TraceStartWhyDYNAMICCRITERION`` Need to start full collection
now, or there won't be enough
memory to complete it.
``TraceStartWhyOPPORTUNISM`` Client had idle time available.
``TraceStartWhyCLIENTFULL_INCREMENTAL`` Client requested incremental
collection.
``TraceStartWhyCLIENTFULL_BLOCK`` Client requested full
collection.
``TraceStartWhyWALK`` Walking references.
``TraceStartWhyEXTENSION`` Request by MPS extension.
======================================= ===============================
.. c:type:: unsigned TraceState
:mps:tag:`tracestate` :c:type:`TraceState` represents the current state in a
trace's lifecycle. See design.mps.trace_. It takes one of the
following values:
================== ====================================================
State Description
================== ====================================================
``TraceINIT`` Nothing happened yet.
``TraceUNFLIPPED`` Segments condemned (made white); initial grey set
created; scanning rate calculated.
``TraceFLIPPED`` Buffers flipped; roots scanned; location
dependencies made stale; grey segments protected.
``TraceRECLAIM`` There are no outstanding grey segments.
``TraceFINISHED`` All segments reclaimed.
================== ====================================================
.. c:type:: MPS_T_ULONGEST ULongest
:mps:tag:`ulongest` :c:type:`ULongest` is the longest unsigned integer on the
platform. (We used to use ``unsigned long`` but this assumption is
violated by 64-bit Windows.) This type should be used for calculations
where any integer might be passed. Notably, it is used in :c:func:`WriteF()`
to print any integer.
.. c:type:: MPS_T_WORD Word
:mps:tag:`word` :c:type:`Word` is an unsigned integral type which matches the size
of the machine word, that is, the natural size of the machine
registers and addresses.
:mps:tag:`word.use` :c:type:`Word` should be used where an unsigned integer is
required that might range as large as the machine word.
:mps:tag:`word.source` :c:type:`Word` is derived from the macro :c:macro:`MPS_T_WORD`
which is declared in impl.h.mpstd according to the target platform
(design.mps.config.pf.word).
:mps:tag:`word.conv.c` :c:type:`Word` is converted to :c:type:`mps_word_t` in the MPS C
Interface.
:mps:tag:`word.ops` :c:func:`WordIsAligned()`, :c:func:`WordAlignUp()`,
:c:func:`WordAlignDown()` and :c:func:`WordRoundUp()`.
.. c:type:: Word ZoneSet
:mps:tag:`zoneset` :c:type:`ZoneSet` is a conservative approximation to a set of
zones. See design.mps.refset_.
Abstract types
--------------
:mps:tag:`adts` The following types are abstract data types, implemented as
pointers to structures. For example, :c:type:`Ring` is a pointer to a
:c:type:`RingStruct`. They are described elsewhere.
:c:type:`AllocFrame`, :c:type:`AllocPattern`, :c:type:`AP`, :c:type:`Arena`, :c:type:`BootBlock`,
:c:type:`Buffer`, :c:type:`Chain`, :c:type:`Chunk`, :c:type:`Format`, :c:type:`Globals`, :c:type:`Land`,
:c:type:`LD`, :c:type:`Lock`, :c:type:`MutatorFaultContext`, :c:type:`PoolClass`, :c:type:`Page`,
:c:type:`Pool`, ``PoolDebugMixin``, :c:type:`Range`, :c:type:`Reservoir`, :c:type:`Ring`,
:c:type:`Root`, :c:type:`ScanState`, :c:type:`Seg`, :c:type:`SegBuf`, :c:type:`SegPref`,
:c:type:`StackContext`, :c:type:`Thread`, :c:type:`Trace`, :c:type:`VM`.
.. c:type:: void *Pointer
:mps:tag:`pointer` The type :c:type:`Pointer` is the same as ``void *``, and
exists to sanctify functions such as :c:func:`PointerAdd()`.