9175da1e02
versions, dates and build names. Fixes trac:1387 Big thanks to Jeff and Brian for help and oversight. This commit was SVN r19120. The following Trac tickets were found above: Ticket 1387 --> https://svn.open-mpi.org/trac/ompi/ticket/1387
124 строки
4.8 KiB
Plaintext
124 строки
4.8 KiB
Plaintext
.\"Copyright 2006-2008 Sun Microsystems, Inc.
|
|
.\" Copyright (c) 1996 Thinking Machines Corporation
|
|
.TH MPI_Testsome 3 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#"
|
|
.SH NAME
|
|
\fBMPI_Testsome\fP \- Tests for completion of one or more previously initiated communications in a list.
|
|
|
|
.SH SYNTAX
|
|
.ft R
|
|
.SH C Syntax
|
|
.nf
|
|
#include <mpi.h>
|
|
int MPI_Testsome(int \fIincount\fP, MPI_Request \fI*array_of_requests\fP,
|
|
int\fI *outcount\fP, int\fI *array_of_indices\fP, MPI_Status\fI *array_of_statuses\fP)
|
|
|
|
.SH Fortran Syntax
|
|
.nf
|
|
INCLUDE 'mpif.h'
|
|
MPI_TESTSOME(\fIINCOUNT, ARRAY_OF_REQUESTS, OUTCOUNT,
|
|
ARRAY_OF_INDICES, ARRAY_OF_STATUSES, IERROR\fP)
|
|
INTEGER \fIINCOUNT, ARRAY_OF_REQUESTS(*)\fP
|
|
INTEGER \fIOUTCOUNT, ARRAY_OF_INDICES(*)\fP
|
|
INTEGER \fIARRAY_OF_STATUSES(MPI_STATUS_SIZE,*), IERROR\fP
|
|
|
|
.SH C++ Syntax
|
|
.nf
|
|
#include <mpi.h>
|
|
static int Request::Testsome(int \fIincount\fP, Request
|
|
\fIarray_of_requests\fP[], int \fIarray_of_indices\fP[], Status \fIarray_of_statuses\fP[])
|
|
|
|
static int Request::Testsome(int \fIincount\fP, Request
|
|
\fIarray_of_requests\fP[], int \fIarray_of_indices\fP[])
|
|
|
|
.SH INPUT PARAMETERS
|
|
.ft R
|
|
.TP 1i
|
|
incount
|
|
Length of array_of_requests (integer).
|
|
.TP 1i
|
|
array_of_requests
|
|
Array of requests (array of handles).
|
|
|
|
.SH OUTPUT PARAMETERS
|
|
.ft R
|
|
.TP 1i
|
|
outcount
|
|
Number of completed requests (integer).
|
|
.TP 1i
|
|
array_of_indices
|
|
Array of indices of operations that completed (array of integers).
|
|
.TP 1i
|
|
array_of_statuses
|
|
Array of status objects for operations that completed (array of status).
|
|
.ft R
|
|
.TP 1i
|
|
IERROR
|
|
Fortran only: Error status (integer).
|
|
|
|
.SH DESCRIPTION
|
|
.ft R
|
|
Behaves like MPI_Waitsome, except that it returns immediately. If no operation has completed it returns outcount = 0. If there is no active handle in the list, it returns outcount = MPI_UNDEFINED.
|
|
.sp
|
|
MPI_Testsome is a local operation, which returns immediately, whereas MPI_Waitsome blocks until a communication completes, if it was passed a list that contains at least one active handle. Both calls fulfill a fairness requirement: If a request for a receive repeatedly appears in a list of requests passed to MPI_Waitsome or MPI_Testsome, and a matching send has been posted, then the receive will eventually succeed unless the send is satisfied by another receive; send requests also fulfill this fairness requirement.
|
|
.sp
|
|
Errors that occur during the execution of MPI_Testsome are handled as for
|
|
MPI_Waitsome.
|
|
.sp
|
|
If your application does not need to examine the \fIarray_of_statuses\fP field, you can save resources by using the predefined constant MPI_STATUSES_IGNORE can be used as a special value for the \fIarray_of_statuses\fP argument.
|
|
|
|
.SH NOTES
|
|
The use of MPI_Testsome is likely to be more
|
|
efficient than the use of MPI_Testany. The former returns information on all completed communications; with the latter, a new call is required for each communication that completes.
|
|
.sp
|
|
A server with multiple clients can use MPI_Waitsome so as not to starve any client. Clients send messages to the server with service requests. The server calls MPI_Waitsome with one receive request for each client, then handles all receives that have completed. If a call to MPI_Waitany is used instead, then one client could starve while requests from another client always sneak in first.
|
|
|
|
.SH ERRORS
|
|
For each invocation of MPI_Testsome, if one or more requests generate
|
|
an MPI exception, only the \fIfirst\fP MPI request that caused an
|
|
exception will be passed to its corresponding error handler. No other
|
|
error handlers will be invoked (even if multiple requests generated
|
|
exceptions). However, \fIall\fP requests that generate an exception
|
|
will have a relevant error code set in the corresponding
|
|
status.MPI_ERROR field (unless MPI_IGNORE_STATUSES was used).
|
|
.sp
|
|
The default error handler aborts the MPI job, except for I/O function
|
|
errors. The error handler may be changed with MPI_Comm_set_errhandler,
|
|
MPI_File_set_errhandler, or MPI_Win_set_errhandler (depending on the
|
|
type of MPI handle that generated the MPI request); the predefined
|
|
error handler MPI_ERRORS_RETURN may be used to cause error values to
|
|
be returned. Note that MPI does not guarantee that an MPI program can
|
|
continue past an error.
|
|
.sp
|
|
If the invoked error handler allows MPI_Testsome to return to the
|
|
caller, the value MPI_ERR_IN_STATUS will be returned in the C and
|
|
Fortran bindings. In C++, if the predefined error handler
|
|
MPI::ERRORS_THROW_EXCEPTIONS is used, the value MPI::ERR_IN_STATUS
|
|
will be contained in the MPI::Exception object. The MPI_ERROR field
|
|
can then be examined in the array of returned statuses to determine
|
|
exactly which request(s) generated an exception.
|
|
|
|
.SH SEE ALSO
|
|
.ft R
|
|
.sp
|
|
MPI_Comm_set_errhandler
|
|
.br
|
|
MPI_File_set_errhandler
|
|
.br
|
|
MPI_Test
|
|
.br
|
|
MPI_Testall
|
|
.br
|
|
MPI_Testany
|
|
.br
|
|
MPI_Wait
|
|
.br
|
|
MPI_Waitall
|
|
.br
|
|
MPI_Waitany
|
|
.br
|
|
MPI_Waitsome
|
|
.br
|
|
MPI_Win_set_errhandler
|
|
.br
|
|
|