mpidu_sock.h

fortran并行计算包

The implementation should strive to only wakeup a MPIDU_Sock_wait() that is already blocking; however, it is acceptable (although
undesireable) for it wakeup a MPIDU_Sock_wait() that is called in the future.

Module:
Utility-Sock
@*/
int MPIDU_Sock_wakeup(MPIDU_Sock_set_t set);

/*@
MPIDU_Sock_read - perform an immediate read

Input Parameters:
+ sock - sock object from which data is to be read
. buf - buffer into which the data should be placed
- len - maximum number of bytes to read

Output Parameter:
. num_read - number of bytes actually read

Return value: a MPI error code with a Sock extended error class
+ MPI_SUCCESS - no error encountered during the read operation
. MPIDU_SOCK_ERR_INIT - Sock module not initialized
. MPIDU_SOCK_ERR_BAD_SOCK - invalid sock object
. MPIDU_SOCK_ERR_BAD_BUF - using the buffer described by buf and len resulted in a memory fault
. MPIDU_SOCK_ERR_BAD_LEN - length parameter must be greater than zero
. 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_INPROGRESS - this operation overlapped with another like operation already in progress
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
- MPIDU_SOCK_ERR_FAIL - other error attempting to post read

Notes:

An immediate read may not be performed while a posted read is outstanding 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.

Thread safety:
MPIDU_Sock_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_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.

A immediate read may not be performed if 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_read() during or after the call to MPIDU_Sock_post_close() is consider an application error.  The result of
doing so is undefined, although the implementation may choose to return MPIDU_SOCK_ERR_SOCK_CLOSED if it is able to catch the
error.  The application should coordinate the closing of a sock with the activities of other threads to ensure that one thread is
not attempting to perform an immediate read while another thread is attempting to close the sock.

Module:
Utility-Sock
@*/
int MPIDU_Sock_read(MPIDU_Sock_t sock, void * buf, MPIU_Size_t len, MPIU_Size_t * num_read);


/*@
MPIDU_Sock_readv - perform an immediate vector read

Input Parameters:
+ sock - sock object from which data is to be 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)

Output Parameter:
. num_read - number of bytes actually read

Return value: a MPI error code with a Sock extended error class
+ MPI_SUCCESS - no error encountered during the read operation
. MPIDU_SOCK_ERR_INIT - Sock module not initialized
. MPIDU_SOCK_ERR_BAD_SOCK - invalid sock object
. MPIDU_SOCK_ERR_BAD_BUF - using the buffer described by iov and iov_n resulted in a memory fault
. MPIDU_SOCK_ERR_BAD_LEN - iov_n parameter must be greater than zero and not greater than MPID_IOV_LIMIT
. 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_INPROGRESS - this operation overlapped with another like operation already in progress
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
- MPIDU_SOCK_ERR_FAIL - other error attempting to post read

Notes:

An immediate read may not be performed while a posted read is outstanding 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.

Thread safety:
MPIDU_Sock_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_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.

A immediate read may not be performed if 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_read() during or after the call to MPIDU_Sock_post_close() is consider an application error.  The result of
doing so is undefined, although the implementation may choose to return MPIDU_SOCK_ERR_SOCK_CLOSED if it is able to catch the
error.  The application should coordinate the closing of a sock with the activities of other threads to ensure that one thread is
not attempting to perform an immediate read while another thread is attempting to close the sock.

Module:
Utility-Sock
@*/
int MPIDU_Sock_readv(MPIDU_Sock_t sock, MPID_IOV * iov, int iov_n, MPIU_Size_t * num_read);


/*@
MPIDU_Sock_write - perform an immediate write

Input Parameters:
+ sock - sock object to which data is to be written
. buf - buffer containing the data to be written
- len - maximum number of bytes to written

Output Parameter:
. num_written - actual number of bytes written

Return value: a MPI error code with a Sock extended error class
+ MPI_SUCCESS - no error encountered during the write operation
. MPIDU_SOCK_ERR_INIT - Sock module not initialized
. MPIDU_SOCK_ERR_BAD_SOCK - invalid sock object
. MPIDU_SOCK_ERR_BAD_BUF - using the buffer described by buf and len resulted in a memory fault
. MPIDU_SOCK_ERR_BAD_LEN - length parameter must be greater than zero
. 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_INPROGRESS - this operation overlapped with another like operation already in progress
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
- MPIDU_SOCK_ERR_FAIL - other error attempting to perform the write

Notes:
An immediate write may not be performed while a posted write is outstanding 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.

Thread safety:
MPIDU_Sock_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_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.

A immediate write may not be performed if 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_write() during or after the call to MPIDU_Sock_post_close() is consider to be an application error.  The result
of doing so is undefined, although the implementation may choose to return MPIDU_SOCK_ERR_SOCK_CLOSED if it is able to catch the
error.  The application should coordinate the closing of a sock with the activities of other threads to ensure that one thread is
not attempting to perform an immediate write while another thread is attempting to close the sock.

Module:
Utility-Sock
@*/
int MPIDU_Sock_write(MPIDU_Sock_t sock, void * buf, MPIU_Size_t len, MPIU_Size_t * num_written);


/*@
MPIDU_Sock_writev - perform an immediate vector write

Input Parameters:
+ sock - sock object to which 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)

Output Parameter:
. num_written - actual number of bytes written

Return value: a MPI error code with a Sock extended error class
+ MPI_SUCCESS - no error encountered during the write operation
. MPIDU_SOCK_ERR_INIT - Sock module not initialized
. MPIDU_SOCK_ERR_BAD_SOCK - invalid sock object
. MPIDU_SOCK_ERR_BAD_BUF - using the buffer described by iov and iov_n resulted in a memory fault
. MPIDU_SOCK_ERR_BAD_LEN - iov_n parameter must be greater than zero and not greater than MPID_IOV_LIMIT
. 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_INPROGRESS - this operation overlapped with another like operation already in progress
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
- MPIDU_SOCK_ERR_FAIL - other error attempting to perform the write

Notes:
An immediate write may not be performed while a posted write is outstanding 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.

Thread safety:
MPIDU_Sock_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_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.

A immediate write may not be performed if 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_write() during or after the call to MPIDU_Sock_post_close() is consider to be an application error.  The result
of doing so is undefined, although the implementation may choose to return MPIDU_SOCK_ERR_SOCK_CLOSED if it is able to catch the
error.  The application should coordinate the closing of a sock with the activities of other threads to ensure that one thread is
not attempting to perform an immediate write while another thread is attempting to close the sock.

Module:
Utility-Sock
@*/
int MPIDU_Sock_writev(MPIDU_Sock_t sock, MPID_IOV * iov, int iov_n, MPIU_Size_t * num_written);


/*@
MPIDU_Sock_get_sock_id - get an integer identifier for a sock object

Input Parameter:
. sock - sock object

Return value: an integer that uniquely identifies the sock object

Notes:
The integer is unique relative to all other open sock objects in the local process.  The integer may later be reused for a
different sock once the current object is closed and destroyed.

This function does not return an error code.  Passing in an invalid sock object has undefined results (garbage in, garbage out).

Module:
Utility-Sock
@*/
int MPIDU_Sock_get_sock_id(MPIDU_Sock_t sock);


/*@
MPIDU_Sock_get_sock_set_id - get an integer identifier for a sock set object

Input Parameter:
. sock set - sock set object

Return value: an integer that uniquely identifies the sock set object

Notes:

The integer is unique relative to all other sock set objects currently existing in the local process.  The integer may later be
reused for a different sock set once the current object destroyed.

This function does not return an error code.  Passing in an invalid sock set object has undefined results (garbage in, garbage
out).

Module:
Utility-Sock
@*/
int MPIDU_Sock_get_sock_set_id(MPIDU_Sock_set_t set);


/*@
MPIDU_Sock_get_error_class_string - get a generic error string from an error code

Input Parameter:
+ error - sock error
- length - length of error string

Output Parameter:
. error_string - error string

Return value: a string representation of the sock error

Notes:

The returned string is the generic error message for the supplied error code.

Module:
Utility-Sock
@*/
int MPIDU_Sock_get_error_class_string(int error, char *error_string, int length);


CPLUSPLUS_END

#endif /* !defined(MPIDU_SOCK_H_INCLUDED) */