LAPI_Util Subroutine

Purpose

Serves as a wrapper function for such data gather/scatter operations as registration and reservation, for updating UDP port information, and for obtaining pointers to locking and signaling functions that are associated with a shared LAPI lock.

Library

Availability Library (liblapi_r.a)

C Syntax

#include <lapi.h>
 
int LAPI_Util(hndl, util_cmd)
lapi_handle_t hndl;
lapi_util_t *util_cmd;

FORTRAN Syntax

include 'lapif.h'
 
LAPI_UTIL(hndl, util_cmd, ierror)
INTEGER hndl
TYPE (LAPI_UTIL_T) :: util_cmd
INTEGER ierror

Description

Type of call: Data gather/scatter program (DGSP), UDP port information, and lock sharing utilities

typedef union {
    lapi_util_type_t    Util_type;  
    lapi_reg_dgsp_t     RegDgsp;    
    lapi_dref_dgsp_t    DrefDgsp;   
    lapi_resv_dgsp_t    ResvDgsp;   
    lapi_reg_ddm_t      DdmFunc;    
    lapi_add_udp_port_t Udp;        
    lapi_pack_dgsp_t    PackDgsp;   
    lapi_unpack_dgsp_t  UnpackDgsp;
    lapi_thread_func_t  ThreadFunc;
} lapi_util_t;

LAPI_REGISTER_DGSP

You can use this operation to register a LAPI DGSP that you have created. To register a LAPI DGSP, lapi_dgsp_descr_t idgsp must be passed in. LAPI returns a handle (lapi_dg_handle_t dgsp_handle) to use for all future LAPI calls. The dgsp_handle that is returned by a register operation is identified as a lapi_dg_handle_t type, which is the appropriate type for LAPI_Xfer and LAPI_Util calls that take a DGSP. This returned dgsp_handle is also defined to be castable to a pointer to a lapi_dgsp_descr_t for those situations where the LAPI user requires read-only access to information that is contained in the cached DGSP. The register operation delivers a DGSP to LAPI for use in future message send, receive, pack, and unpack operations. LAPI creates its own copy of the DGSP and protects it by reference count. All internal LAPI operations that depend on a DGSP cached in LAPI ensure the preservation of the DGSP by incrementing the reference count when they begin a dependency on the DGSP and decrementing the count when that dependency ends. A DGSP, once registered, can be used from any LAPI instance. LAPI_Term does not discard any DGSPs.

You can register a DGSP, start one or more LAPI operations using the DGSP, and then unreserve it with no concern about when the LAPI operations that depend on the DGSP will be done using it. See LAPI_RESERVE_DGSP and LAPI_UNRESERVE_DGSP for more information.

In general, the DGSP you create and pass in to the LAPI_REGISTER_DGSP call using the dgsp parameter is discarded after LAPI makes and caches its own copy. Because DGSP creation is complex, user errors may occur, but extensive error checking at data transfer time would hurt performance. When developing code that creates DGSPs, you can invoke extra validation at the point of registration by setting the LAPI_VERIFY_DGSP environment variable. LAPI_Util will return any detected errors. Any errors that exist and are not detected at registration time will cause problems during data transfer. Any errors detected during data transfer will be reported by an asynchronous error handler. A segmentation fault is one common symptom of a faulty DGSP. If multiple DGSPs are in use, the asynchronous error handler will not be able to identify which DGSP caused the error. For more information about asynchronous error handling, see LAPI_Init.

LAPI_RESERVE_DGSP

You can use this operation to reserve a DGSP. This operation is provided because a LAPI client might cache a LAPI DGSP handle for later use. The client needs to ensure the DGSP will not be discarded before the cached handle is used. A DGSP handle, which is defined to be a pointer to a DGSP description that is already cached inside LAPI, is passed to this operation. The DGSP handle is also defined to be a structure pointer, so that client programs can get direct access to information in the DGSP. Unless the client can be certain that the DGSP will not be "unreserved" by another thread while it is being accessed, the client should bracket the access window with its own reserve/unreserve operation. The client is not to modify the cached DGSP, but LAPI has no way to enforce this. The reserve operation increments the user reference count, thus protecting the DGSP until an unreserve operation occurs. This is needed because the thread that placed the reservation will expect to be able to use or examine the cached DGSP until it makes an unreserve call (which decrements the user reference count), even if the unreserve operation that matches the original register operation occurs within this window on some other thread.

LAPI_UNRESERVE_DGSP

You can use this operation to unregister or unreserve a DGSP. This operation decrements the user reference count. If external and internal reference counts are zero, this operation lets LAPI free the DGSP. All operations that decrement a reference count cause LAPI to check to see if the counts have both become 0 and if they have, dispose of the DGSP. Several internal LAPI activities increment and decrement a second reference count. The cached DGSP is disposable only when all activities (internal and external) that depend on it and use reference counting to preserve it have discharged their reference. The DGSP handle is passed to LAPI as a value parameter and LAPI does not nullify the caller's handle. It is your responsibility to not use this handle again because in doing an unreserve operation, you have indicated that you no longer count on the handle remaining valid.

LAPI_REG_DDM_FUNC

You can use this operation to register data distribution manager (DDM) functions. It works in conjunction with the DGSM CONTROL instruction. Primarily, it is used for MPI_Accumulate, but LAPI clients can provide any DDM function. It is also used to establish a callback function for processing data that is being scattered into a user buffer on the destination side.

typedef long ddm_func_t (        /* return number of bytes processed */
        void      *in,           /* pointer to inbound data          */
        void      *inout,        /* pointer to destination space     */
        long      bytes,         /* number of bytes inbound          */
        int       operand,       /* CONTROL operand value            */
        int       operation      /* CONTROL operation value          */
);

A DDM function acts between the arrival of message data and the target buffer. The most common usage is to combine inbound data with data already in the target buffer. For example, if the target buffer is an array of integers and the incoming message consists of integers, the DDM function can be written to add each incoming integer to the value that is already in the buffer. The operand and operation fields of the DDM function allow one DDM function to support a range of operations with the CONTROL instruction by providing the appropriate values for these fields.

See RSCT for AIX 5L™: LAPI Programming Guide for more information about DGSP programming.

LAPI_DGSP_PACK

You can use this operation to gather data to a pack buffer from a user buffer under control of a DGSP. A single buffer may be packed by a series of calls. The caller provides a position value that is initialized to the starting offset within the buffer. Each pack operation adjusts position, so the next pack operation can begin where the previous pack operation ended. In general, a series of pack operations begins with position initialized to 0, but any offset is valid. There is no state carried from one pack operation to the next. Each pack operation starts at the beginning of the DGSP it is passed.

LAPI_DGSP_UNPACK

You can use this operation to scatter data from a packed buffer to a user buffer under control of a DGSP. A single buffer may be unpacked by a series of calls. The caller provides a position value that is initialized to the starting offset within the packed buffer. Each unpack operation adjusts position, so the next unpack operation can begin where the previous unpack operation ended. In general, a series of unpack operations begins with position initialized to 0, but any offset is valid. There is no state carried from one unpack operation to the next. Each unpack operation starts at the beginning of the DGSP it is passed.

LAPI_ADD_UDP_DEST_PORT

You can use this operation to update UDP port information about the destination task. This operation can be used when you have written your own UDP handler (udp_hndlr) and you need to support recovery of failed tasks. You cannot use this operation under the POE runtime environment.

LAPI_GET_THREAD_FUNC

You can use this operation to retrieve various shared locking and signaling functions. Retrieval of these functions is valid only after LAPI is initialized and before LAPI is terminated. You should not call any of these functions after LAPI is terminated.

LAPI uses the pthread library for thread ID management. You can therefore use pthread_self() to get the running thread ID and lapi_mutex_getowner_t to get the thread ID that owns the shared lock. Then, you can use pthread_equal() to see if the two are the same.

Mutex thread functions

LAPI_GET_THREAD_FUNC includes the following mutex thread functions: mutex lock, mutex unlock, mutex try lock, and mutex get owner.

int (*lapi_mutex_lock_t)(lapi_handle_t hndl);

int (*lapi_mutex_unlock_t)(lapi_handle_t hndl);

int (*lapi_mutex_trylock_t)(lapi_handle_t hndl);

int (*lapi_mutex_getowner_t)(lapi_handle_t hndl, pthread_t *tid);

Condition functions

LAPI_GET_THREAD_FUNC includes the following condition functions: condition wait, condition timed wait, condition signal, initialize condition, and destroy condition.

int (*lapi_cond_wait_t)(lapi_handle_t hndl, lapi_cond_t *cond);

int (*lapi_cond_timedwait_t)(lapi_handle_t hndl, 
                             lapi_cond_t *cond, 
                             struct timespec *timeout);

int (*lapi_cond_wait_t)(lapi_handle_t hndl, lapi_cond_t *cond);
typedef int (*lapi_cond_signal_t)(lapi_handle_t hndl, lapi_cond_t *cond);

int (*lapi_cond_init_t)(lapi_handle_t hndl, lapi_cond_t *cond);

int (*lapi_cond_destroy_t)(lapi_handle_t hndl, lapi_cond_t *cond);

Parameters

INPUT

hndl

Specifies the LAPI handle.

INPUT/OUTPUT

util_cmd

Specifies the command type of the utility function.

OUTPUT

ierror

Specifies a FORTRAN return code. This is always the last parameter.

Return Values

LAPI_SUCCESS

Indicates that the function call completed successfully.

LAPI_ERR_DGSP

Indicates that the DGSP that was passed in is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN) or is not a registered DGSP.

LAPI_ERR_DGSP_ATOM

Indicates that the DGSP has an atom_size that is less than 0 or greater than MAX_ATOM_SIZE.

LAPI_ERR_DGSP_BRANCH

Indicates that the DGSP attempted a branch that fell outside of the code array. This is returned only in validation mode.

LAPI_ERR_DGSP_COPY_SZ

Is returned with DGSP validation turned on when MCOPY block < 0 or COPY instruction with bytes < 0. This is returned only in validation mode.

LAPI_ERR_DGSP_FREE

Indicates that LAPI tried to free a DGSP that is not valid or is no longer registered. There should be one LAPI_UNRESERVE_DGSP operation to close the LAPI_REGISTER_DGSP operation and one LAPI_UNRESERVE_DGSP operation for each LAPI_RESERVE_DGSP operation.

LAPI_ERR_DGSP_OPC

Indicates that the DGSP opcode is not valid. This is returned only in validation mode.

LAPI_ERR_DGSP_STACK

Indicates that the DGSP has a greater GOSUB depth than the allocated stack supports. Stack allocation is specified by the dgsp->depth member. This is returned only in validation mode.

LAPI_ERR_HNDL_INVALID

Indicates that the hndl passed in is not valid (not initialized or in terminated state).

LAPI_ERR_MEMORY_EXHAUSTED

Indicates that LAPI is unable to obtain memory from the system.

LAPI_ERR_UDP_PORT_INFO

Indicates that the udp_port information pointer is NULL (in C) or that the value of udp_port is LAPI_ADDR_NULL (in FORTRAN).

LAPI_ERR_UTIL_CMD

Indicates that the command type is not valid.

C Examples

Location

/usr/lib/liblapi_r.a

Related Information

Subroutines: LAPI_Init, LAPI_Xfer