12.3.1. Session Creation and Destruction Methods

Up: The Sessions Model Next: Processes Sets Previous: The Sessions Model

MPI_SESSION_INIT(info, errhandler, session)
IN infoinfo object to specify thread support level and MPI implementation specific resources (handle)
IN errhandlererror handler to invoke in the event that an error is encountered during this function call (handle)
OUT sessionnew session (handle)
C binding
int MPI_Session_init(MPI_Info info, MPI_Errhandler errhandler, MPI_Session *session)
Fortran 2008 binding
MPI_Session_init(info, errhandler, session, ierror)

TYPE(MPI_Info), INTENT(IN) :: info
TYPE(MPI_Errhandler), INTENT(IN) :: errhandler
TYPE(MPI_Session), INTENT(OUT) :: session
Fortran binding


The info argument is used to request MPI functionality requirements and possible MPI implementation specific capabilities. The following info keys are predefined:

used to request the thread support level required for MPI objects derived from the Session. Allowed values are MPI_THREAD_SINGLE, MPI_THREAD_FUNNELED, MPI_THREAD_SERIALIZED, and MPI_THREAD_MULTIPLE. Note that the thread support value is specified by a string rather than the integer values supplied to MPI_INIT_THREAD. The thread support level actually provided by the MPI implementation can be determined via a subsequent call to MPI_SESSION_GET_INFO to return the info object associated with the Session. The default thread support level is MPI implementation dependent.
used to request support for memory allocation kinds to be used by the calling MPI process on MPI objects derived from the Session. See Section Memory Allocation Info. A value for this info key can also be supplied as an argument to an MPI startup mechanism as described in Section Portable MPI Process Startup.

The errhandler argument specifies an error handler to invoke in the event that the Session instantiation call encounters an error. The error handler shall be either a pre-defined error handler (see Error Handling) or one created using MPI_SESSION_CREATE_ERRHANDLER. Session instantiation is intended to be a lightweight operation. An MPI process may instantiate multiple Sessions. MPI_SESSION_INIT is always thread safe; multiple threads within an application may invoke it concurrently.

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.)

INOUT sessionsession to be finalized (handle)
C binding
int MPI_Session_finalize(MPI_Session *session)
Fortran 2008 binding
MPI_Session_finalize(session, ierror)

TYPE(MPI_Session), INTENT(INOUT) :: session
Fortran binding


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).


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.

Up: The Sessions Model Next: Processes Sets Previous: The Sessions Model

Return to MPI-4.1 Standard Index
Return to MPI Forum Home Page

(Unofficial) MPI-4.1 of November 2, 2023
HTML Generated on November 19, 2023