.. index::
pair: messages; design
single: client message protocol
.. _design-message:
Client message protocol
=======================
.. mps:prefix:: design.mps.message
pair: messages; design
single: client message protocol
Introduction
------------
:mps:tag:`intro` The client message protocol provides a means by which
clients can receive messages from the MPS asynchronously. Typical
messages may be low memory notification (or in general low utility),
finalization notification, soft-failure notification. There is a
general assumption that it should not be disastrous for the MPS client
to ignore messages, but that it is probably in the clients best
interest to not ignore messages. The justification for this is that
the MPS cannot force the MPS client to read and act on messages, so no
message should be critical.
.. note::
Bogus, since we cannot force clients to check error codes either.
Pekka P. Pirinen, 1997-09-17.
:mps:tag:`contents` This document describes the design of the external and
internal interfaces and concludes with a sketch of an example design
of an internal client. The example is that of implementing
finalization using PoolMRG.
:mps:tag:`readership` Any MPS developer.
Requirements
------------
:mps:tag:`req` The client message protocol will be used for implementing
finalization (see design.mps.finalize and req.dylan.fun.final). It
will also be used for implementing the notification of various
conditions (possibly req.dylan.prot.consult is relevant here).
External interface
------------------
:mps:tag:`if.queue` Messages are presented as a single queue per arena.
Various functions are provided to inspect the queue and inspect
messages in it (see below).
Functions
.........
:mps:tag:`if.fun` The following functions are provided:
:mps:tag:`if.fun.poll` :c:func:`mps_message_poll()` sees whether there are any
messages pending. Returns 1 only if there is a message on the queue of
arena. Returns 0 otherwise.
:mps:tag:`if.fun.enable` :c:func:`mps_message_type_enable()` enables the flow of
messages of a certain type. The queue of messages of a arena will
contain only messages whose types have been enabled. Initially all
message types are disabled. Effectively this function allows the
client to declare to the MPS what message types the client
understands. The MPS does not generate any messages of a type that
hasn't been enabled. This allows the MPS to add new message types (in
subsequent releases of a memory manager) without confusing the client.
The client will only be receiving the messages if they have explicitly
enabled them (and the client presumably only enables message types
when they have written the code to handle them).
:mps:tag:`if.fun.disable` :c:func:`mps_message_type_disable()` disables the flow
of messages of a certain type. The antidote to
:c:func:`mps_message_type_enable()`. Disables the specified message type.
Flushes any existing messages of that type on the queue, and stops any
further generation of messages of that type. This permits clients to
dynamically decline interest in a message type, which may help to
avoid a memory leak or bloated queue when the messages are only
required temporarily.
:mps:tag:`if.fun.get` :c:func:`mps_message_get()` begins a message "transaction".
If there is a message of the specified type on the queue then the
first such message will be removed from the queue and a handle to it
will be returned to the client via the ``messageReturn`` argument; in
this case the function will return :c:macro:`TRUE`. Otherwise it will return
:c:macro:`FALSE`. Having obtained a handle on a message in this way, the
client can use the type-specific accessors to find out about the
message. When the client is done with the message the client should
call :c:func:`mps_message_discard()`; failure to do so will result in a
resource leak.
:mps:tag:`if.fun.discard` :c:func:`mps_message_discard()` ends a message
"transaction". It indicates to the MPS that the client is done with
this message and its resources may be reclaimed.
:mps:tag:`if.fun.type.any` :c:func:`mps_message_queue_type()` determines the type
of a message in the queue. Returns :c:macro:`TRUE` only if there is a message
on the queue of arena, and in this case updates the ``typeReturn``
argument to be the type of a message in the queue. Otherwise returns
:c:macro:`FALSE`.
:mps:tag:`if.fun.type` :c:func:`mps_message_type()` determines the type of a
message (that has already been got). Only legal when inside a message
transaction (that is, after :c:func:`mps_message_get()` and before
:c:func:`mps_message_discard()`). Note that the type will be the same as the
type that the client passed in the call to :c:func:`mps_message_get()`.
Types of messages
.................
:mps:tag:`type` The type governs the "shape" and meaning of the message.
:mps:tag:`type.int` Types themselves will just be a scalar quantity, an
integer.
:mps:tag:`type.semantics` A type indicates the semantics of the message.
:mps:tag:`type.semantics.interpret` The semantics of a message are
interpreted by the client by calling various accessor methods on the
message.
:mps:tag:`type.accessor` The type of a message governs which accessor
methods are legal to apply to the message.
:mps:tag:`type.example` Some example types:
:mps:tag:`type.finalization` There will be a finalization type. The type is
abstractly: ``FinalizationMessage(Ref)``.
:mps:tag:`type.finalization.semantics` A finalization message indicates that
an object has been discovered to be finalizable (see
design.mps.poolmrg.def.final.object for a definition of finalizable).
:mps:tag:`type.finalization.ref` There is an accessor to get the reference
of the finalization message (i.e. a reference to the object which is
finalizable) called :c:func:`mps_message_finalization_ref()`.
:mps:tag:`type.finalization.ref.scan` Note that the reference returned
should be stored in scanned memory.
Compatibility issues
....................
:mps:tag:`compatibility` The following issues affect future compatibility of
the interface:
:mps:tag:`compatibility.future.type-new` Notice that message of a type that
the client doesn't understand are not placed on the queue, therefore
the MPS can introduce new types of message and existing client will
still function and will not leak resources. This has been achieved by
getting the client to declare the types that the client understands
(with :c:func:`mps_message_type_enable()`, :mps:ref:`.if.fun.enable`).
:mps:tag:`compatibility.future.type-extend` The information available in a
message of a given type can be extended by providing more accessor
methods. Old clients won't get any of this information but that's
okay.
Internal interface
------------------
Types
.....
.. c:type:: struct MessageStruct *Message
:mps:tag:`message.type` :c:type:`Message` is the type of messages.
:mps:tag:`message.instance` Messages are instances of Message Classes.
.. c:type:: struct MessageStruct *MessageStruct
:mps:tag:`message.concrete` Concretely a message is represented by a
:c:type:`MessageStruct`. A :c:type:`MessageStruct` has the usual signature field
(see design.mps.sig). A :c:type:`MessageStruct` has a type field which
defines its type, a ring node, which is used to attach the message to
the queue of pending messages, a class field, which identifies a
:c:type:`MessageClass` object.
:mps:tag:`message.intent` The intention is that a :c:type:`MessageStruct` will be
embedded in some richer object which contains information relevant to
that specific type of message.
:mps:tag:`message.struct` The structure is declared as follows::
struct MessageStruct {
Sig sig;
MessageType type;
MessageClass class;
RingStruct node;
} MessageStruct;
.. c:type:: struct MessageClassStruct *MessageClass
:mps:tag:`class` A message class is an encapsulation of methods. It
encapsulates methods that are applicable to all types of messages
(generic) and methods that are applicable to messages only of a
certain type (type-specific).
:mps:tag:`class.concrete` Concretely a message class is represented by a
:c:type:`MessageClassStruct` (a struct). Clients of the Message module are
expected to allocate storage for and initialise the
:c:type:`MessageClassStruct`. It is expected that such storage will be
allocated and initialised statically.
:mps:tag:`class.one-type` A message class implements exactly one message
type. The identifier for this type is stored in the ``type`` field of
the :c:type:`MessageClassStruct`. Note that the converse is not true: a
single message type may be implemented by two (or more) different
message classes (for example: for two pool classes that require
different implementations for that message type).
:mps:tag:`class.methods.generic` The generic methods are as follows:
* ``delete`` -- used when the message is destroyed (by the client
calling :c:func:`mps_message_discard()`). The class implementation should
finish the message (by calling :c:func:`MessageFinish()`) and storage for
the message should be reclaimed (if applicable).
:mps:tag:`class.methods.specific` The type specific methods are:
:mps:tag:`class.methods.specific.finalization` Specific to
``MessageTypeFinalization``:
* ``finalizationRef`` -- returns a reference to the finalizable object
represented by this message.
:mps:tag:`class.methods.specific.collectionstats` Specific to ``MessageTypeCollectionStats``:
* ``collectionStatsLiveSize`` -- returns the number of bytes (of
objects) that were condemned but survived.
* ``collectionStatsCondemnedSize`` -- returns the number of bytes
condemned in the collection.
* ``collectionStatsNotCondemnedSize`` -- returns the the number of
bytes (of objects) that are subject to a GC policy (that is,
collectable) but were not condemned in the collection.
:mps:tag:`class.sig.double` The :c:type:`MessageClassStruct` has a signature field
at both ends. This is so that if the :c:type:`MessageClassStruct` changes
size (by adding extra methods for example) then any static
initializers will generate errors from the compiler (there will be a
type error causes by initialising a non-signature type field with a
signature) unless the static initializers are changed as well.
:mps:tag:`class.struct` The structure is declared as follows::
typedef struct MessageClassStruct {
Sig sig; /* design.mps.sig */
const char *name; /* Human readable Class name */
/* generic methods */
MessageDeleteMethod delete; /* terminates a message */
/* methods specific to MessageTypeFinalization */
MessageFinalizationRefMethod finalizationRef;
/* methods specific to MessageTypeCollectionStats */
MessageCollectionStatsLiveSizeMethod collectionStatsLiveSize;
MessageCollectionStatsCondemnedSizeMethod collectionStatsCondemnedSize;
MessageCollectionStatsNotCondemnedSizeMethod collectionStatsNotCondemnedSize;
Sig endSig; /* design.mps.message.class.sig.double */
} MessageClassStruct;
:mps:tag:`space.queue` The arena structure is augmented with a structure for
managing for queue of pending messages. This is a ring in the
:c:type:`ArenaStruct`::
struct ArenaStruct
{
...
RingStruct messageRing;
...
}
Functions
.........
.. c:function:: void MessageInit(Arena arena, Message message, MessageClass class)
:mps:tag:`fun.init` Initializes the :c:type:`MessageStruct` pointed to by
``message``. The caller of this function is expected to manage the
store for the :c:type:`MessageStruct`.
.. c:function:: void MessageFinish(Message message)
:mps:tag:`fun.finish` Finishes the :c:type:`MessageStruct` pointed to by
``message``. The caller of this function is expected to manage the
store for the :c:type:`MessageStruct`.
.. c:function:: void MessagePost(Arena arena, Message message)
:mps:tag:`fun.post` Places a message on the queue of an arena.
:mps:tag:`fun.post.precondition` Prior to calling the function, the node
field of the message must be a singleton. After the call to the
function the message will be available for MPS client to access. After
the call to the function the message fields must not be manipulated
except from the message's class's method functions (that is, you
mustn't poke about with the node field in particular).
.. c:function:: void MessageEmpty(Arena arena)
:mps:tag:`fun.empty` Empties the message queue. This function has the same
effect as discarding all the messages on the queue. After calling this
function there will be no messages on the queue.
:mps:tag:`fun.empty.internal-only` This functionality is not exposed to
clients. We might want to expose this functionality to our clients in
the future.
Message life cycle
------------------
:mps:tag:`life` A message will be allocated by a client of the message
module, it will be initialised by calling :c:func:`MessageInit()`. The
client will eventually post the message on the external queue (in fact
most clients will create a message and then immediately post it). The
message module may then apply any of the methods to the message. The
message module will eventually destroy the message by applying the
``delete`` method to it.
Examples
--------
Finalization
............
.. note::
Possibly out of date, see design.mps.finalize and
design.mps.poolmrg instead. David Jones, 1997-08-28.
This subsection is a sketch of how PoolMRG will use Messages for
finalization (see design.mps.poolmrg).
PoolMRG has guardians (see design.mps.poolmrg.guardian). Guardians are
used to manage final references and detect when an object is
finalizable.
The link part of a guardian will include a :c:type:`MessageStruct`.
The :c:type:`MessageStruct` is allocated when the final reference is created
(which is when the referred to object is registered for finalization).
This avoids allocating at the time when the message gets posted (which
might be a tricky, undesirable, or impossible, time to allocate).
PoolMRG has two queues: the entry queue, and the exit queue. The entry
queue will use a ring; the exit queue of MRG will simply be the
external message queue.
The ``delete`` method frees both the link part and the reference part
of the guardian.