View figure.
The LAPI provides the following specific functions.
The active message function (LAPI_Amsend) is a non-blocking call that causes the specified active message handler to be invoked and executed in the address space of the target process. Completion of the operation is signaled if counters are specified. Both standard and synchronous behaviors are supported. The LAPI_Amsend function provides two counters (org_cntr and cmpl_cntr) which can be used to provide the two behaviors. The org_cntr increments when the origin buffer can be reused (standard). The cmpl_cntr increments after the completion handler has completed execution (synchronous).
Data transfer functions are non-blocking calls that cause data to be copied from a specified region in the origin address space to the specified region in the target address space (in the case of a LAPI_Put operation) or from a specified region in the target address space to a specified region in the origin address space (in the case of a LAPI_Get operation). Completion of the operation is signaled if counters are specified. Both standard and synchronous operations are supported for PUT. Only synchronous operation is possible in the case of GET. Standard PUT is provided by incrementing the org_cntr when the origin buffer can be reused. Synchronous PUT is provided by incrementing the cmpl_cntr after the data has been written into the target buffer. The LAPI_Getcntr (or LAPI_Waitcntr) function should be used in conjunction with the org_cntr and cmpl_cntr counters to guarantee the respective standard and synchronous behavior of the LAPI PUT operations.
The LAPI vector functions are provided to help you transfer noncontiguous data more efficiently. Without these functions you would have used a series of data transfer functions, one for each contiguous chunk of data, resulting in pipelining overhead, or you would have copied the various chunks of data into a contiguous buffer before using LPI to transfer the data, resulting in copy overhead. |The general I/O vector transfer, generic Amsendv, and the general |strided transfer functions all use the following I/O vector structure:
typedef struct {
lapi_vectype_t vec_type; /* operation code */
uint num_vecs; /* number of vectors */
void **info; /* vector of information */
uint *len; /* vector of lengths */
} lapi_vec_t;
wherevec_type, num_vecs, info, and len are variables to be replaced by the respective values.
The following properties apply in all vector data transfers:
Figure 41 shows the general I/O vector transfer case.
Figure 41. Transfer of noncontiguous data using LAPI general I/O vector transfer
View figure.
In this case, the respective values for the lapi_vec_t structure variables are as follows:
vec_type must be LAPI_GEN_IOVECTOR
num_vecs is the number of vectors in the info and len arrays. The value at the origin can be different from the value at the target.
info is an array that contains buffer addresses representing the starting address for each of the vectors.
len is an array that contains the length in bytes for each vector respectively.
|The num_vecs field at the origin task must be the same as |the num_vecs field at the target task. The length of a |vector at the target must be at least as big as the corresponding vector at |the origin.
|This is a more generalized form of the general I/O vector transfer. |It uses the Amsendv active message function. The |vec_type field of the lapi_vec_t structure must be |LAPI_GEN_GENERIC. There are no restrictions on the num_vecs |field and the lengths of vectors in the general I/O vector transfer in this |case. The effect of the generic vector transfer is to simply transfer a |given number of bytes in noncontiguous buffers specified by the origin vector |structure to another number of bytes in noncontiguous buffers specified by the |target vector structure returned by the header handler of the |Amsendv active message function.
Figure 42 shows the general strided data transfer case.
Figure 42. Transfer of noncontiguous data using LAPI general strided transfer
View figure.
In this case, the respective values for the lapi_vec_t structure variables are as follows:
vec_type must be LAPI_GEN_STRIDED_XFER
num_vecs is the number of vectors in the info array. The value at the origin can be different from the value at the target.
info is an array that contains buffer addresses representing the starting address for each of the vectors. In this case, the array has the following special use entries:
len is not used in this case.
The LAPI_Rmw function is used to synchronize two independent operations such as two processes sharing a common |32-bit data structure. The LAPI_Rmw64 function does |the same for a 64-bit data structure. The operation is performed at the target process and is atomic. The operation takes a variable from the origin and performs one of four selected operations on a variable from the target and replaces the target variable with the results of the operation. The original value of the target variable is returned to the origin. LAPI_Rmw provides four different read-modify-write operations:
Completion is signaled at the origin if the counter is specified.
The following counter functions provide the means for a process to manage the completion state of the LAPI operations.
These functions also provide an efficient means to order the flow of LAPI operations or the use of certain user managed resources (for example, buffers). For example, a series of PUTs to a single target and buffer requires that the contents of the buffer at the target remains in step with the order of execution of the PUTs at the origin. Using the cmpl_cntr counter in the LAPI_Put function in conjunction with the LAPI_Waitcntr function provides the necessary ordering.
LAPI-Fence and LAPI_Gfence operations provide a means to enforce the order of execution of LAPI functions. LAPI functions initiated prior to these fencing operations are guaranteed to complete before LAPI functions initiated after the fencing functions. LAPI_Fence is a local operation which is used to guarantee that all LAPI operations initiated by the local process and the same process thread are complete. LAPI_Gfence is a collective operation involving all processes in the parallel program. LAPI_Gfence provides a barrier operation for the parallel program. Both LAPI_Fence and LAPI_Gfence operations are a data fence that guarantee that the data movement is complete. These are not an operation fence which would need to include active message completion handlers completing at the target.
The LAPI_Probe function is used in polling mode to transfer control to the communication subsystem in order to make progress on arriving messages.
The LAPI_Address_init collective operation allows processes to exchange operand addresses of interest. Such function is required if the processes do not have identical address maps. The LAPI_Address is used by Fortran programs when an address needs to be stored in an array. In Fortran there is no concept of "address" (as there is in the C language) and this function gives that ability to Fortran.
LAPI_Init and LAPI_Term operations are used to initialize and terminate the communication structures required to effect LAPI communications for a specific instance of LAPI. LAPI_Init returns a unique handle which is used to associate a communication channel with the LAPI instance. This handle is subsequently passed as a parameter to each of the other LAPI functions. The LAPI_Term function is used to terminate a specific instance of LAPI.
The LAPI_Init function provides a means for the user of LAPI to register an error handler. This error handler is specified as part of the lapi_info structure parameter which is passed to the LAPI_Init function. The LAPI_Msg_String function provides the means to translate a LAPI call return code value (integer) into a message string.
The LAPI_Qenv function is used to query the state of the LAPI communications subsystem. The LAPI_Senv function allows the programmer to specify the value of some of the LAPI communications subsystem's environment variables. An important value that can be specified is the interrupt state. The interrupt state is set by specifying INTERRUPT_SET as on (for interrupt mode) or off (for polling mode). The default setting for INTERRUPT_SET is on.