339 lines
11 KiB
Groff
339 lines
11 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.TH "MPI_GREQUEST_START" "3" "Feb 14, 2025" "" "Open MPI"
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.sp
|
|
\fI\%MPI_Grequest_start\fP — Starts a generalized request and returns a
|
|
handle to it in \fBrequest\fP\&.
|
|
.SH SYNTAX
|
|
.SS C Syntax
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
#include <mpi.h>
|
|
|
|
int MPI_Grequest_start(MPI_Grequest_query_function *query_fn,
|
|
MPI_Grequest_free_function *free_fn,
|
|
MPI_Grequest_cancel_function *cancel_fn, void *extra_state,
|
|
MPI_Request *request)
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Fortran Syntax
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
USE MPI
|
|
! or the older form: INCLUDE \(aqmpif.h\(aq
|
|
|
|
MPI_GREQUEST_START(QUERY_FN, FREE_FN, CANCEL_FN, EXTRA_STATE,
|
|
REQUEST, IERROR)
|
|
INTEGER REQUEST, IERROR
|
|
EXTERNAL QUERY_FN, FREE_FN, CANCEL_FN
|
|
INTEGER(KIND=MPI_ADDRESS_KIND) EXTRA_STATE
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SS Fortran 2008 Syntax
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
USE mpi_f08
|
|
|
|
MPI_Grequest_start(query_fn, free_fn, cancel_fn, extra_state, request,
|
|
ierror)
|
|
PROCEDURE(MPI_Grequest_query_function) :: query_fn
|
|
PROCEDURE(MPI_Grequest_free_function) :: free_fn
|
|
PROCEDURE(MPI_Grequest_cancel_function) :: cancel_fn
|
|
INTEGER(KIND=MPI_ADDRESS_KIND), INTENT(IN) :: extra_state
|
|
TYPE(MPI_Request), INTENT(OUT) :: request
|
|
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.SH INPUT PARAMETERS
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
.INDENT 2.0
|
|
.TP
|
|
.B \fBquery_fn\fP
|
|
Callback function invoked when request status is
|
|
queried (function).
|
|
.UNINDENT
|
|
.IP \(bu 2
|
|
.INDENT 2.0
|
|
.TP
|
|
.B \fBfree_fn\fP
|
|
Callback function invoked when request is freed
|
|
(function).
|
|
.UNINDENT
|
|
.IP \(bu 2
|
|
.INDENT 2.0
|
|
.TP
|
|
.B \fBcancel_fn\fP
|
|
Callback function invoked when request is canceled
|
|
(function).
|
|
.UNINDENT
|
|
.IP \(bu 2
|
|
\fBextra_state\fP : Extra state.
|
|
.UNINDENT
|
|
.SH OUTPUT PARAMETERS
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
\fBrequest\fP : Generalized request (handle).
|
|
.IP \(bu 2
|
|
\fBierror\fP : Fortran only: Error status (integer).
|
|
.UNINDENT
|
|
.SH DESCRIPTION
|
|
.sp
|
|
\fI\%MPI_Grequest_start\fP starts a generalized \fBrequest\fP and returns a
|
|
handle to it in \fBrequest\fP\&.
|
|
.sp
|
|
The syntax and meaning of the callback functions are listed below. All
|
|
callback functions are passed the \fBextra_state\fP argument that was
|
|
associated with the \fBrequest\fP by the starting call
|
|
\fI\%MPI_Grequest_start\fP\&. This can be used to maintain user\-defined state
|
|
for the \fBrequest\fP\&. In C, the query function is
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
typedef int MPI_Grequest_query_function(void *extra_state,
|
|
MPI_Status *status);
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
In Fortran, it is
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
SUBROUTINE GREQUEST_QUERY_FUNCTION(EXTRA_STATE, STATUS, IERROR)
|
|
INTEGER STATUS(MPI_STATUS_SIZE), IERROR
|
|
INTEGER(KIND=MPI_ADDRESS_KIND) EXTRA_STATE
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
The \fBquery_fn\fP function computes the status that should be returned
|
|
for the generalized request. The status also includes information about
|
|
successful/unsuccessful cancellation of the request (result to be
|
|
returned by \fBMPI_Test_cancelled\fP).
|
|
.sp
|
|
The \fBquery_fn\fP function is invoked by the
|
|
\fBMPI_{Wait|Test}{any|some|all}\fP call that completed the generalized
|
|
request associated with this callback. The callback function is also
|
|
invoked by calls to \fBMPI_Request_get_status\fP if the request is
|
|
complete when the call occurs. In both cases, the callback is passed a
|
|
reference to the corresponding status variable passed by the user to the
|
|
MPI call. If the user provided \fBMPI_STATUS_IGNORE\fP or
|
|
\fBMPI_STATUSES_IGNORE\fP to the MPI function that causes \fBquery_fn\fP to
|
|
be called, then MPI will pass a valid status object to \fBquery_fn\fP, and
|
|
this status will be ignored upon return of the callback function. Note
|
|
that \fBquery_fn\fP is invoked only after \fBMPI_Grequest_complete\fP is
|
|
called on the request; it may be invoked several times for the same
|
|
generalized request. Note also that a call to
|
|
\fBMPI_{Wait|Test}{some|all}\fP may cause multiple invocations of
|
|
\fBquery_fn\fP callback functions, one for each generalized request that
|
|
is completed by the MPI call. The order of these invocations is not
|
|
specified by MPI.
|
|
.sp
|
|
In C, the free function is
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
typedef int MPI_Grequest_free_function(void *extra_state);
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
And in Fortran, it is
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
SUBROUTINE GREQUEST_FREE_FUNCTION(EXTRA_STATE, IERROR)
|
|
INTEGER IERROR
|
|
INTEGER(KIND=MPI_ADDRESS_KIND) EXTRA_STATE
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
The \fBfree_fn\fP callback function is invoked to clean up user\-allocated
|
|
resources when the generalized request is freed.
|
|
.sp
|
|
The \fBfree_fn\fP function is invoked by the
|
|
\fBMPI_{Wait|Test}{any|some|all}\fP call that completed the generalized
|
|
request associated with this callback. \fBfree_fn\fP is invoked after the
|
|
call to \fBquery_fn\fP for the same request. However, if the MPI call
|
|
completed multiple generalized requests, the order in which \fBfree_fn\fP
|
|
callback functions are invoked is not specified by MPI.
|
|
.sp
|
|
The \fBfree_fn\fP callback is also invoked for generalized requests that
|
|
are freed by a call to \fBMPI_Request_free\fP (no call to
|
|
\fBMPI_{Wait|Test}{any|some|all}\fP will occur for such a request). In
|
|
this case, the callback function will be called either in the MPI call
|
|
\fBMPI_Request_free(request)\fP or in the MPI call
|
|
\fBMPI_Grequest_complete(request)\fP, whichever happens last. In other
|
|
words, in this case the actual freeing code is executed as soon as both
|
|
calls (\fBMPI_Request_free\fP and \fBMPI_Grequest_complete\fP) have
|
|
occurred. The \fBrequest\fP is not deallocated until after \fBfree_fn\fP
|
|
completes. Note that \fBfree_fn\fP will be invoked only once per request
|
|
by a correct program.
|
|
.sp
|
|
In C, the cancel function is
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
typedef int MPI_Grequest_cancel_function(void *extra_state, int complete);
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
In Fortran, the cancel function is
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
SUBROUTINE GREQUEST_CANCEL_FUNCTION(EXTRA_STATE, COMPLETE, IERROR)
|
|
INTEGER IERROR
|
|
INTEGER(KIND=MPI_ADDRESS_KIND) EXTRA_STATE
|
|
LOGICAL COMPLETE
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
The \fBcancel_fn\fP function is invoked to start the cancellation of a
|
|
generalized request. It is called by \fBMPI_Request_cancel(request)\fP\&.
|
|
MPI passes to the callback function complete=true if
|
|
\fBMPI_Grequest_complete\fP has already been called on the request, and
|
|
complete=false otherwise.
|
|
.SH ERRORS
|
|
.sp
|
|
Almost all MPI routines return an error value; C routines as the return result
|
|
of the function and Fortran routines in the last argument.
|
|
.sp
|
|
Before the error value is returned, the current MPI error handler associated
|
|
with the communication object (e.g., communicator, window, file) is called.
|
|
If no communication object is associated with the MPI call, then the call is
|
|
considered attached to MPI_COMM_SELF and will call the associated MPI error
|
|
handler. When MPI_COMM_SELF is not initialized (i.e., before
|
|
\fI\%MPI_Init\fP/\fI\%MPI_Init_thread\fP, after \fI\%MPI_Finalize\fP, or when using the Sessions
|
|
Model exclusively) the error raises the initial error handler. The initial
|
|
error handler can be changed by calling \fI\%MPI_Comm_set_errhandler\fP on
|
|
MPI_COMM_SELF when using the World model, or the mpi_initial_errhandler CLI
|
|
argument to mpiexec or info key to \fI\%MPI_Comm_spawn\fP/\fI\%MPI_Comm_spawn_multiple\fP\&.
|
|
If no other appropriate error handler has been set, then the MPI_ERRORS_RETURN
|
|
error handler is called for MPI I/O functions and the MPI_ERRORS_ABORT error
|
|
handler is called for all other MPI functions.
|
|
.sp
|
|
Open MPI includes three predefined error handlers that can be used:
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
\fBMPI_ERRORS_ARE_FATAL\fP
|
|
Causes the program to abort all connected MPI processes.
|
|
.IP \(bu 2
|
|
\fBMPI_ERRORS_ABORT\fP
|
|
An error handler that can be invoked on a communicator,
|
|
window, file, or session. When called on a communicator, it
|
|
acts as if \fI\%MPI_Abort\fP was called on that communicator. If
|
|
called on a window or file, acts as if \fI\%MPI_Abort\fP was called
|
|
on a communicator containing the group of processes in the
|
|
corresponding window or file. If called on a session,
|
|
aborts only the local process.
|
|
.IP \(bu 2
|
|
\fBMPI_ERRORS_RETURN\fP
|
|
Returns an error code to the application.
|
|
.UNINDENT
|
|
.sp
|
|
MPI applications can also implement their own error handlers by calling:
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
\fI\%MPI_Comm_create_errhandler\fP then \fI\%MPI_Comm_set_errhandler\fP
|
|
.IP \(bu 2
|
|
\fI\%MPI_File_create_errhandler\fP then \fI\%MPI_File_set_errhandler\fP
|
|
.IP \(bu 2
|
|
\fI\%MPI_Session_create_errhandler\fP then \fI\%MPI_Session_set_errhandler\fP or at \fI\%MPI_Session_init\fP
|
|
.IP \(bu 2
|
|
\fI\%MPI_Win_create_errhandler\fP then \fI\%MPI_Win_set_errhandler\fP
|
|
.UNINDENT
|
|
.sp
|
|
Note that MPI does not guarantee that an MPI program can continue past
|
|
an error.
|
|
.sp
|
|
See the \fI\%MPI man page\fP for a full list of \fI\%MPI error codes\fP\&.
|
|
.sp
|
|
See the Error Handling section of the MPI\-3.1 standard for
|
|
more information.
|
|
.sp
|
|
All callback functions return an error code. The code is passed back and
|
|
dealt with as appropriate for the error code by the MPI function that
|
|
invoked the callback function. For example, if error codes are returned,
|
|
then the error code returned by the callback function will be returned
|
|
by the MPI function that invoked the callback function. In the case of a
|
|
\fBMPI_{Wait|Test}any\fP call that invokes both \fBquery_fn\fP and
|
|
\fBfree_fn\fP, the MPI call will return the error code returned by the
|
|
last callback, namely \fBfree_fn\fP\&. If one or more of the \fBrequest\(ga\(gas
|
|
in a call to \(ga\(gaMPI_{Wait|Test}{some|all\fP} has failed, then the MPI call
|
|
will return \fBMPI_ERR_IN_STATUS\fP\&. In such a case, if the MPI call was
|
|
passed an array of statuses, then MPI will return in each of the
|
|
statuses that correspond to a completed generalized \fBrequest\fP the
|
|
error code returned by the corresponding invocation of its \fBfree_fn\fP
|
|
callback function. However, if the MPI function was passed
|
|
\fBMPI_STATUSES_IGNORE\fP, then the individual error codes returned by
|
|
each callback function will be lost.
|
|
.SH COPYRIGHT
|
|
2003-2025, The Open MPI Community
|
|
.\" Generated by docutils manpage writer.
|
|
.
|