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::[anonymous] 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::[anonymous] 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.