| MPI_SESSION_INIT(info, errhandler, session) | |
| IN info | info object to specify thread support level and MPI implementation specific resources (handle) |
| IN errhandler | error handler to invoke in the event that an error is encountered during this function call (handle) |
| OUT session | new session (handle) |
The info argument is used to request MPI functionality requirements and possible MPI implementation specific capabilities. The following info keys are predefined:
Advice to users.
Requesting `` MPI_THREAD_SINGLE'' thread support level is generally not recommended, because this will conflict with other components of an application requesting higher levels of thread support.
( End of advice to users.)
Advice
to implementors.
Owing to the restrictions of the MPI_THREAD_SINGLE thread support level, implementators are discouraged from making this the default thread support level for Sessions.
( End of advice to implementors.)
| MPI_SESSION_FINALIZE(session) | |
| INOUT session | session to be finalized (handle) |
This routine cleans up all MPI state associated with the supplied session. Every instantiated Session must be finalized using MPI_SESSION_FINALIZE. The handle session is set to MPI_SESSION_NULL by the call.
Before an MPI process invokes MPI_SESSION_FINALIZE, the process must perform all MPI calls needed to complete its involvement in MPI communications: it must locally complete all MPI operations that it initiated and it must execute matching calls needed to complete MPI communications initiated by other processes. This means that before calling MPI_SESSION_FINALIZE, all message handles associated with this session must be received (with MPI_MRECV or derived procedures) and all request handles associated with this session must be freed in the case of nonblocking operations, and must be inactive or freed in the case of persistent operations (i.e., by calling one of the procedures MPI_{TEST|WAIT}{|ANY|SOME|ALL} or MPI_REQUEST_FREE).
The call to MPI_SESSION_FINALIZE does not free objects created by MPI calls; these objects are freed using MPI_ XXX_FREE, MPI_COMM_DISCONNECT, or MPI_FILE_CLOSE calls.
Once MPI_SESSION_FINALIZE returns, no MPI procedure may be called in the Sessions Model that are related to this session (not even freeing objects that are derived from this session), except for those listed in Section MPI Functionality that is Always Available.
Advice to users.
Opaque objects and their handles may bind internal resources.
Therefore, it is highly recommended to explicitly free the handles associated with this session before finalizing it.
Such associated handles can be group, communicator, window, file, message, and request handles,
whereas datatype, operation (e.g., for reductions), error handler, and info handles exist independently
of the World Model or a session in the Sessions Model.
In addition, if attributes are cached on such an opaque object (see Section Caching),
then the delete callback functions are only invoked when the object is explicitly freed (or disconnected).
( End of advice to users.)
Most handles that exist independently from the World Model or a session in the Sessions Model, e.g., datatype handles,
can be created only while MPI is initialized.
For example, a datatype handle that was created when one particular session existed
can be used in any other session (or in the World Model), even if the second session
was initialized after the first session had already been finalized
and no other session existed in between.
See Section MPI Functionality that is Always Available for handle creation procedures that do not require that MPI is initialized.
MPI_SESSION_FINALIZE may be synchronizing on any or all of the groups associated with communicators, windows, or files derived from the session and not disconnected, freed, or closed, respectively, before the call to the MPI_SESSION_FINALIZE procedure. MPI_SESSION_FINALIZE behaves as if all such synchronizations occur concurrently. As MPI_COMM_FREE may mark a communicator for freeing later, MPI_SESSION_FINALIZE may be synchronizing on the group associated with a communicator that is only freed (with MPI_COMM_FREE) rather than disconnected (with MPI_COMM_DISCONNECT).
Rationale.
This rule is similar to the rule that MPI_FINALIZE is collective (see Finalizing MPI),
but does not require that MPI_SESSION_FINALIZE be collective over all connected MPI processes.
It also allows for cases where some MPI processes may have derived a set of communicators
using a different number of session handles. See Example Session Creation and Destruction Methods.
( End of rationale.)
Advice
to implementors.
This rule also allows for the completion of communications the MPI process is involved with
that may not yet be completed from the viewpoint of the underlying MPI system.
See Section Progress on progress
and the advice to implementors at the end of Section Finalizing MPI.
( End of advice to implementors.)
Advice
to implementors.
An MPI implementation should be able to implement the semantics of MPI_SESSION_FINALIZE
as a local procedure,
provided an application frees all MPI windows, closes all MPI files,
and uses MPI_COMM_DISCONNECT to free all MPI communicators
associated with a session
prior to invoking MPI_SESSION_FINALIZE on the corresponding session handle.
( End of advice to implementors.)
Example
Three MPI processes are connected with 2 communicators (indicated by the = symbols),
derived from one session handle in process X but from two separate session handles
in both process Y and Z.
process-X process-Y process-Z Remarks
sesX, sesYA, ses YB, sesZA and
sesZB are session handles.
(sesX)=======(sesYA)=======(sesZA) communicator_1 and
(sesX)=======(sesYB)=======(sesZB) communicator_2 are derived
from them.
SF(sesX) SF(sesYA) SF(sesZA) SF = MPI_SESSION_FINALIZE
SF(sesYB) SF(sesZB)
Process X has only to finalize its one session handle,
whereas the other two MPI processes have to call
MPI_SESSION_FINALIZE twice in the same sequence with respect to
the communicators derived from the session handles.
Specifically, both process Y and process Z shall call MPI_SESSION_FINALIZE
for the session from which communicator_1 was derived before calling the
MPI_SESSION_FINALIZE for the session from which communicator_2 was derived,
or vice versa (i.e., both shall finalize the session for communicator_2
first then finalize the session for communicator_1).
The call SF(ses) in process X may not return until
both SF(ses*A) and SF(ses*B) are called in processes Y and Z.