mpidu_sock.h

fortran并行计算包

. MPIDU_SOCK_ERR_INIT - Sock module not initialized
. MPIDU_SOCK_ERR_BAD_SOCK - invalid sock object
. MPIDU_SOCK_ERR_BAD_LEN - length parameters must be greater than zero and maxlen must be greater than minlen
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
. MPIDU_SOCK_ERR_INPROGRESS - this operation overlapped with another like operation already in progress
- MPIDU_SOCK_ERR_FAIL - other error attempting to post read

Events generated:
. MPIDU_SOCK_OP_READ

Event errors: a MPI error code with a Sock extended error class
+ MPI_SUCCESS -  successfully established
. MPIDU_SOCK_ERR_BAD_BUF - using the buffer described by buf and maxlen resulted in a memory fault
. MPIDU_SOCK_ERR_SOCK_CLOSED - the sock object was closed locally
. MPIDU_SOCK_ERR_CONN_CLOSED - the connection was closed by the peer
. MPIDU_SOCK_ERR_CONN_FAILED - the connection failed
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
- MPIDU_SOCK_ERR_FAIL - other error completing the read

Notes:
Only one read operation may be posted at a time.  Furthermore, an immediate read may not be performed while a posted write is
outstanding.  This is considered to be an application error, and the results of doing so are undefined.  The implementation may
choose to catch the error and return MPIDU_SOCK_ERR_INPROGRESS, but it is not required to do so.

If MPIDU_Sock_post_close() is called before the posted read operation completes, the read operation will be terminated and a
MPIDU_SOCK_OP_READ event containing a MPIDU_SOCK_ERR_SOCK_CLOSED error will be generated.  This event will be returned by
MPIDU_Sock_wait() prior to the MPIDU_SOCK_OP_CLOSE event.

Thread safety:
MPIDU_Sock_post_read() may be called while another thread is attempting to perform an immediate write or post a write operation on
the same sock.  MPIDU_Sock_post_read() may also be called while another thread is calling or blocking in MPIDU_Sock_wait() on the
same sock set to which the specified sock belongs.

MPIDU_Sock_post_write() may not be called while another thread is performing an immediate read on the same sock.  This is
considered to be an application error, and the results of doing so are undefined.  The implementation may choose to catch the error
and return MPIDU_SOCK_ERR_INPROGRESS, but it is not required to do so.

Calling MPIDU_Sock_post_read() during or after the call to MPIDU_Sock_post_close() is consider an application error.  The result of
doing so is undefined.  The application should coordinate the closing of a sock with the activities of other threads to ensure that
one thread is not attempting to post a new operation while another thread is attempting to close the sock.

Module:
Utility-Sock
@*/
int MPIDU_Sock_post_read(MPIDU_Sock_t sock, void * buf, MPIU_Size_t minbr, MPIU_Size_t maxbr,
                         MPIDU_Sock_progress_update_func_t fn);


/*@
MPIDU_Sock_post_readv - request that a vector of data be read from a sock

Input Parameters:
+ sock - sock object from which the data is to read
. iov - I/O vector describing buffers into which the data is placed
. iov_n - number of elements in I/O vector (must be less than MPID_IOV_LIMIT)
+ upate_fn - application progress update function (may be NULL)

Return value: a MPI error code with a Sock extended error class
+ MPI_SUCCESS - request to read was successfully posted
. MPIDU_SOCK_ERR_INIT - Sock module not initialized
. MPIDU_SOCK_ERR_BAD_SOCK - invalid sock object
. MPIDU_SOCK_ERR_BAD_LEN - iov_n is out of range
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
. MPIDU_SOCK_ERR_INPROGRESS - this operation overlapped with another like operation already in progress
- MPIDU_SOCK_ERR_FAIL - other error attempting to post read

Events generated:
. MPIDU_SOCK_OP_READ

Event errors: a MPI error code with a Sock extended error class
+ MPI_SUCCESS -  successfully established
. MPIDU_SOCK_ERR_BAD_BUF - using the buffer described by iov and iov_n resulted in a memory fault
. MPIDU_SOCK_ERR_SOCK_CLOSED - the sock object was closed locally
. MPIDU_SOCK_ERR_CONN_CLOSED - the connection was closed by the peer
. MPIDU_SOCK_ERR_CONN_FAILED - the connection failed
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
- MPIDU_SOCK_ERR_FAIL - other error completing the read

Notes:
Only one read operation may be posted at a time.  Furthermore, an immediate read may not be performed while a posted write is
outstanding.  This is considered to be an application error, and the results of doing so are undefined.  The implementation may
choose to catch the error and return MPIDU_SOCK_ERR_INPROGRESS, but it is not required to do so.

If MPIDU_Sock_post_close() is called before the posted read operation completes, the read operation will be terminated and a
MPIDU_SOCK_OP_READ event containing a MPIDU_SOCK_ERR_SOCK_CLOSED error will be generated.  This event will be returned by
MPIDU_Sock_wait() prior to the MPIDU_SOCK_OP_CLOSE event.

Thread safety:
MPIDU_Sock_post_readv() may be called while another thread is attempting to perform an immediate write or post a write operation on
the same sock.  MPIDU_Sock_post_readv() may also be called while another thread is calling or blocking in MPIDU_Sock_wait() on the
same sock set to which the specified sock belongs.

MPIDU_Sock_post_readv() may not be called while another thread is performing an immediate read on the same sock.  This is
considered to be an application error, and the results of doing so are undefined.  The implementation may choose to catch the error
and return MPIDU_SOCK_ERR_INPROGRESS, but it is not required to do so.

Calling MPIDU_Sock_post_readv() during or after the call to MPIDU_Sock_post_close() is consider an application error.  The result
of doing so is undefined.  The application should coordinate the closing of a sock with the activities of other threads to ensure
that one thread is not attempting to post a new operation while another thread is attempting to close the sock.

Module:
Utility-Sock
@*/
int MPIDU_Sock_post_readv(MPIDU_Sock_t sock, MPID_IOV * iov, int iov_n, MPIDU_Sock_progress_update_func_t fn);


/*@
MPIDU_Sock_post_write - request that data be written to a sock

Input Parameters:
+ sock - sock object which the data is to be written
. buf - buffer containing the data
. minlen - minimum number of bytes to write
. maxlen - maximum number of bytes to write
+ upate_fn - application progress aupdate function (may be NULL)

Return value: a MPI error code with a Sock extended error class
+ MPI_SUCCESS - request to write was successfully posted
. MPIDU_SOCK_ERR_INIT - Sock module not initialized
. MPIDU_SOCK_ERR_BAD_SOCK - invalid sock object
. MPIDU_SOCK_ERR_BAD_LEN - length parameters must be greater than zero and maxlen must be greater than minlen
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
. MPIDU_SOCK_ERR_INPROGRESS - this operation overlapped with another like operation already in progress
- MPIDU_SOCK_ERR_FAIL - other error attempting to post write

Events generated:
. MPIDU_SOCK_OP_WRITE

Event errors: a MPI error code with a Sock extended error class
+ MPI_SUCCESS -  successfully established
. MPIDU_SOCK_ERR_BAD_BUF - using the buffer described by buf and maxlen resulted in a memory fault
. MPIDU_SOCK_ERR_SOCK_CLOSED - the sock object was closed locally
. MPIDU_SOCK_ERR_CONN_CLOSED - the connection was closed by the peer
. MPIDU_SOCK_ERR_CONN_FAILED - the connection failed
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
- MPIDU_SOCK_ERR_FAIL - other error completing the write

Notes:
Only one write operation may be posted at a time.  Furthermore, an immediate write may not be performed while a posted write is
outstanding.  This is considered to be an application error, and the results of doing so are undefined.  The implementation may
choose to catch the error and return MPIDU_SOCK_ERR_INPROGRESS, but it is not required to do so.

If MPIDU_Sock_post_close() is called before the posted write operation completes, the write operation will be terminated and a
MPIDU_SOCK_OP_WRITE event containing a MPIDU_SOCK_ERR_SOCK_CLOSED error will be generated.  This event will be returned by
MPIDU_Sock_wait() prior to the MPIDU_SOCK_OP_CLOSE event.

Thread safety:
MPIDU_Sock_post_write() may be called while another thread is attempting to perform an immediate read or post a read operation on
the same sock.  MPIDU_Sock_post_write() may also be called while another thread is calling or blocking in MPIDU_Sock_wait() on the
same sock set to which the specified sock belongs.

MPIDU_Sock_post_write() may not be called while another thread is performing an immediate write on the same sock.  This is
considered to be an application error, and the results of doing so are undefined.  The implementation may choose to catch the error
and return MPIDU_SOCK_ERR_INPROGRESS, but it is not required to do so.

Calling MPIDU_Sock_post_write() during or after the call to MPIDU_Sock_post_close() is consider an application error.  The result
of doing so is undefined.  The application should coordinate the closing of a sock with the activities of other threads to ensure
that one thread is not attempting to post a new operation while another thread is attempting to close the sock.  <BRT> Do we really
need this flexibility?

Module:
Utility-Sock
@*/
int MPIDU_Sock_post_write(MPIDU_Sock_t sock, void * buf, MPIU_Size_t min, MPIU_Size_t max,
			  MPIDU_Sock_progress_update_func_t fn);


/*@
MPIDU_Sock_post_writev - request that a vector of data be written to a sock

Input Parameters:
+ sock - sock object which the data is to be written
. iov - I/O vector describing buffers of data to be written
. iov_n - number of elements in I/O vector (must be less than MPID_IOV_LIMIT)
+ upate_fn - application progress update function (may be NULL)

Return value: a MPI error code with a Sock extended error class
+ MPI_SUCCESS - request to write was successfully posted
. MPIDU_SOCK_ERR_INIT - Sock module not initialized
. MPIDU_SOCK_ERR_BAD_SOCK - invalid sock object
. MPIDU_SOCK_ERR_BAD_LEN - iov_n is out of range
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
. MPIDU_SOCK_ERR_INPROGRESS - this operation overlapped with another like operation already in progress
- MPIDU_SOCK_ERR_FAIL - other error attempting to post write

Events generated:
. MPIDU_SOCK_OP_WRITE

Event errors: a MPI error code with a Sock extended error class
+ MPI_SUCCESS -  successfully established
. MPIDU_SOCK_ERR_BAD_BUF - using the buffer described by iov and iov_n resulted in a memory fault
. MPIDU_SOCK_ERR_SOCK_CLOSED - the sock object was closed locally
. MPIDU_SOCK_ERR_CONN_CLOSED - the connection was closed by the peer
. MPIDU_SOCK_ERR_CONN_FAILED - the connection failed
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
- MPIDU_SOCK_ERR_FAIL - other error completing the write

Notes:
Only one write operation may be posted at a time.  Furthermore, an immediate write may not be performed while a posted write is
outstanding.  This is considered to be an application error, and the results of doing so are undefined.  The implementation may
choose to catch the error and return MPIDU_SOCK_ERR_INPROGRESS, but it is not required to do so.

If MPIDU_Sock_post_close() is called before the posted write operation completes, the write operation will be terminated and a
MPIDU_SOCK_OP_WRITE event containing a MPIDU_SOCK_ERR_SOCK_CLOSED error will be generated.  This event will be returned by
MPIDU_Sock_wait() prior to the MPIDU_SOCK_OP_CLOSE event.

Thread safety:
MPIDU_Sock_post_writev() may be called while another thread is attempting to perform an immediate read or post a read operation on
the same sock.  MPIDU_Sock_post_writev() may also be called while another thread is calling or blocking in MPIDU_Sock_wait() on the
same sock set to which the specified sock belongs.

MPIDU_Sock_post_writev() may not be called while another thread is performing an immediate write on the same sock.  This is
considered to be an application error, and the results of doing so are undefined.  The implementation may choose to catch the error
and return MPIDU_SOCK_ERR_INPROGRESS, but it is not required to do so.

Calling MPIDU_Sock_post_writev() during or after the call to MPIDU_Sock_post_close() is consider an application error.  The result
of doing so is undefined.  The application should coordinate the closing of a sock with the activities of other threads to ensure
that one thread is not attempting to post a new operation while another thread is attempting to close the sock.

Module:
Utility-Sock
@*/
int MPIDU_Sock_post_writev(MPIDU_Sock_t sock, MPID_IOV * iov, int iov_n, MPIDU_Sock_progress_update_func_t fn);


/*@
MPIDU_Sock_wait - wait for an event

Input Parameters:
+ set - sock set upon which to wait for an event
- timeout - timeout in milliseconds (<0 for infinity)

Output Parameter:
. event - pointer to the event structure to be populated

Return value: a MPI error code with a Sock extended error class
+ MPI_SUCCESS - a new event was returned
. MPIDU_SOCK_ERR_INIT - Sock module not initialized
. MPIDU_SOCK_ERR_BAD_SET - invalid sock set object
. MPIDU_SOCK_ERR_TIMEOUT - a timeout occurred
. MPIDU_SOCK_ERR_INTR - the routine was interrupted by a call to MPIDU_Sock_wakeup()
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
- MPIDU_SOCK_ERR_FAIL - other error (are there any?)

Notes:
MPIDU_Sock_wakeup() can be called from another thread to force MPIDU_Sock_wait() to return with a MPIDU_SOCK_ERR_INTR error.
MPIDU_Sock_wakeup() may not be called from within a progress update function or any function directly or indirectly called by a
progress update function.

Thread safety:
New operations may be posted to sock contained in the specified sock set while another thread is calling or blocking in
MPIDU_Sock_wait().  These operations should complete as though they were posted before MPIDU_Sock_wait() was called.

Module:
Utility-Sock
@*/
int MPIDU_Sock_wait(MPIDU_Sock_set_t set, int timeout, MPIDU_Sock_event_t * event);


/*@
MPIDU_Sock_wakeup - wakeup a MPIDU_Sock_wait blocking in another thread

Input Parameter:
. set - sock set upon which to wait for an event

Return value: a MPI error code with a Sock extended error class
+ MPI_SUCCESS - wakeup request successfully processed
. MPIDU_SOCK_ERR_INIT - Sock module not initialized
. MPIDU_SOCK_ERR_BAD_SET - invalid sock set object
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory (is this possible?)
- MPIDU_SOCK_ERR_FAIL - other error (are there any?)

Notes:
This routine forces a MPIDU_Sock_wait() blocking in another thread to wakeup and return a MPIDU_SOCK_ERR_INTR error.
MPIDU_Sock_wakeup() may not be called from within a progress update function or any function directly or indirectly called by a
progress update function.