274 lines
8.7 KiB
Groff
274 lines
8.7 KiB
Groff
.\" Man page generated from reStructuredText.
|
||
.
|
||
.TH "MPIX_COMM_AGREE" "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\%MPIX_Comm_agree\fP, \fI\%MPIX_Comm_iagree\fP \- Agree on a flag value
|
||
from all live processes and distributes the result back to all live
|
||
processes, even after process failures.
|
||
.sp
|
||
This is part of the User Level Fault Mitigation \fI\%ULFM extension\fP\&.
|
||
.SH SYNTAX
|
||
.SS C Syntax
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
#include <mpi.h>
|
||
#include <mpi\-ext.h>
|
||
|
||
int MPIX_Comm_agree(MPI_Comm comm, int *flag)
|
||
|
||
int MPIX_Comm_iagree(MPI_Comm comm, int *flag, MPI_Request *request)
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SS Fortran Syntax
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
USE MPI
|
||
USE MPI_EXT
|
||
! or the older form: INCLUDE \(aqmpif.h\(aq
|
||
|
||
MPIX_COMM_AGREE(COMM, FLAG, IERROR)
|
||
INTEGER COMM, FLAG, IERROR
|
||
|
||
MPIX_COMM_IAGREE(COMM, FLAG, REQUEST, IERROR)
|
||
INTEGER COMM, FLAG, REQUEST, IERROR
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SS Fortran 2008 Syntax
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
USE mpi_f08
|
||
USE mpi_ext_f08
|
||
|
||
MPIX_Comm_agree(comm, flag, ierror)
|
||
TYPE(MPI_Comm), INTENT(IN) :: comm
|
||
INTEGER, INTENT(INOUT) :: flag
|
||
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
|
||
|
||
MPIX_COMM_IAGREE(COMM, FLAG, REQUEST, IERROR)
|
||
TYPE(MPI_Comm), INTENT(IN) :: comm
|
||
INTEGER, INTENT(INOUT), ASYNCHRONOUS :: flag
|
||
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
|
||
\fBcomm\fP: Communicator (handle).
|
||
.IP \(bu 2
|
||
\fBflag\fP: Binary flags (integer).
|
||
.UNINDENT
|
||
.SH OUTPUT PARAMETERS
|
||
.INDENT 0.0
|
||
.IP \(bu 2
|
||
\fBflag\fP: Reduced binary flags (integer).
|
||
.IP \(bu 2
|
||
\fBrequest\fP: Request (handle, non\-blocking only).
|
||
.IP \(bu 2
|
||
\fBierror\fP: Fortran only: Error status (integer).
|
||
.UNINDENT
|
||
.SH DESCRIPTION
|
||
.sp
|
||
This collective communication agrees on the integer value \fIflag\fP and
|
||
(implicitly) on the group of failed processes in \fIcomm\fP\&.
|
||
.sp
|
||
On completion, all non\-failed MPI processes have agreed to set the
|
||
output integer value of \fIflag\fP to the result of a \fIbitwise AND\fP
|
||
operation over the contributed input values of \fIflag\fP\&.
|
||
.sp
|
||
\fI\%MPIX_Comm_iagree\fP is the non\-blocking variant of \fI\%MPIX_Comm_agree\fP\&.
|
||
.SH PROCESS FAILURES
|
||
.sp
|
||
When an MPI process fails before contributing to the agree operation,
|
||
the \fIflag\fP is computed ignoring its contribution, and the operation
|
||
raises an error of class MPIX_ERR_PROC_FAILED.
|
||
.sp
|
||
When an error of class MPIX_ERR_PROC_FAILED is raised, it is consistently
|
||
raised at all MPI processes in the group(s) of \fIcomm\fP\&.
|
||
.sp
|
||
After \fI\%MPIX_Comm_agree\fP raised an error of class MPIX_ERR_PROC_FAILED,
|
||
the group produced by a subsequent call to \fI\%MPIX_Comm_get_failed\fP on
|
||
\fIcomm\fP contains every MPI process that didn’t contribute to the
|
||
computation of \fIflag\fP\&.
|
||
.SH WHEN THE COMMUNICATOR CONTAINS ACKNOWLEDGED FAILURES
|
||
.sp
|
||
If \fBall\fP MPI processes in the group of \fIcomm\fP have acknowledged the failure
|
||
of an MPI process (using \fI\%MPIX_Comm_ack_failed\fP) prior to the call to
|
||
\fI\%MPIX_Comm_agree\fP (or \fI\%MPIX_Comm_iagree\fP), the MPIX_ERR_PROC_FAILED
|
||
error is not raised when the output value of \fIflag\fP ignores the
|
||
contribution of that failed process. Note that this is an uniform property:
|
||
if a non\-contributing process is found to be not\-acknowledged at any live
|
||
process in \fIcomm\fP, all processes raise an error of class MPIX_ERR_PROC_FAILED.
|
||
.sp
|
||
\fBExample 1:\fP Using a combination of \fI\%MPIX_Comm_ack_failed\fP and
|
||
\fI\%MPIX_Comm_agree\fP users can propagate and synchronize the knowledge
|
||
of failures across all MPI processes in \fIcomm\fP\&.
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.sp
|
||
.nf
|
||
.ft C
|
||
Comm_get_failed_consistent(MPI_Comm c, MPI_Group * g) {
|
||
int rc; int T=1;
|
||
int size; int num_acked;
|
||
MPI_Group gf;
|
||
int ranges[3] = {0, 0, 1};
|
||
|
||
MPI_Comm_size(c, &size);
|
||
|
||
do {
|
||
/* this routine is not pure: calling MPI_Comm_ack_failed
|
||
* affects the state of the communicator c */
|
||
MPIX_Comm_ack_failed(c, size, &num_acked);
|
||
/* we simply ignore the T value in this example */
|
||
rc = MPIX_Comm_agree(c, &T);
|
||
} while( rc != MPI_SUCCESS );
|
||
/* after this loop, MPIX_Comm_agree has returned MPI_SUCCESS at
|
||
* all processes, so all processes have Acknowledged the same set of
|
||
* failures. Let\(aqs get that set of failures in the g group. */
|
||
if( 0 == num_acked ) {
|
||
*g = MPI_GROUP_EMPTY;
|
||
}
|
||
else {
|
||
MPIX_Comm_get_failed(c, &gf);
|
||
ranges[1] = num_acked \- 1;
|
||
MPI_Group_range_incl(gf, 1, ranges, g);
|
||
MPI_Group_free(&gf);
|
||
}
|
||
}
|
||
.ft P
|
||
.fi
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SH WHEN THE COMMUNICATOR IS REVOKED
|
||
.sp
|
||
This function never raises an error of class MPIX_ERR_REVOKED.
|
||
The defined semantics of \fI\%MPIX_Comm_agree\fP are maintained when \fIcomm\fP
|
||
is revoked, or when the group of \fIcomm\fP contains failed MPI processes.
|
||
In particular, \fI\%MPIX_Comm_agree\fP is a collective operation, even
|
||
when \fIcomm\fP is revoked.
|
||
.SH WHEN COMMUNICATOR IS AN INTER-COMMUNICATOR
|
||
.sp
|
||
When the communicator is an inter\-communicator, the value of \fIflag\fP is
|
||
a \fIbitwise AND\fP operation over the values contributed by the remote
|
||
group.
|
||
.sp
|
||
When an error of class MPIX_ERR_PROC_FAILED is raised, it is consistently
|
||
raised at all MPI processes in the group(s) of \fIcomm\fP, that is, both
|
||
the local and remote groups of the inter\-communicator.
|
||
.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
|
||
\fBSEE ALSO:\fP
|
||
.INDENT 0.0
|
||
.INDENT 3.5
|
||
.INDENT 0.0
|
||
.IP \(bu 2
|
||
\fI\%MPIX_Comm_is_revoked\fP
|
||
.IP \(bu 2
|
||
\fI\%MPIX_Comm_ack_failed\fP
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.UNINDENT
|
||
.SH COPYRIGHT
|
||
2003-2025, The Open MPI Community
|
||
.\" Generated by docutils manpage writer.
|
||
.
|