mpidu_sock.h

fortran并行计算包

The constraints on which file descriptors/handles may be converted to a sock object are defined by the implementation.  The
implementation may return MPIDU_SOCK_ERR_BAD_NATIVE_FD if the descriptor/handle cannot be used with the implementation.  It is
possible, however, that the conversion of an inappropriate descriptor/handle may complete successfully but the sock object may not
function properly.

Thread safety:
The addition of a new sock object to the sock set may occur while other threads are performing operations on the same sock set.
Thread safety of simultaneously operations on the same sock set must be guaranteed by the Sock implementation.
  
@*/
int MPIDU_Sock_native_to_sock(MPIDU_Sock_set_t set, MPIDU_SOCK_NATIVE_FD fd, void * user_ptr, MPIDU_Sock_t * sock);


/*@
MPIDU_Sock_listen - establish a listener sock

Input Parameters:
+ set - sock set to which the listening sock should be added
. user_ptr - user pointer associated with the new sock object
- port - desired port (or zero if a specific port is not desired)

Output Parameters:
+ port - port assigned to the listener
- sock - new listener sock

Return value: a MPI error code with a Sock extended error class
+ MPI_SUCCESS - listener sock successfully established
. MPIDU_SOCK_ERR_INIT - Sock module not initialized
. MPIDU_SOCK_ERR_BAD_SET - invalid sock set
. MPIDU_SOCK_ERR_BAD_PORT - port number is out of range or pointer to port parameter is invalid
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
- MPIDU_SOCK_ERR_FAIL - other failure; listener sock could not be created

Events generated:
. MPIDU_SOCK_OP_ACCEPT - each time a new connection is being formed and needs to be accepted (with MPIDU_Sock_accept())

Event errors:
+ MPI_SUCCESS - new sock waiting to be accepted
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
- MPIDU_SOCK_ERR_FAIL - other failure?

Notes:
While not a post routine, this routine can generate events.  In fact,
unlike the post routine, many MPIDU_SOCK_OP_ACCEPT events can 
be generated from a listener (typically one per incoming connection attempt).

The implementation may generate an event as soon it is notified that a
new connection is forming.  In such an implementation, 
MPIDU_Sock_accept() may be responsible for finalizing the connection.
It is also possible that the connection may fail to 
complete, causing MPIDU_Sock_accept() to be unable to obtain a sock
despite the event notification. 

The environment variable MPICH_PORT_RANGE=min:max may be used to
restrict the ports mpich processes listen on. 

Thread safety:
The addition of the listener sock object to the sock set may occur
while other threads are performing operations on the same sock 
set.  Thread safety of simultaneously operations on the same sock set
must be guaranteed by the Sock implementation. 

Module:
Utility-Sock
@*/
int MPIDU_Sock_listen(MPIDU_Sock_set_t set, void * user_ptr, int * port, MPIDU_Sock_t * sock);


/*@
MPIDU_Sock_accept - obtain the sock object associated with a new connection

Input Parameters:
+ listener_sock - listener sock object from which to obtain the new connection
. set - sock set to which the new sock object should be added
- user_ptr - user pointer associated with the new sock object

Output Parameter:
. sock - sock object for the new connection

Return value: a MPI error code with a Sock extended error class
+ MPI_SUCCESS - new connection successfully established and associated with new sock objecta
. MPIDU_SOCK_ERR_INIT - Sock module not initialized
. MPIDU_SOCK_ERR_NO_NEW_SOCK - no new connection was available
. MPIDU_SOCK_ERR_BAD_SOCK - invalid listener sock or bad pointer to new sock object
. MPIDU_SOCK_ERR_BAD_SET - invalid sock set
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
- MPIDU_SOCK_ERR_FAIL - failed to acquire a new connection

Notes:
In the event of a connection failure, MPIDU_Sock_accept() may fail to acquire and return a new sock despite any
MPIDU_SOCK_OP_ACCEPT event notification.  On the other hand, MPIDU_Sock_accept() may return a sock for which the underlying
connection has already failed.  (The Sock implementation may be unaware of the failure until read/write operations are performed.)

Thread safety:
The addition of the new sock object to the sock set may occur while other threads are performing operations on the same sock set.
Thread safety of simultaneously operations on the same sock set must be guaranteed by the Sock implementation.

MPIDU_Sock_accept() may fail to return a new sock if multiple threads call MPIDU_Sock_accept() and queue of new connections is
depleted.  In this case, MPIDU_SOCK_ERR_NO_SOCK is returned.

Module:
Utility-Sock
@*/
int MPIDU_Sock_accept(MPIDU_Sock_t listener_sock, MPIDU_Sock_set_t set, void * user_ptr, MPIDU_Sock_t * sock);


/*@
MPIDU_Sock_post_connect - request that a new connection be formed

Input Parameters:
+ set - sock set to which the new sock object should be added
. user_ptr - user pointer associated with the new sock object
. host_description - string containing the communication capabilities of the listening host
+ port - port number of listener sock on the listening host

Output Parameter:
. sock - new sock object associated with the connection request

Return value: a MPI error code with a Sock extended error class
+ MPI_SUCCESS - request to form new connection successfully posted
. MPIDU_SOCK_ERR_INIT - Sock module not initialized
. MPIDU_SOCK_ERR_BAD_SET - invalid sock set
. MPIDU_SOCK_ERR_BAD_HOST - host description string is not valid
. MPIDU_SOCK_ERR_BAD_PORT - port number is out of range
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
- MPIDU_SOCK_ERR_FAIL - other failure attempting to post connection request

Events generated:
. MPIDU_SOCK_OP_CONNECT

Event errors: a MPI error code with a Sock extended error class
+ MPI_SUCCESS -  successfully established
. MPIDU_SOCK_ERR_CONN_FAILED - failed to connect to the remote host
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
- MPIDU_SOCK_ERR_FAIL - other error?

<BRT> Any other event errors?  Does the sock/ssm channel require finer granularity?

Notes:
The host description of the listening host is supplied MPIDU_Sock_get_host_description().  The intention is that the description
contain an enumeration of interface information so that the MPIDU_Sock_connect() can try each of the interfaces until it succeeds
in forming a connection.  Having a complete set of interface information also allows a particular interface be used selected by the
user at runtime using the MPICH_NETMASK.  <BRT> The name of the environment variable seems wrong.  Perhaps MPICH_INTERFACE?  We
should ask the Systems group.

Thread safety:
The addition of the new sock object to the sock set may occur while other threads are performing operations on the same sock set.
Thread safety of simultaneously operations on the same sock set must be guaranteed by the Sock implementation.

Module:
Utility-Sock
@*/
int MPIDU_Sock_post_connect(MPIDU_Sock_set_t set, void * user_ptr, char * host_description, int port, MPIDU_Sock_t * sock);

/*S
  MPIDU_Sock_ifaddr_t - Structure to hold an Internet address.

+ len - Length of the address.  4 for IPv4, 16 for IPv6.
- ifaddr - Address bytes (as bytes, not characters)

S*/
typedef struct MPIDU_Sock_ifaddr_t {
    int len, type;
    unsigned char ifaddr[16];
} MPIDU_Sock_ifaddr_t;

/*@ MPIDU_Sock_post_connect_ifaddr - Post a connection given an interface
  address (bytes, not string).

  This is the basic routine.  MPIDU_Sock_post_connect converts the
  host description into the ifaddr and calls this routine.
  @*/
int MPIDU_Sock_post_connect_ifaddr( MPIDU_Sock_set_t sock_set, 
				    void * user_ptr, 
				    MPIDU_Sock_ifaddr_t *ifaddr, int port,
				    MPIDU_Sock_t * sockp);


/*@
MPIDU_Sock_set_user_ptr - change the user pointer associated with a sock object

Input Parameters:
+ sock - sock object
- user_ptr - new user pointer

Return value: a MPI error code with a Sock extended error class
+ MPI_SUCCESS - user pointer successfully updated
. MPIDU_SOCK_ERR_INIT - Sock module not initialized
. MPIDU_SOCK_ERR_BAD_SOCK - invalid sock object
- MPIDU_SOCK_ERR_FAIL - other failure?

Module:
Utility-Sock
@*/
int MPIDU_Sock_set_user_ptr(MPIDU_Sock_t sock, void * user_ptr);


/*@
MPIDU_Sock_post_close - request that an existing connection be closed

Input Parameter:
. sock - sock object to be closed

Return value: a MPI error code with a Sock extended error class
+ MPI_SUCCESS - request to close the connection was successfully posted
. MPIDU_SOCK_ERR_INIT - Sock module not initialized
. MPIDU_SOCK_ERR_BAD_SOCK - invalid sock object or close already posted
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
- MPIDU_SOCK_ERR_FAIL - other failure?

Events generated:
+ MPIDU_SOCK_OP_CLOSE
. MPIDU_SOCK_OP_READ
- MPIDU_SOCK_OP_WRITE

Event errors: a MPI error code with a Sock extended error class
+ MPI_SUCCESS -  successfully established
. MPIDU_SOCK_ERR_NOMEM - unable to allocate required memory
- MPIDU_SOCK_ERR_FAIL - an error occurred closing the sock; sock object is still destroyed

Notes:
If any other operations are posted on the specified sock, they will be terminated.  An appropriate event will be generated for each
terminated operation.  All such events will be delivered by MPIDU_Sock_wait() prior to the delivery of the MPIDU_SOCK_OP_CLOSE
event.

The sock object is destroyed just prior to the MPIDU_SOCK_OP_CLOSE event being returned by MPIDU_Sock_wait().  Any oustanding
references to the sock object held by the application should be considered invalid and not used again.

Thread safety:
MPIDU_Sock_post_close() may be called while another thread is calling or blocking in MPIDU_Sock_wait() specifying the same sock set
to which this sock belongs.  If another thread is blocking MPIDU_Sock_wait() and the close operation causes the sock set to become
empty, then MPIDU_Sock_wait() will return with an error.

Calling any of the immediate or post routines 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 simultaneous calls do not occur.

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


/*E
MPIDU_Sock_progress_update_func_t - progress update callback functions

If a pointer to a function of this type is passed to one of the post read or write functions, the implementation must honor the
following rules:

1) The sock progress engine will call this function when partial data has been read or written for the posted operation.

2) All progress_update calls must complete before completion notification is signalled.  In other words, MPIDU_Sock_wait() will not
return until all progress_update calls have completed.

Notes:
<BRT> We need to define ordering and delivery from multiple threads.  Do the handlers have to be thread safe?  If so, then the
internal progress engine could block on an application routine.

Module:
Utility-Sock
E*/
typedef int (* MPIDU_Sock_progress_update_func_t)(MPIU_Size_t num_bytes, void * user_ptr);


/*@
MPIDU_Sock_post_read - request that data be read from a sock

Input Parameters:
+ sock - sock object from which data is to be read
. buf - buffer into which the data should be placed
. minlen - minimum number of bytes to read
. maxlen - maximum number of bytes to read
+ 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