Struct ucp_request_param_t

struct ucp_request_param_t

Operation parameters passed to ucp_tag_send_nbx, ucp_tag_send_sync_nbx, ucp_tag_recv_nbx, ucp_put_nbx, ucp_get_nbx, ucp_am_send_nbx and ucp_am_recv_data_nbx.

The structure ucp_request_param_t is used to specify datatype of operation, provide user request in case the external request is used, set completion callback and custom user data passed to this callback.

Example: implementation of function to send contiguous buffer to ep and invoke callback function at operation completion. If the operation completed immediately (status == UCS_OK) then callback is not called.

ucs_status_ptr_t send_data(ucp_ep_h ep, void *buffer, size_t length,
                           ucp_tag_t tag, void *request)
{
    ucp_request_param_t param = {
        .op_attr_mask               = UCP_OP_ATTR_FIELD_CALLBACK |
                                      UCP_OP_ATTR_FIELD_REQUEST,
        .request                    = request,
        .cb.send                    = custom_send_callback_f,
        .user_data                  = pointer_to_user_context_passed_to_cb
    };

    ucs_status_ptr_t status;

    status = ucp_tag_send_nbx(ep, buffer, length, tag, &param);
    if (UCS_PTR_IS_ERR(status)) {
        handle_error(status);
    } else if (status == UCS_OK) {
        // operation is completed
    }

    return status;
}

Public Members

uint32_t op_attr_mask

Mask of valid fields in this structure and operation flags, using bits from ucp_op_attr_t. Fields not specified in this mask will be ignored. Provides ABI compatibility with respect to adding new fields.

void *request

Request handle allocated by the user. There should be at least UCP request size bytes of available space before the request. The size of the UCP request can be obtained by ucp_context_query function.

union ucp_request_param_t cb

Callback function that is invoked whenever the send or receive operation is completed.

ucp_datatype_t datatype

Datatype descriptor for the elements in the buffer. In case the op_attr_mask & UCP_OP_ATTR_FIELD_DATATYPE bit is not set, then use default datatype ucp_dt_make_contig(1)

void *user_data

Pointer to user data passed to callback function.

void *reply_buffer

Reply buffer. Can be used for storing operation result, for example by ucp_atomic_op_nbx.

ucs_memory_type_t memory_type

Memory type of the buffer. see ucs_memory_type_t for possible memory types. An optimization hint to avoid memory type detection for request buffer. If this value is not set (along with its corresponding bit in the op_attr_mask - UCP_OP_ATTR_FIELD_MEMORY_TYPE), then use default UCS_MEMORY_TYPE_UNKNOWN which means the memory type will be detected internally.

union ucp_request_param_t recv_info

Pointer to the information where received data details are stored in case of an immediate completion of receive operation. The user has to provide a pointer to valid memory/variable which will be updated on function return.

ucp_mem_h memh

Memory handle for pre-registered buffer. If the handle is provided, protocols that require registered memory can skip the registration step. As a result, the communication request overhead can be reduced and the request can be completed faster. The memory handle should be obtained by calling ucp_mem_map.

ucp_datatype_t remote_datatype

Remote datatype identifier for SGL operations. When set (along with UCP_OP_ATTR_FIELD_REMOTE_DATATYPE), specifies the datatype of the remote side. Currently only ucp_dt_make_sgl() is supported. When this field is set, remote and remote_count should also be set.

const void *remote

Remote data descriptor. The type is determined by remote_datatype. Used together with remote_datatype and remote_count to specify the remote side of SGL operations. This field is used when UCP_OP_ATTR_FIELD_REMOTE is set in op_attr_mask.

size_t remote_count

Number of elements in the remote descriptor. When set (along with UCP_OP_ATTR_FIELD_REMOTE_COUNT), specifies how many elements the remote side has, independent of the local count parameter. Used together with remote_datatype and remote.

Note

Currently must equal the local count (only N->N mapping is supported).