emacs/mps/manual/source/topic/message.rst

.. Sources:

    `<https://info.ravenbrook.com/project/mps/master/design/message/>`_
    `<https://info.ravenbrook.com/mail/2005/04/05/13-33-11/0.txt>`_

.. index::
   single: message; introduction

.. _topic-message:

Messages
========

The MPS sometimes needs to communicate with the :term:`client program`
about events which occur :term:`asynchronously <asynchronous garbage
collector>`, and so information cannot be returned as function call
results.

*Messages* are the mechanism for this asynchronous communication,
implemented in the form of a :term:`message queue` attached to each
:term:`arena`.

The client program must enable each message type that it is prepared
to handle, by calling :c:func:`mps_message_type_enable`. Then it must
poll the message queue at regular intervals when it is convenient to
do so, calling :c:func:`mps_message_get` to retrieve each message from
the queue, and finally calling :c:func:`mps_message_discard` when done
with the message.

Messages are thus :term:`manually managed <manual memory management>`:
if the client program enables one or more message types, and then
neglects to poll the message queue or neglects to discard the messages
it retrieved, then messages will :term:`leak <memory leak>`.

There is no requirement on the client program to retrieve and discard
messages promptly. However, a client program that allows the number of
garbage collection (or garbage collection start) messages on the
message queue to grow without limit will eventually find that new
garbage collections no longer start until some of these messages are
retrieved and discarded.


.. index::
   pair: message; finalization

Finalization messages
---------------------

:term:`Finalization` is implemented by posting a finalization message
(of type :c:func:`mps_message_type_finalization`) to the arena's
message queue. This allows the :term:`client program` to perform the
finalization at a convenient time and so avoid synchronization
difficulties.

The block is not actually reclaimed until the finalization message is
removed from the message queue and discarded, by calling
:c:func:`mps_message_get` followed by :c:func:`mps_message_discard`.

See :ref:`topic-finalization`.


.. index::
   single: message; example
   single: Scheme; interactive chatter

Example: interactive chatter
----------------------------

The toy Scheme interpreter enables garbage collection messages when
started in interactive mode::

    mps_message_type_enable(arena, mps_message_type_gc());
    mps_message_type_enable(arena, mps_message_type_gc_start());

Then, after every interactive command finishes, it reads these
messages from the message queue and prints a description of the
contents of each one::

    static void mps_chat(void)
    {
        mps_message_type_t type;

        while (mps_message_queue_type(&type, arena)) {
            mps_message_t message;
            mps_bool_t b;
            b = mps_message_get(&message, arena, type);
            assert(b); /* we just checked there was one */

            if (type == mps_message_type_gc_start()) {
                printf("Collection started.\n");
                printf("  Why: %s\n", mps_message_gc_start_why(arena, message));
                printf("  Clock: %lu\n", (unsigned long)mps_message_clock(arena, message));
            if (type == mps_message_type_gc()) {
                /* ... and so on for other message types ... */
            } else {
                printf("Unknown message from MPS!\n");
            }

            mps_message_discard(arena, message);
        }
    }

Here's how this looks in operation:

.. code-block:: none

    MPS Toy Scheme Example
    9960, 0> (define (make-list n e) (if (eqv? n 0) '() (cons e (make-list (- n 1) e))))
    make-list
    10824, 0> (length (make-list 1000 #t))
    1000
    Collection started.
      Why: Generation 0 of a chain has reached capacity: start a minor collection.
      Clock: 6649
    507408, 1> (length (make-list 200 #f))
    200
    Collection finished.
        live 112360
        condemned 196600
        not_condemned 0
        clock: 18431
    607192, 1> Bye.

.. note::

    This kind of interactive "chatter" may be useful when testing and
    debugging memory management, but should not be used otherwise. The
    scheduling of garbage collections is not normally of interest even
    to programmers, and chatter of this sort may give the illusion
    that a program is spending much more time garbage collecting than
    is actually the case.

    Versions of GNU Emacs prior to 19.31 (May 1996) used to display
    the message "Garbage collecting..." during a collection. Erik
    Naggum commented on this feature:

        I have run some tests at the U of Oslo with about 100
        users who generally agreed that Emacs had become faster in
        the latest Emacs pretest. All I had done was to remove the
        "Garbage collecting" message which people perceive as
        slowing Emacs down and tell them that it had been sped up.


.. index::
   single: message; types

Message types
-------------

.. c:type:: mps_message_type_t

    The type of :term:`message types`.

    There are three message types:

    1. :c:func:`mps_message_type_finalization`
    2. :c:func:`mps_message_type_gc`
    3. :c:func:`mps_message_type_gc_start`


.. c:function:: void mps_message_type_disable(mps_arena_t arena, mps_message_type_t message_type)

    Restore an :term:`arena` to the default state whereby
    :term:`messages` of the specified :term:`message type`
    are not posted, reversing the effect of an earlier call to
    :c:func:`mps_message_type_enable`.

    ``arena`` is an arena.

    ``message_type`` is the message type to be disabled.

    Any existing messages of the specified type are flushed from the
    :term:`message queue` of ``arena``.

    .. note::

        It is permitted to call this function when ``message_type`` is
        already disabled, in which case it has no effect.


.. c:function:: void mps_message_type_enable(mps_arena_t arena, mps_message_type_t message_type)

    Enable an :term:`arena` to post :term:`messages` of a
    specified :term:`message type`.

    ``arena`` is an arena.

    ``message_type`` is the message type to be enabled.

    This function tells the MPS that ``arena`` may post messages of
    ``message_type`` to its :term:`message queue`. By default, the MPS
    does not generate any messages of any type.

    A :term:`client program` that enables messages for a message type
    must access messages by calling :c:func:`mps_message_get` and
    discard them by calling :c:func:`mps_message_discard`, or the
    message queue may consume unbounded resources.

    The client program may disable the posting of messages by calling
    :c:func:`mps_message_type_disable`.

    .. note::

        It is permitted to call this function when ``message_type`` is
        already enabled, in which case it has no effect.


.. index::
   single: message; interface

Message interface
-----------------

.. c:type:: mps_message_t

    The type of a :term:`message`.

    Messages are :term:`manually <manual memory management>` managed.
    They are created at the instigation of the MPS (but see
    :c:func:`mps_message_type_enable`), and are deleted by the
    :term:`client program` by calling :c:func:`mps_message_discard`.

    An :term:`arena` has a :term:`message queue` from which messages
    can be obtained by calling :c:func:`mps_message_get`.

    An :c:type:`mps_message_t` is a :term:`reference` into MPS managed
    memory, and can safely be :term:`fixed`.


.. c:function:: mps_clock_t mps_message_clock(mps_arena_t arena, mps_message_t message)

    Returns the time at which the MPS posted a :term:`message`.

    ``arena`` is the :term:`arena` which posted the message.

    ``message`` is a message retrieved by :c:func:`mps_message_get` and
    not yet discarded.

    If ``message`` belongs to one of the following supported message,
    return the time at which the MPS posted the message:

    * :c:type:`mps_message_type_gc`;
    * :c:type:`mps_message_type_gc_start`.

    For other message types, the value returned is always zero.

    Messages are asynchronous: they are posted by the MPS, wait on a
    queue, and are later collected by the :term:`client program`. Each
    message (of the supported message types) records the time that it
    was posted, and this is what :c:func:`mps_message_clock` returns.

    The time returned is the :c:func:`mps_clock_t` value returned by
    the :term:`plinth` function :c:func:`mps_clock` at the time the
    message was posted. You can subtract one clock value from another
    to get the time interval between the posting of two messages.


.. c:function:: void mps_message_discard(mps_arena_t arena, mps_message_t message)

    Indicate to the MPS that the :term:`client program` has no further
    use for a :term:`message` and the MPS can now reclaim any storage
    associated with the message.

    ``arena`` is the :term:`arena` which posted the message.

    ``message`` is the message. After this call, ``message`` is invalid
    and should not be passed as an argument to any message functions.

    Messages are essentially :term:`manually <manual memory
    management>` managed. This function allows the MPS to reclaim
    storage associated with messages. If the client does not discard
    messages then the resources used may grow without bound.

    As well as consuming resources, messages may have other effects
    that require them to be tidied by calling this function. In
    particular finalization messages refer to a :term:`finalized
    block`, and prevent the object from being reclaimed (subject to
    the usual :term:`garbage collection` liveness analysis). A
    finalized block cannot be reclaimed until all its finalization
    messages have been discarded. See
    :c:func:`mps_message_type_finalization`.

    .. seealso::

        :ref:`topic-finalization`.


.. c:function:: mps_message_type_t mps_message_type(mps_arena_t arena, mps_message_t message)

    Return the :term:`message type` of a :term:`message`.

    ``arena`` is the arena that posted the message.

    ``message`` is a message retrieved by :c:func:`mps_message_get` and
    not yet discarded.


.. index::
   single: message; queue interface

Message queue interface
-----------------------

.. c:function:: mps_bool_t mps_message_get(mps_message_t *message_o, mps_arena_t arena, mps_message_type_t message_type)

    Get a :term:`message` of a specified type from the :term:`message
    queue` for an :term:`arena`.

    ``message_o`` points to a location that will hold the address of the
    message if the function succeeds.

    ``arena`` is the arena.

    ``message_type`` is the type of message to return.

    If there is at least one message of the specified type on the
    message queue of the specified arena, then this function removes
    one such message from the queue, stores a pointer to the message
    in the location pointed to by ``message_o``, and returns true.
    Otherwise it returns false.


.. c:function:: mps_bool_t mps_message_poll(mps_arena_t arena)

    Determine whether there are currently any :term:`messages` on a :term:`message queue` for an :term:`arena`.

    ``arena`` is the arena whose message queue will be polled.

    Returns true if there is at least one message on the message queue
    for ``arena``, or false if the message queue is empty.

    .. note::

        If you are interested in a particular type of message, it is
        usually simpler to call :c:func:`mps_message_get`.


.. c:function:: mps_bool_t mps_message_queue_type(mps_message_type_t *message_type_o, mps_arena_t arena)

    Determine whether there are currently any :term:`messages` on a :term:`message queue` for an :term:`arena`, and
    return the :term:`message type` of the first message, if any.

    ``message_type_o`` points to a location that will hold the message
    type of the first message on the queue, if any.

    ``arena`` is the arena whose message queue will be polled.

    If there is at least one message on the message queue of ``arena``,
    then this function returns true, and also writes the message type
    of the first message on the queue into the location pointed to by
    ``message_type_o``. If there are no messages on the message queue,
    it returns false.

    .. note::

        If you are interested in a particular type of message, it is
        usually simpler to call :c:func:`mps_message_get`.