TITLE: Sleep v5

* With a minor binding change, version 5 passed at the September 2000
   meeting with a 6/0/0 formal vote.

* At the June 2000 meeting, changed MPIRT_TIME_INFINITE to the already
   defined MPIRT_TIME_SPEC_IGNORE to avoid introducing another built-in
   timespec and all the possible ways it might be used.  Also removed a
   reference to "another thread".  Passed with a straw vote of 6/0/0.

* Version v3 adds the C++ binding.

* Version v2 was passed by formal vote 7/0/1 at the June 1999 meeting.
   It includes modifications made at the meeting to return when
   either COMMIT or UNCOMMIT is called, and to allow the caller
   to determine why it exited by looking at the return code.  There
   is also a new error return if you ask for an absolute time which
   has already passed.

* Version v1 was passed by a straw vote at the April 1999 meeting.  This
   proposal was derived directly from v3 of the Receptor Wait proposal
   when it was agreed that getting a sleep by providing a null
   receptor to RECEPTOR_WAIT was too much of a kludge.

SUMMARY:

A function is proposed to allow the main process (or any thread) of a 
program to sleep until an absolute time arrives, or until a relative 
time period has elapsed.

BACKGROUND:

This proposal addresses two issues related to the ability of the main
process or thread of a program to make use of MPI/RT capabilities.

First, there is no method for the main process or thread to wait for a
specified time to arrive or a time interval to elapse.  MPI/RT time
specifications may be used only to describe timeout values for transfers
or QoS requirements.

Second, in an application which is driven by events or a time schedule,
once the communication and QoS parameters have been established the
main process has no further work to do, but must nevertheless not exit.
This may be considered as entering an idle state; MPI/RT 1.0 cannot
describe this situation.

ISSUES:

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

  * A similar question arises for COMMIT and UNCOMMIT; the answer
    is the same.

PROPOSAL:

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

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

    After establishing the communication schedule and starting schedule
    operation, the main program may sleep while program processing is
    done by the handlers.  See section 14.5 for how this is done.

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

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

Add a new section 14.5 "Timed Waiting" as follows:

A program or thread may block while waiting for an absolute time to 
arrive or for a time period to elapse by calling the following function:

    MPIRT_SLEEP (waittime)
       IN     waittime      absolute time to await or relative
                            time period to elapse (MPIRT_TIME_SPEC)

    int MPIRT_Sleep (MPIRT_Time_spec timeout)

    int MPIRT::Sleep(const MPIRT::Time_Spec &timeout)

This function blocks until the specified absolute time is reached or the 
specified relative time has elapsed.  The return value is MPIRT_SUCCESS, 
not MPIRT_ERR_TIMEOUT.  There is no quality of service associated with
this late-binding function.

If an absolute time is given which has already arrived, the function
returns immediately with return value MPIRT_ERR_PAST_TIME.

This function will return before the specified time for three 
conditions: one of MPIRT_COMMIT, MPIRT_UNCOMMIT, or MPIRT_FINALIZE is 
completed.  The return value will then be MPIRT_ERR_COMMITTED, 
MPIRT_ERR_UNCOMMITTED, or MPIRT_ERR_FINALIZED respectively.

If the calling thread has no need to return, the timespec argument may
be given as MPIRT_TIME_SPEC_IGNORE, in which case control is transferred
to the MPI/RT library and the call will not return except for the cases
described above.

Since timespecs are not committable objects, calls to this function may
occur when the MPI/RT program is not in real-time mode.

NEW THINGS ADDED TO MPI/RT:

These need to be indexed and included in the end-of-chapter summaries.
    MPIRT_SLEEP
    MPIRT_ERR_PAST_TIME
    MPIRT_ERR_COMMITTED
    MPIRT_ERR_UNCOMMITTED