TITLE: Receptor Wait v8

* Version v8 was passed with a formal vote of 5/0/1 at the September
   2000 meeting after minor revisions to the binding and relocating
   two paragraphs in the document.

* V7: Removed an impossible termination condition (another thread calls
   FINALIZE) as noted at the June 2000 meeting where this proposal was
   supported by a 6/0/0 straw vote.

* The only change for version v6 is to add the C++ binding.

* Version v5 was passed by a formal vote of 8/0/0 at the June 1999
   meeting after a very minor textual revision.

* Version v4 was passed by a straw vote at the April 1999 meeting.
   The important change was that the receptor argument is not optional
   so this call can't be used as a timed wait.  However, a related
   timed wait facility was also passed -- see the SLEEP proposal
   provided separately.

* Version v3 added the statement that a waiting program will return from
   the RECEPTOR_WAIT call if (and only if) some other thread in the
   process calls FINALIZE.  The related issues are summarized in the
   ISSUES section.

* Version v2 added an ISSUES section for comments and how they were
   resolved, an attempt at identifying the sections where changes are
   required in the document, and a draft of the proposed actual wording.

SUMMARY:

A function is proposed to allow the main process of a program to wait
for an event to occur with a specified timeout.

BACKGROUND:

This proposal addresses an issue related to the ability of the main
process or thread of a program to make use of MPI/RT capabilities.  That
is, in the current MPI/RT standard (1.0) a program can respond to an
event by creating a receptor for that event and attaching a handler to
the receptor.  When the event occurs, the handler is activated. However,
there is currently no way for the main process or thread of a program to
wait for an event.

ISSUES:

  * Handlers on the receptor: The suggestion was made that this call take
    a special type of receptor with no handlers since handlers probably
    aren't need for this use.  To avoid adding a special receptor type,
    this proposal says that it is just a regular receptor, possibly with
    handlers.

  * No handlers on the receptor: It was pointed out that if no handlers
    were needed for the receptor, the implementation might optimize away
    the receptor and the event delivery.  This proposal says that such
    optimizations are not allowed, thus avoiding a special flag argument.

  * Waiting for the next real-time phase: Some applications will run in
    real-time phases.  In a time- or event-driven program, the main
    process or thread may want to wait until a phase is complete, and
    then reCOMMIT.  This can be accomplished by triggering an
    end-of-phase event for which the main process waits in RECEPTOR_WAIT.
    It doesn't require that some mechanism be provided to return from the
    waiting state.

  * Finalizing when waiting: What happens to a waiting thread when another
    thread of the program calls FINALIZE?  This proposal says that under
    those circumstances, any thread which is waiting will return from
    the RECEPTOR_WAIT call, returning an indication of why it returned.

  * Null receptor argument: Having the receptor argument optional was said
    to be a problem for the C++ interface, and using this approach to get
    a sleep/idle call was thought to be a kludge.  The Forum indicated a
    preference for a separate function specifically for sleep so the
    receptor argument is required.

PROPOSAL:

One new function and corresponding supporting text will be added to the
document as follows:

At the end of section 4.2 (Event Delivery Abstraction) add the following
paragraph:

    A program may block on a receptor while waiting for an event to occur
    (or a timeout to expire).  See section 4.4 for how this is done.

At the end of section 10.2.2 (Time-Driven Model) add the following
paragraph:

    After establishing the communication schedule and starting schedule
    operation, the program may wait for an event while program
    processing is done by the handlers.  See section 4.4 for how this is
    done.

At the end of section 10.3.2 (Event-Driven Model) add the following
paragraph:

    After establishing the communication events and starting the event
    operation, the program may wait for an event while program
    processing is done by the handlers.  See section 4.4 for how this is
    done.

Add a new section 4.4 "Waiting for an Event" as follows:

As described above, a program can respond asynchronously to an event by
creating a receptor for that event and attaching one or more handlers to
the receptor.  When the event occurs, the handlers are activated.  If a
program or thread must wait synchronously for an event to occur, a
receptor for the event is created (with or without handlers) and the
program or thread blocks waiting for the event to occur by calling the
following function:

    MPIRT_RECEPTOR_WAIT (receptor, timeout)
       IN     receptor      receptor for the event (MPIRT_RECEPTOR)
       IN     timeout       time to quit waiting (MPIRT_TIME_SPEC)

    int MPIRT_Receptor_wait (MPIRT_Receptor receptor,
                             MPIRT_Time_spec &timeout)

    int MPIRT::Receptor::Wait(const MPIRT::Time_Spec timeout)

This function blocks until either the receptor's event occurs, or until
the timeout has expired.  If the function returns due to timeout
expiration, the return value is MPIRT_ERR_TIMEOUT.

The arguments to the function are an event receptor and a time
specification.  The time specification is a timeout, so that if the
receptor's event has not occurred before the specified absolute time is
reached (or before the specified relative time has elapsed), the
function returns MPIRT_ERR_TIMEOUT to indicate that a timeout occurred.

If the time specification is MPIRT_TIME_SPEC_IGNORE, this is a simple
event wait and the function will not return until the event occurs.

The event receptor argument must be included in MPIRT_COMMIT so that the
system is aware that the event must be delivered to the process.
Therefore, a call to MPIRT_RECEPTOR_WAIT when MPI/RT is not in real-time
mode is an error and the function returns MPIRT_ERR_OBJECT_NOT_COMMITTED.

If the receptor object is uncommitted during the time a thread is waiting
for it, the function will return MPIRT_ERR_OBJECT_UNCOMMITTED.

The awaited receptor may or may not have associated handlers.  If there
are handlers, they are invoked in the usual manner when the event is
delivered.

    Advice to implementors.  Even if no handlers are associated with a
    receptor, the implementation must assume that the receptor will be
    used as it may later appear as an argument to MPIRT_RECEPTOR_WAIT.
    (End of advice to implementors.)

NEW THINGS ADDED TO MPI/RT:

These need to be indexed and included in the end-of-chapter summaries.
    MPIRT_RECEPTOR_WAIT
    MPIRT_ERR_OBJECT_UNCOMMITTED