UCP Communication routines

Data Structures
struct	ucp_err_handler
	UCP endpoint error handling context. More...

Typedefs
typedef uint64_t	ucp_tag_t
	UCP Tag Identifier. More...
typedef struct ucp_recv_desc *	ucp_tag_message_h
	UCP Message descriptor. More...
typedef uint64_t	ucp_datatype_t
	UCP Datatype Identifier. More...
typedef void(*	ucp_send_callback_t) (void *request, ucs_status_t status)
	Completion callback for non-blocking sends. More...
typedef void(*	ucp_err_handler_cb_t) (void *arg, ucp_ep_h ep, ucs_status_t status)
	Callback to process peer failure. More...
typedef struct ucp_err_handler	ucp_err_handler_t
	UCP endpoint error handling context. More...
typedef void(*	ucp_stream_recv_callback_t) (void *request, ucs_status_t status, size_t length)
	Completion callback for non-blocking stream oriented receives. More...
typedef void(*	ucp_tag_recv_callback_t) (void *request, ucs_status_t status, ucp_tag_recv_info_t *info)
	Completion callback for non-blocking tag receives. More...

Enumerations
enum	ucp_atomic_post_op_t {   UCP_ATOMIC_POST_OP_ADD, UCP_ATOMIC_POST_OP_AND, UCP_ATOMIC_POST_OP_OR, UCP_ATOMIC_POST_OP_XOR,   UCP_ATOMIC_POST_OP_LAST }
	Atomic operation requested for ucp_atomic_post. More...
enum	ucp_atomic_fetch_op_t {   UCP_ATOMIC_FETCH_OP_FADD, UCP_ATOMIC_FETCH_OP_SWAP, UCP_ATOMIC_FETCH_OP_CSWAP, UCP_ATOMIC_FETCH_OP_FAND,   UCP_ATOMIC_FETCH_OP_FOR, UCP_ATOMIC_FETCH_OP_FXOR, UCP_ATOMIC_FETCH_OP_LAST }
	Atomic operation requested for ucp_atomic_fetch. More...
enum	ucp_stream_recv_flags_t { UCP_STREAM_RECV_FLAG_WAITALL = UCS_BIT(0) }
	Flags to define behavior of ucp_stream_recv_nb function. More...

Functions
ucs_status_ptr_t	ucp_am_send_nb (ucp_ep_h ep, uint16_t id, const void *buffer, size_t count, ucp_datatype_t datatype, ucp_send_callback_t cb, unsigned flags)
	Send Active Message. More...
void	ucp_am_data_release (ucp_worker_h worker, void *data)
	Releases Active Message data. More...
ucs_status_ptr_t	ucp_stream_send_nb (ucp_ep_h ep, const void *buffer, size_t count, ucp_datatype_t datatype, ucp_send_callback_t cb, unsigned flags)
	Non-blocking stream send operation. More...
ucs_status_ptr_t	ucp_tag_send_nb (ucp_ep_h ep, const void *buffer, size_t count, ucp_datatype_t datatype, ucp_tag_t tag, ucp_send_callback_t cb)
	Non-blocking tagged-send operations. More...
ucs_status_t	ucp_tag_send_nbr (ucp_ep_h ep, const void *buffer, size_t count, ucp_datatype_t datatype, ucp_tag_t tag, void *req)
	Non-blocking tagged-send operations with user provided request. More...
ucs_status_ptr_t	ucp_tag_send_sync_nb (ucp_ep_h ep, const void *buffer, size_t count, ucp_datatype_t datatype, ucp_tag_t tag, ucp_send_callback_t cb)
	Non-blocking synchronous tagged-send operation. More...
ucs_status_ptr_t	ucp_stream_recv_nb (ucp_ep_h ep, void *buffer, size_t count, ucp_datatype_t datatype, ucp_stream_recv_callback_t cb, size_t *length, unsigned flags)
	Non-blocking stream receive operation of structured data into a user-supplied buffer. More...
ucs_status_ptr_t	ucp_stream_recv_data_nb (ucp_ep_h ep, size_t *length)
	Non-blocking stream receive operation of unstructured data into a UCP-supplied buffer. More...
ucs_status_ptr_t	ucp_tag_recv_nb (ucp_worker_h worker, void *buffer, size_t count, ucp_datatype_t datatype, ucp_tag_t tag, ucp_tag_t tag_mask, ucp_tag_recv_callback_t cb)
	Non-blocking tagged-receive operation. More...
ucs_status_t	ucp_tag_recv_nbr (ucp_worker_h worker, void *buffer, size_t count, ucp_datatype_t datatype, ucp_tag_t tag, ucp_tag_t tag_mask, void *req)
	Non-blocking tagged-receive operation. More...
ucp_tag_message_h	ucp_tag_probe_nb (ucp_worker_h worker, ucp_tag_t tag, ucp_tag_t tag_mask, int remove, ucp_tag_recv_info_t *info)
	Non-blocking probe and return a message. More...
ucs_status_ptr_t	ucp_tag_msg_recv_nb (ucp_worker_h worker, void *buffer, size_t count, ucp_datatype_t datatype, ucp_tag_message_h message, ucp_tag_recv_callback_t cb)
	Non-blocking receive operation for a probed message. More...
ucs_status_t	ucp_put_nbi (ucp_ep_h ep, const void *buffer, size_t length, uint64_t remote_addr, ucp_rkey_h rkey)
	Non-blocking implicit remote memory put operation. More...
ucs_status_ptr_t	ucp_put_nb (ucp_ep_h ep, const void *buffer, size_t length, uint64_t remote_addr, ucp_rkey_h rkey, ucp_send_callback_t cb)
	Non-blocking remote memory put operation. More...
ucs_status_t	ucp_get_nbi (ucp_ep_h ep, void *buffer, size_t length, uint64_t remote_addr, ucp_rkey_h rkey)
	Non-blocking implicit remote memory get operation. More...
ucs_status_ptr_t	ucp_get_nb (ucp_ep_h ep, void *buffer, size_t length, uint64_t remote_addr, ucp_rkey_h rkey, ucp_send_callback_t cb)
	Non-blocking remote memory get operation. More...
ucs_status_t	ucp_atomic_post (ucp_ep_h ep, ucp_atomic_post_op_t opcode, uint64_t value, size_t op_size, uint64_t remote_addr, ucp_rkey_h rkey)
	Post an atomic memory operation. More...
ucs_status_ptr_t	ucp_atomic_fetch_nb (ucp_ep_h ep, ucp_atomic_fetch_op_t opcode, uint64_t value, void *result, size_t op_size, uint64_t remote_addr, ucp_rkey_h rkey, ucp_send_callback_t cb)
	Post an atomic fetch operation. More...
ucs_status_t	ucp_request_check_status (void *request)
	Check the status of non-blocking request. More...
ucs_status_t	ucp_tag_recv_request_test (void *request, ucp_tag_recv_info_t *info)
	Check the status and currently available state of non-blocking request returned from ucp_tag_recv_nb routine. More...
ucs_status_t	ucp_stream_recv_request_test (void *request, size_t *length_p)
	Check the status and currently available state of non-blocking request returned from ucp_stream_recv_nb routine. More...
void	ucp_request_cancel (ucp_worker_h worker, void *request)
	Cancel an outstanding communications request. More...
void	ucp_stream_data_release (ucp_ep_h ep, void *data)
	Release UCP data buffer returned by ucp_stream_recv_data_nb. More...
void	ucp_request_free (void *request)
	Release a communications request. More...
int	ucp_request_is_completed (void *request)
ucs_status_t	ucp_put (ucp_ep_h ep, const void *buffer, size_t length, uint64_t remote_addr, ucp_rkey_h rkey)
	Blocking remote memory put operation. More...
ucs_status_t	ucp_get (ucp_ep_h ep, void *buffer, size_t length, uint64_t remote_addr, ucp_rkey_h rkey)
	Blocking remote memory get operation. More...
ucs_status_t	ucp_atomic_add32 (ucp_ep_h ep, uint32_t add, uint64_t remote_addr, ucp_rkey_h rkey)
	Blocking atomic add operation for 32 bit integers. More...
ucs_status_t	ucp_atomic_add64 (ucp_ep_h ep, uint64_t add, uint64_t remote_addr, ucp_rkey_h rkey)
	Blocking atomic add operation for 64 bit integers. More...
ucs_status_t	ucp_atomic_fadd32 (ucp_ep_h ep, uint32_t add, uint64_t remote_addr, ucp_rkey_h rkey, uint32_t *result)
	Blocking atomic fetch and add operation for 32 bit integers. More...
ucs_status_t	ucp_atomic_fadd64 (ucp_ep_h ep, uint64_t add, uint64_t remote_addr, ucp_rkey_h rkey, uint64_t *result)
	Blocking atomic fetch and add operation for 64 bit integers. More...
ucs_status_t	ucp_atomic_swap32 (ucp_ep_h ep, uint32_t swap, uint64_t remote_addr, ucp_rkey_h rkey, uint32_t *result)
	Blocking atomic swap operation for 32 bit values. More...
ucs_status_t	ucp_atomic_swap64 (ucp_ep_h ep, uint64_t swap, uint64_t remote_addr, ucp_rkey_h rkey, uint64_t *result)
	Blocking atomic swap operation for 64 bit values. More...
ucs_status_t	ucp_atomic_cswap32 (ucp_ep_h ep, uint32_t compare, uint32_t swap, uint64_t remote_addr, ucp_rkey_h rkey, uint32_t *result)
	Blocking atomic conditional swap (cswap) operation for 32 bit values. More...
ucs_status_t	ucp_atomic_cswap64 (ucp_ep_h ep, uint64_t compare, uint64_t swap, uint64_t remote_addr, ucp_rkey_h rkey, uint64_t *result)
	Blocking atomic conditional swap (cswap) operation for 64 bit values. More...

Detailed Description

UCP Communication routines

---

Data Structure Documentation

ucp_err_handler

struct ucp_err_handler

This structure should be initialized in ucp_ep_params_t to handle peer failure

Data Fields
ucp_err_handler_cb_t	cb	Error handler callback, if NULL, will not be called.
void *	arg	User defined argument associated with an endpoint, it will be overridden by ucp_ep_params_t::user_data if both are set.

Typedef Documentation

ucp_tag_t

typedef uint64_t ucp_tag_t

UCP tag identifier is a 64bit object used for message identification. UCP tag send and receive operations use the object for an implementation tag matching semantics (derivative of MPI tag matching semantics).

ucp_tag_message_h

typedef struct ucp_recv_desc* ucp_tag_message_h

UCP Message descriptor is an opaque handle for a message returned by ucp_tag_probe_nb. This handle can be passed to ucp_tag_msg_recv_nb in order to receive the message data to a specific buffer.

ucp_datatype_t

typedef uint64_t ucp_datatype_t

UCP datatype identifier is a 64bit object used for datatype identification. Predefined UCP identifiers are defined by ucp_dt_type.

ucp_send_callback_t

typedef void(* ucp_send_callback_t) (void *request, ucs_status_t status)

This callback routine is invoked whenever the send operation is completed. It is important to note that the call-back is only invoked in a case when the operation cannot be completed in place.

Parameters

[in]	request	The completed send request.
[in]	status	Completion status. If the send operation was completed successfully UCS_OK is returned. If send operation was canceled UCS_ERR_CANCELED is returned. Otherwise, an error status is returned.

ucp_err_handler_cb_t

typedef void(* ucp_err_handler_cb_t) (void *arg, ucp_ep_h ep, ucs_status_t status)

This callback routine is invoked when transport level error detected.

Parameters

[in]	arg	User argument to be passed to the callback.
[in]	ep	Endpoint to handle transport level error. Upon return from the callback, this ep is no longer usable and all subsequent operations on this ep will fail with the error code passed in status.
[in]	status	error status.

ucp_err_handler_t

typedef struct ucp_err_handler ucp_err_handler_t

This structure should be initialized in ucp_ep_params_t to handle peer failure

ucp_stream_recv_callback_t

typedef void(* ucp_stream_recv_callback_t) (void *request, ucs_status_t status, size_t length)

This callback routine is invoked whenever the receive operation is completed and the data is ready in the receive buffer.

Parameters

[in]	request	The completed receive request.
[in]	status	Completion status. If the send operation was completed successfully UCS_OK is returned. Otherwise, an error status is returned.
[in]	length	The size of the received data in bytes, always boundary of base datatype size. The value is valid only if the status is UCS_OK.

ucp_tag_recv_callback_t

typedef void(* ucp_tag_recv_callback_t) (void *request, ucs_status_t status, ucp_tag_recv_info_t *info)

This callback routine is invoked whenever the receive operation is completed and the data is ready in the receive buffer.

Parameters

[in]	request	The completed receive request.
[in]	status	Completion status. If the send operation was completed successfully UCS_OK is returned. If send operation was canceled UCS_ERR_CANCELED is returned. If the data can not fit into the receive buffer the UCS_ERR_MESSAGE_TRUNCATED error code is returned. Otherwise, an error status is returned.
[in]	info	Completion information The info descriptor is Valid only if the status is UCS_OK.

Enumeration Type Documentation

ucp_atomic_post_op_t

enum ucp_atomic_post_op_t

This enumeration defines which atomic memory operation should be performed by the ucp_atomic_post family of fuctions. All of these are non-fetching atomics and will not result in a request handle.

Enumerator
UCP_ATOMIC_POST_OP_ADD	Atomic add
UCP_ATOMIC_POST_OP_AND	Atomic and
UCP_ATOMIC_POST_OP_OR	Atomic or
UCP_ATOMIC_POST_OP_XOR	Atomic xor
UCP_ATOMIC_POST_OP_LAST

ucp_atomic_fetch_op_t

enum ucp_atomic_fetch_op_t

This enumeration defines which atomic memory operation should be performed by the ucp_atomic_fetch family of functions. All of these functions will fetch data from the remote node.

Enumerator
UCP_ATOMIC_FETCH_OP_FADD	Atomic Fetch and add
UCP_ATOMIC_FETCH_OP_SWAP	Atomic swap
UCP_ATOMIC_FETCH_OP_CSWAP	Atomic conditional swap
UCP_ATOMIC_FETCH_OP_FAND	Atomic Fetch and and
UCP_ATOMIC_FETCH_OP_FOR	Atomic Fetch and or
UCP_ATOMIC_FETCH_OP_FXOR	Atomic Fetch and xor
UCP_ATOMIC_FETCH_OP_LAST

ucp_stream_recv_flags_t

enum ucp_stream_recv_flags_t

This enumeration defines behavior of ucp_stream_recv_nb function.

Enumerator
UCP_STREAM_RECV_FLAG_WAITALL	This flag requests that operation will not be completed untill all amout of requested data is received and placed in the user buffer.

Function Documentation

ucp_am_send_nb()

ucs_status_ptr_t ucp_am_send_nb	(	ucp_ep_h	ep,
		uint16_t	id,
		const void *	buffer,
		size_t	count,
		ucp_datatype_t	datatype,
		ucp_send_callback_t	cb,
		unsigned	flags
	)

This routine sends an Active Message to an ep. It does not support CUDA memory.

Parameters

[in]	ep	UCP endpoint where the Active Message will be run.
[in]	id	Active Message id. Specifies which registered callback to run.
[in]	buffer	Pointer to the data to be sent to the target node of the Active Message.
[in]	count	Number of elements to send.
[in]	datatype	Datatype descriptor for the elements in the buffer.
[in]	cb	Callback that is invoked upon completion of the data transfer if it is not completed immediately.
[in]	flags	For Future use.

Returns

NULL Active Message was sent immediately.

UCS_PTR_IS_ERR(_ptr) Error sending Active Message.

otherwise Pointer to request, and Active Message is known to be completed after cb is run.

ucp_am_data_release()

void ucp_am_data_release	(	ucp_worker_h	worker,
		void *	data
	)

This routine releases data that persisted through an Active Message callback because that callback returned UCS_INPROGRESS.

Parameters

[in]	worker	Worker which received the Active Message.
[in]	data	Pointer to data that was passed into the Active Message callback as the data parameter.

ucp_stream_send_nb()

ucs_status_ptr_t ucp_stream_send_nb	(	ucp_ep_h	ep,
		const void *	buffer,
		size_t	count,
		ucp_datatype_t	datatype,
		ucp_send_callback_t	cb,
		unsigned	flags
	)

This routine sends data that is described by the local address buffer, size count, and datatype object to the destination endpoint ep. The routine is non-blocking and therefore returns immediately, however the actual send operation may be delayed. The send operation is considered completed when it is safe to reuse the source buffer. If the send operation is completed immediately the routine returns UCS_OK and the call-back function cb is not invoked. If the operation is not completed immediately and no error reported, then the UCP library will schedule invocation of the call-back cb upon completion of the send operation. In other words, the completion of the operation will be signaled either by the return code or by the call-back.

Note

The user should not modify any part of the buffer after this operation is called, until the operation completes.

Parameters

[in]	ep	Destination endpoint handle.
[in]	buffer	Pointer to the message buffer (payload).
[in]	count	Number of elements to send.
[in]	datatype	Datatype descriptor for the elements in the buffer.
[in]	cb	Callback function that is invoked whenever the send operation is completed. It is important to note that the call-back is only invoked in a case when the operation cannot be completed in place.
[in]	flags	Reserved for future use.

Returns

NULL - The send operation was completed immediately.

UCS_PTR_IS_ERR(_ptr) - The send operation failed.

otherwise - Operation was scheduled for send and can be completed in any point in time. The request handle is returned to the application in order to track progress of the message. The application is responsible for releasing the handle using ucp_request_free routine.

ucp_tag_send_nb()

ucs_status_ptr_t ucp_tag_send_nb	(	ucp_ep_h	ep,
		const void *	buffer,
		size_t	count,
		ucp_datatype_t	datatype,
		ucp_tag_t	tag,
		ucp_send_callback_t	cb
	)

This routine sends a messages that is described by the local address buffer, size count, and datatype object to the destination endpoint ep. Each message is associated with a tag value that is used for message matching on the receiver. The routine is non-blocking and therefore returns immediately, however the actual send operation may be delayed. The send operation is considered completed when it is safe to reuse the source buffer. If the send operation is completed immediately the routine return UCS_OK and the call-back function cb is not invoked. If the operation is not completed immediately and no error reported then the UCP library will schedule to invoke the call-back cb whenever the send operation will be completed. In other words, the completion of a message can be signaled by the return code or the call-back.

Note

The user should not modify any part of the buffer after this operation is called, until the operation completes.

Parameters

[in]	ep	Destination endpoint handle.
[in]	buffer	Pointer to the message buffer (payload).
[in]	count	Number of elements to send
[in]	datatype	Datatype descriptor for the elements in the buffer.
[in]	tag	Message tag.
[in]	cb	Callback function that is invoked whenever the send operation is completed. It is important to note that the call-back is only invoked in a case when the operation cannot be completed in place.

Returns

NULL - The send operation was completed immediately.

UCS_PTR_IS_ERR(_ptr) - The send operation failed.

otherwise - Operation was scheduled for send and can be completed in any point in time. The request handle is returned to the application in order to track progress of the message. The application is responsible for releasing the handle using ucp_request_free() routine.

Examples

ucp_hello_world.c.

ucp_tag_send_nbr()

ucs_status_t ucp_tag_send_nbr	(	ucp_ep_h	ep,
		const void *	buffer,
		size_t	count,
		ucp_datatype_t	datatype,
		ucp_tag_t	tag,
		void *	req
	)

This routine provides a convenient and efficient way to implement a blocking send pattern. It also completes requests faster than ucp_tag_send_nb() because:

• it always uses uct_ep_am_bcopy() to send data up to the rendezvous threshold.
• its rendezvous threshold is higher than the one used by the ucp_tag_send_nb(). The threshold is controlled by the UCX_SEND_NBR_RNDV_THRESH environment variable.
• its request handling is simpler. There is no callback and no need to allocate and free requests. In fact request can be allocated by caller on the stack.

This routine sends a messages that is described by the local address buffer, size count, and datatype object to the destination endpoint ep. Each message is associated with a tag value that is used for message matching on the receiver.

The routine is non-blocking and therefore returns immediately, however the actual send operation may be delayed. The send operation is considered completed when it is safe to reuse the source buffer. If the send operation is completed immediately the routine returns UCS_OK.

If the operation is not completed immediately and no error reported then the UCP library will fill a user provided req and return UCS_INPROGRESS status. In order to monitor completion of the operation ucp_request_check_status() should be used.

Following pseudo code implements a blocking send function:

MPI_send(...)
{
    char *request;
    ucs_status_t status;

    // allocate request on the stack
    // ucp_context_query() was used to get ucp_request_size
    request = alloca(ucp_request_size);

    // note: make sure that there is enough memory before the
    // request handle
    status = ucp_tag_send_nbr(ep, ..., request + ucp_request_size);
    if (status != UCS_INPROGRESS) {
        return status;
    }

    do {
        ucp_worker_progress(worker);
        status = ucp_request_check_status(request + ucp_request_size);
    } while (status == UCS_INPROGRESS);

    return status;
}

Note

The user should not modify any part of the buffer after this operation is called, until the operation completes.

Parameters

[in]	ep	Destination endpoint handle.
[in]	buffer	Pointer to the message buffer (payload).
[in]	count	Number of elements to send
[in]	datatype	Datatype descriptor for the elements in the buffer.
[in]	tag	Message tag.
[in]	req	Request handle allocated by the user. There should be at least UCP request size bytes of available space before the req. The size of UCP request can be obtained by ucp_context_query function.

Returns

UCS_OK - The send operation was completed immediately.

UCS_INPROGRESS - The send was not completed and is in progress. ucp_request_check_status() should be used to monitor req status.

Error code as defined by ucs_status_t

ucp_tag_send_sync_nb()

ucs_status_ptr_t ucp_tag_send_sync_nb	(	ucp_ep_h	ep,
		const void *	buffer,
		size_t	count,
		ucp_datatype_t	datatype,
		ucp_tag_t	tag,
		ucp_send_callback_t	cb
	)

Same as ucp_tag_send_nb, except the request completes only after there is a remote tag match on the message (which does not always mean the remote receive has been completed). This function never completes "in-place", and always returns a request handle.

Note

The user should not modify any part of the buffer after this operation is called, until the operation completes.

Returns UCS_ERR_UNSUPPORTED if UCP_ERR_HANDLING_MODE_PEER is enabled. This is a temporary implementation-related constraint that will be addressed in future releases.

Parameters

[in]	ep	Destination endpoint handle.
[in]	buffer	Pointer to the message buffer (payload).
[in]	count	Number of elements to send
[in]	datatype	Datatype descriptor for the elements in the buffer.
[in]	tag	Message tag.
[in]	cb	Callback function that is invoked whenever the send operation is completed.

Returns

UCS_PTR_IS_ERR(_ptr) - The send operation failed.

otherwise - Operation was scheduled for send and can be completed in any point in time. The request handle is returned to the application in order to track progress of the message. The application is responsible for releasing the handle using ucp_request_free() routine.

ucp_stream_recv_nb()

ucs_status_ptr_t ucp_stream_recv_nb	(	ucp_ep_h	ep,
		void *	buffer,
		size_t	count,
		ucp_datatype_t	datatype,
		ucp_stream_recv_callback_t	cb,
		size_t *	length,
		unsigned	flags
	)

This routine receives data that is described by the local address buffer, size count, and datatype object on the endpoint ep. The routine is non-blocking and therefore returns immediately. The receive operation is considered complete when the message is delivered to the buffer. If data is not immediately available, the operation will be scheduled for receive and a request handle will be returned. In order to notify the application about completion of a scheduled receive operation, the UCP library will invoke the call-back cb when data is in the receive buffer and ready for application access. If the receive operation cannot be started, the routine returns an error.

Parameters

[in]	ep	UCP endpoint that is used for the receive operation.
[in]	buffer	Pointer to the buffer to receive the data to.
[in]	count	Number of elements to receive into buffer.
[in]	datatype	Datatype descriptor for the elements in the buffer.
[in]	cb	Callback function that is invoked whenever the receive operation is completed and the data is ready in the receive buffer. It is important to note that the call-back is only invoked in a case when the operation cannot be completed immediately.
[out]	length	Size of the received data in bytes. The value is valid only if return code is UCS_OK.

Note

The amount of data received, in bytes, is always an integral multiple of the datatype size.

Parameters

[in]

flags

Flags defined in ucp_stream_recv_flags_t.

Returns

NULL - The receive operation was completed immediately.

UCS_PTR_IS_ERR(_ptr) - The receive operation failed.

otherwise - Operation was scheduled for receive. A request handle is returned to the application in order to track progress of the operation. The application is responsible for releasing the handle by calling the ucp_request_free routine.

ucp_stream_recv_data_nb()

ucs_status_ptr_t ucp_stream_recv_data_nb	(	ucp_ep_h	ep,
		size_t *	length
	)

This routine receives any available data from endpoint ep. Unlike ucp_stream_recv_nb, the returned data is unstructured and is treated as an array of bytes. If data is immediately available, UCS_STATUS_PTR(_ptr) is returned as a pointer to the data, and length is set to the size of the returned data buffer. The routine is non-blocking and therefore returns immediately.

Parameters

[in]	ep	UCP endpoint that is used for the receive operation.
[out]	length	Length of received data.

Returns

NULL - No received data available on the ep.

UCS_PTR_IS_ERR(_ptr) - the receive operation failed and UCS_PTR_STATUS(_ptr) indicates an error.

otherwise - The pointer to the data UCS_STATUS_PTR(_ptr) is returned to the application. After the data is processed, the application is responsible for releasing the data buffer by calling the ucp_stream_data_release routine.

Note

This function returns packed data (equivalent to ucp_dt_make_contig(1)).

This function returns a pointer to a UCP-supplied buffer, whereas ucp_stream_recv_nb places the data into a user-provided buffer. In some cases, receiving data directly into a UCP-supplied buffer can be more optimal, for example by processing the incoming data in-place and thus avoiding extra memory copy operations.

ucp_tag_recv_nb()

ucs_status_ptr_t ucp_tag_recv_nb	(	ucp_worker_h	worker,
		void *	buffer,
		size_t	count,
		ucp_datatype_t	datatype,
		ucp_tag_t	tag,
		ucp_tag_t	tag_mask,
		ucp_tag_recv_callback_t	cb
	)

This routine receives a messages that is described by the local address buffer, size count, and datatype object on the worker. The tag value of the receive message has to match the tag and tag_mask values, where the tag_mask indicates what bits of the tag have to be matched. The routine is a non-blocking and therefore returns immediately. The receive operation is considered completed when the message is delivered to the buffer. In order to notify the application about completion of the receive operation the UCP library will invoke the call-back cb when the received message is in the receive buffer and ready for application access. If the receive operation cannot be stated the routine returns an error.

Note

This routine cannot return UCS_OK. It always returns a request handle or an error.

Parameters

[in]	worker	UCP worker that is used for the receive operation.
[in]	buffer	Pointer to the buffer to receive the data to.
[in]	count	Number of elements to receive
[in]	datatype	Datatype descriptor for the elements in the buffer.
[in]	tag	Message tag to expect.
[in]	tag_mask	Bit mask that indicates the bits that are used for the matching of the incoming tag against the expected tag.
[in]	cb	Callback function that is invoked whenever the receive operation is completed and the data is ready in the receive buffer.

Returns

UCS_PTR_IS_ERR(_ptr) - The receive operation failed.

otherwise - Operation was scheduled for receive. The request handle is returned to the application in order to track progress of the operation. The application is responsible for releasing the handle using ucp_request_free() routine.

ucp_tag_recv_nbr()

ucs_status_t ucp_tag_recv_nbr	(	ucp_worker_h	worker,
		void *	buffer,
		size_t	count,
		ucp_datatype_t	datatype,
		ucp_tag_t	tag,
		ucp_tag_t	tag_mask,
		void *	req
	)

This routine receives a message that is described by the local address buffer, size count, and datatype object on the worker. The tag value of the receive message has to match the tag and tag_mask values, where the tag_mask indicates what bits of the tag have to be matched. The routine is a non-blocking and therefore returns immediately. The receive operation is considered completed when the message is delivered to the buffer. In order to monitor completion of the operation ucp_request_check_status or ucp_tag_recv_request_test should be used.

Parameters

[in]	worker	UCP worker that is used for the receive operation.
[in]	buffer	Pointer to the buffer to receive the data to.
[in]	count	Number of elements to receive
[in]	datatype	Datatype descriptor for the elements in the buffer.
[in]	tag	Message tag to expect.
[in]	tag_mask	Bit mask that indicates the bits that are used for the matching of the incoming tag against the expected tag.
[in]	req	Request handle allocated by the user. There should be at least UCP request size bytes of available space before the req. The size of UCP request can be obtained by ucp_context_query function.

Returns

Error code as defined by ucs_status_t

ucp_tag_probe_nb()

ucp_tag_message_h ucp_tag_probe_nb	(	ucp_worker_h	worker,
		ucp_tag_t	tag,
		ucp_tag_t	tag_mask,
		int	remove,
		ucp_tag_recv_info_t *	info
	)

This routine probes (checks) if a messages described by the tag and tag_mask was received (fully or partially) on the worker. The tag value of the received message has to match the tag and tag_mask values, where the tag_mask indicates what bits of the tag have to be matched. The function returns immediately and if the message is matched it returns a handle for the message.

Parameters

[in]	worker	UCP worker that is used for the probe operation.
[in]	tag	Message tag to probe for.
[in]	tag_mask	Bit mask that indicates the bits that are used for the matching of the incoming tag against the expected tag.
[in]	remove	The flag indicates if the matched message has to be removed from UCP library. If true (1), the message handle is removed from the UCP library and the application is responsible to call ucp_tag_msg_recv_nb() in order to receive the data and release the resources associated with the message handle. If false (0), the return value is merely an indication to whether a matching message is present, and it cannot be used in any other way, and in particular it cannot be passed to ucp_tag_msg_recv_nb().
[out]	info	If the matching message is found the descriptor is filled with the details about the message.

Returns

NULL - No match found.

Message handle (not NULL) - If message is matched the message handle is returned.

Note

This function does not advance the communication state of the network. If this routine is used in busy-poll mode, need to make sure ucp_worker_progress() is called periodically to extract messages from the transport.

Examples

ucp_hello_world.c.

ucp_tag_msg_recv_nb()

ucs_status_ptr_t ucp_tag_msg_recv_nb	(	ucp_worker_h	worker,
		void *	buffer,
		size_t	count,
		ucp_datatype_t	datatype,
		ucp_tag_message_h	message,
		ucp_tag_recv_callback_t	cb
	)

This routine receives a messages that is described by the local address buffer, size count, message handle, and datatype object on the worker. The message handle can be obtain by calling the ucp_tag_probe_nb() routine. ucp_tag_msg_recv_nb() routine is a non-blocking and therefore returns immediately. The receive operation is considered completed when the message is delivered to the buffer. In order to notify the application about completion of the receive operation the UCP library will invoke the call-back cb when the received message is in the receive buffer and ready for application access. If the receive operation cannot be stated the routine returns an error.

Parameters

[in]	worker	UCP worker that is used for the receive operation.
[in]	buffer	Pointer to the buffer to receive the data to.
[in]	count	Number of elements to receive
[in]	datatype	Datatype descriptor for the elements in the buffer.
[in]	message	Message handle.
[in]	cb	Callback function that is invoked whenever the receive operation is completed and the data is ready in the receive buffer.

Returns

UCS_PTR_IS_ERR(_ptr) - The receive operation failed.

otherwise - Operation was scheduled for receive. The request handle is returned to the application in order to track progress of the operation. The application is responsible for releasing the handle using ucp_request_free() routine.

Examples

ucp_hello_world.c.

ucp_put_nbi()

ucs_status_t ucp_put_nbi	(	ucp_ep_h	ep,
		const void *	buffer,
		size_t	length,
		uint64_t	remote_addr,
		ucp_rkey_h	rkey
	)

This routine initiates a storage of contiguous block of data that is described by the local address buffer in the remote contiguous memory region described by remote_addr address and the memoryhandle" rkey. The routine returns immediately and does not guarantee re-usability of the source address buffer. If the operation is completed immediately the routine return UCS_OK, otherwise UCS_INPROGRESS or an error is returned to user.

Note

A user can use ucp_worker_flush_nb() in order to guarantee re-usability of the source address buffer.

Parameters

[in]	ep	Remote endpoint handle.
[in]	buffer	Pointer to the local source address.
[in]	length	Length of the data (in bytes) stored under the source address.
[in]	remote_addr	Pointer to the destination remote memory address to write to.
[in]	rkey	Remote memory key associated with the remote memory address.

Returns

Error code as defined by ucs_status_t

ucp_put_nb()

ucs_status_ptr_t ucp_put_nb	(	ucp_ep_h	ep,
		const void *	buffer,
		size_t	length,
		uint64_t	remote_addr,
		ucp_rkey_h	rkey,
		ucp_send_callback_t	cb
	)

This routine initiates a storage of contiguous block of data that is described by the local address buffer in the remote contiguous memory region described by remote_addr address and the memoryhandle" rkey. The routine returns immediately and does not guarantee re-usability of the source address buffer. If the operation is completed immediately the routine return UCS_OK, otherwise UCS_INPROGRESS or an error is returned to user. If the put operation completes immediately, the routine returns UCS_OK and the call-back routine cb is not invoked. If the operation is not completed immediately and no error is reported, then the UCP library will schedule invocation of the call-back routine cb upon completion of the put operation. In other words, the completion of a put operation can be signaled by the return code or execution of the call-back.

Note

A user can use ucp_worker_flush_nb() in order to guarantee re-usability of the source address buffer.

Parameters

[in]	ep	Remote endpoint handle.
[in]	buffer	Pointer to the local source address.
[in]	length	Length of the data (in bytes) stored under the source address.
[in]	remote_addr	Pointer to the destination remote memory address to write to.
[in]	rkey	Remote memory key associated with the remote memory address.
[in]	cb	Call-back function that is invoked whenever the put operation is completed and the local buffer can be modified. Does not guarantee remote completion.

Returns

NULL - The operation was completed immediately.

UCS_PTR_IS_ERR(_ptr) - The operation failed.

otherwise - Operation was scheduled and can be completed at any point in time. The request handle is returned to the application in order to track progress of the operation. The application is responsible for releasing the handle using ucp_request_free() routine.

ucp_get_nbi()

ucs_status_t ucp_get_nbi	(	ucp_ep_h	ep,
		void *	buffer,
		size_t	length,
		uint64_t	remote_addr,
		ucp_rkey_h	rkey
	)

This routine initiate a load of contiguous block of data that is described by the remote memory address remote_addr and the memory handle rkey in the local contiguous memory region described by buffer address. The routine returns immediately and does not guarantee that remote data is loaded and stored under the local address buffer.

Note

A user can use ucp_worker_flush_nb() in order guarantee that remote data is loaded and stored under the local address buffer.

Parameters

[in]	ep	Remote endpoint handle.
[in]	buffer	Pointer to the local destination address.
[in]	length	Length of the data (in bytes) stored under the destination address.
[in]	remote_addr	Pointer to the source remote memory address to read from.
[in]	rkey	Remote memory key associated with the remote memory address.

Returns

Error code as defined by ucs_status_t

ucp_get_nb()

ucs_status_ptr_t ucp_get_nb	(	ucp_ep_h	ep,
		void *	buffer,
		size_t	length,
		uint64_t	remote_addr,
		ucp_rkey_h	rkey,
		ucp_send_callback_t	cb
	)

This routine initiates a load of a contiguous block of data that is described by the remote memory address remote_addr and the memory handle rkey in the local contiguous memory region described by buffer address. The routine returns immediately and does not guarantee that remote data is loaded and stored under the local address buffer. If the operation is completed immediately the routine return UCS_OK, otherwise UCS_INPROGRESS or an error is returned to user. If the get operation completes immediately, the routine returns UCS_OK and the call-back routine cb is not invoked. If the operation is not completed immediately and no error is reported, then the UCP library will schedule invocation of the call-back routine cb upon completion of the get operation. In other words, the completion of a get operation can be signaled by the return code or execution of the call-back.

Note

A user can use ucp_worker_flush_nb() in order to guarantee re-usability of the source address buffer.

Parameters

[in]	ep	Remote endpoint handle.
[in]	buffer	Pointer to the local destination address.
[in]	length	Length of the data (in bytes) stored under the destination address.
[in]	remote_addr	Pointer to the source remote memory address to read from.
[in]	rkey	Remote memory key associated with the remote memory address.
[in]	cb	Call-back function that is invoked whenever the get operation is completed and the data is visible to the local process.

Returns

NULL - The operation was completed immediately.

UCS_PTR_IS_ERR(_ptr) - The operation failed.

otherwise - Operation was scheduled and can be completed at any point in time. The request handle is returned to the application in order to track progress of the operation. The application is responsible for releasing the handle using ucp_request_free() routine.

ucp_atomic_post()

ucs_status_t ucp_atomic_post	(	ucp_ep_h	ep,
		ucp_atomic_post_op_t	opcode,
		uint64_t	value,
		size_t	op_size,
		uint64_t	remote_addr,
		ucp_rkey_h	rkey
	)

This routine posts an atomic memory operation to a remote value. The remote value is described by the combination of the remote memory address remote_addr and the remote memory handle rkey. Return from the function does not guarantee completion. A user must call ucp_ep_flush_nb or ucp_worker_flush_nb to guarantee that the remote value has been updated.

Parameters

[in]	ep	UCP endpoint.
[in]	opcode	One of ucp_atomic_post_op_t.
[in]	value	Source operand for the atomic operation.
[in]	op_size	Size of value in bytes
[in]	remote_addr	Remote address to operate on.
[in]	rkey	Remote key handle for the remote memory address.

Returns

Error code as defined by ucs_status_t

ucp_atomic_fetch_nb()

ucs_status_ptr_t ucp_atomic_fetch_nb	(	ucp_ep_h	ep,
		ucp_atomic_fetch_op_t	opcode,
		uint64_t	value,
		void *	result,
		size_t	op_size,
		uint64_t	remote_addr,
		ucp_rkey_h	rkey,
		ucp_send_callback_t	cb
	)

This routine will post an atomic fetch operation to remote memory. The remote value is described by the combination of the remote memory address remote_addr and the remote memory handle rkey. The routine is non-blocking and therefore returns immediately. However the actual atomic operation may be delayed. The atomic operation is not considered complete until the values in remote and local memory are completed. If the atomic operation completes immediately, the routine returns UCS_OK and the call-back routine cb is not invoked. If the operation is not completed immediately and no error is reported, then the UCP library will schedule invocation of the call-back routine cb upon completion of the atomic operation. In other words, the completion of an atomic operation can be signaled by the return code or execution of the call-back.

Note

The user should not modify any part of the result after this operation is called, until the operation completes.

Parameters

[in]	ep	UCP endpoint.
[in]	opcode	One of ucp_atomic_fetch_op_t.
[in]	value	Source operand for atomic operation. In the case of CSWAP this is the conditional for the swap. For SWAP this is the value to be placed in remote memory.
[in,out]	result	Local memory address to store resulting fetch to. In the case of CSWAP the value in result will be swapped into the remote_addr if the condition is true.
[in]	op_size	Size of value in bytes and pointer type for result
[in]	remote_addr	Remote address to operate on.
[in]	rkey	Remote key handle for the remote memory address.
[in]	cb	Call-back function that is invoked whenever the send operation is completed. It is important to note that the call-back function is only invoked in a case when the operation cannot be completed in place.

Returns

NULL - The operation was completed immediately.

UCS_PTR_IS_ERR(_ptr) - The operation failed.

otherwise - Operation was scheduled and can be completed at any point in time. The request handle is returned to the application in order to track progress of the operation. The application is responsible for releasing the handle using ucp_request_free() routine.

ucp_request_check_status()

ucs_status_t ucp_request_check_status

(

void *

request

)

This routine checks the state of the request and returns its current status. Any value different from UCS_INPROGRESS means that request is in a completed state.

Parameters

[in]

request

Non-blocking request to check.

Returns

Error code as defined by ucs_status_t

Examples

ucp_hello_world.c.

ucp_tag_recv_request_test()

ucs_status_t ucp_tag_recv_request_test	(	void *	request,
		ucp_tag_recv_info_t *	info
	)

This routine checks the state and returns current status of the request returned from ucp_tag_recv_nb routine or the user allocated request for ucp_tag_recv_nbr. Any value different from UCS_INPROGRESS means that the request is in a completed state.

Parameters

[in]	request	Non-blocking request to check.
[out]	info	It is filled with the details about the message available at the moment of calling.

Returns

Error code as defined by ucs_status_t

ucp_stream_recv_request_test()

ucs_status_t ucp_stream_recv_request_test	(	void *	request,
		size_t *	length_p
	)

This routine checks the state and returns current status of the request returned from ucp_stream_recv_nb routine. Any value different from UCS_INPROGRESS means that the request is in a completed state.

Parameters

[in]	request	Non-blocking request to check.
[out]	length_p	The size of the received data in bytes. This value is only valid if the status is UCS_OK. If valid, it is always an integral multiple of the datatype size associated with the request.

Returns

Error code as defined by ucs_status_t

ucp_request_cancel()

void ucp_request_cancel	(	ucp_worker_h	worker,
		void *	request
	)

Parameters

[in]	worker	UCP worker.
[in]	request	Non-blocking request to cancel.

This routine tries to cancels an outstanding communication request. After calling this routine, the request will be in completed or canceled (but not both) state regardless of the status of the target endpoint associated with the communication request. If the request is completed successfully, the send or receive completion callbacks (based on the type of the request) will be called with the status argument of the callback set to UCS_OK, and in a case it is canceled the status argument is set to UCS_ERR_CANCELED. It is important to note that in order to release the request back to the library the application is responsible for calling ucp_request_free().

ucp_stream_data_release()

void ucp_stream_data_release	(	ucp_ep_h	ep,
		void *	data
	)

Parameters

[in]	ep	Endpoint data received from.
[in]	data	Data pointer to release, which was returned from ucp_stream_recv_data_nb.

This routine releases internal UCP data buffer returned by ucp_stream_recv_data_nb when data is processed, the application can't use this buffer after calling this function.

ucp_request_free()

void ucp_request_free

(

void *

request

)

Parameters

[in]

request

Non-blocking request to release.

This routine releases the non-blocking request back to the library, regardless of its current state. Communications operations associated with this request will make progress internally, however no further notifications or callbacks will be invoked for this request.

ucp_request_is_completed()

int ucp_request_is_completed

(

void *

request

)

Deprecated:

Replaced by ucp_request_test.

ucp_put()

ucs_status_t ucp_put	(	ucp_ep_h	ep,
		const void *	buffer,
		size_t	length,
		uint64_t	remote_addr,
		ucp_rkey_h	rkey
	)

Deprecated:

Replaced by ucp_put_nb. The following example implements the same functionality using ucp_put_nb :

void empty_callback(void *request, ucs_status_t status)
{
}

ucs_status_t put(ucp_ep_h ep, const void *buffer, size_t length,
                  uint64_t remote_addr, ucp_rkey_h rkey)
{
    void *request = ucp_put_nb(ep, buffer, length, remote_addr, rkey,
                               empty_callback),
    if (request == NULL) {
        return UCS_OK;
    } else if (UCS_PTR_IS_ERR(request)) {
        return UCS_PTR_STATUS(request);
    } else {
        ucs_status_t status;
        do {
            ucp_worker_progress(worker);
            status = ucp_request_check_status(request);
        } while (status == UCS_INPROGRESS);
        ucp_request_release(request);
        return status;
    }
}

This routine stores contiguous block of data that is described by the local address buffer in the remote contiguous memory region described by remote_addr address and the memory handle rkey. The routine returns when it is safe to reuse the source address buffer.

Parameters

[in]	ep	Remote endpoint handle.
[in]	buffer	Pointer to the local source address.
[in]	length	Length of the data (in bytes) stored under the source address.
[in]	remote_addr	Pointer to the destination remote address to write to.
[in]	rkey	Remote memory key associated with the remote address.

Returns

Error code as defined by ucs_status_t

ucp_get()

ucs_status_t ucp_get	(	ucp_ep_h	ep,
		void *	buffer,
		size_t	length,
		uint64_t	remote_addr,
		ucp_rkey_h	rkey
	)

Deprecated:

Replaced by ucp_get_nb.

See also

ucp_put.

This routine loads contiguous block of data that is described by the remote address remote_addr and the memory handle rkey in the local contiguous memory region described by buffer address. The routine returns when remote data is loaded and stored under the local address buffer.

Parameters

[in]	ep	Remote endpoint handle.
[in]	buffer	Pointer to the local source address.
[in]	length	Length of the data (in bytes) stored under the source address.
[in]	remote_addr	Pointer to the destination remote address to write to.
[in]	rkey	Remote memory key associated with the remote address.

Returns

Error code as defined by ucs_status_t

ucp_atomic_add32()

ucs_status_t ucp_atomic_add32	(	ucp_ep_h	ep,
		uint32_t	add,
		uint64_t	remote_addr,
		ucp_rkey_h	rkey
	)

Deprecated:

Replaced by ucp_atomic_post with opcode UCP_ATOMIC_POST_OP_ADD.

See also

ucp_put.

This routine performs an add operation on a 32 bit integer value atomically. The remote integer value is described by the combination of the remote memory address remote_addr and the remote memory handle rkey. The add value is the value that is used for the add operation. When the operation completes the sum of the original remote value and the operand value (add) is stored in remote memory. The call to the routine returns immediately, independent of operation completion.

Note

The remote address must be aligned to 32 bit.

Parameters

[in]	ep	Remote endpoint handle.
[in]	add	Value to add.
[in]	remote_addr	Pointer to the destination remote address of the atomic variable.
[in]	rkey	Remote memory key associated with the remote address.

Returns

Error code as defined by ucs_status_t

ucp_atomic_add64()

ucs_status_t ucp_atomic_add64	(	ucp_ep_h	ep,
		uint64_t	add,
		uint64_t	remote_addr,
		ucp_rkey_h	rkey
	)

Deprecated:

Replaced by ucp_atomic_post with opcode UCP_ATOMIC_POST_OP_ADD.

See also

ucp_put.

This routine performs an add operation on a 64 bit integer value atomically. The remote integer value is described by the combination of the remote memory address remote_addr and the remote memory handle rkey. The add value is the value that is used for the add operation. When the operation completes the sum of the original remote value and the operand value (add) is stored in remote memory. The call to the routine returns immediately, independent of operation completion.

Note

The remote address must be aligned to 64 bit.

Parameters

[in]	ep	Remote endpoint handle.
[in]	add	Value to add.
[in]	remote_addr	Pointer to the destination remote address of the atomic variable.
[in]	rkey	Remote memory key associated with the remote address.

Returns

Error code as defined by ucs_status_t

ucp_atomic_fadd32()

ucs_status_t ucp_atomic_fadd32	(	ucp_ep_h	ep,
		uint32_t	add,
		uint64_t	remote_addr,
		ucp_rkey_h	rkey,
		uint32_t *	result
	)

Deprecated:

Replaced by ucp_atomic_fetch_nb with opcode UCP_ATOMIC_FETCH_OP_FADD.

See also

ucp_put.

This routine performs an add operation on a 32 bit integer value atomically. The remote integer value is described by the combination of the remote memory address remote_addr and the remote memory handle rkey. The add value is the value that is used for the add operation. When the operation completes, the original remote value is stored in the local memory result, and the sum of the original remote value and the operand value is stored in remote memory. The call to the routine returns when the operation is completed and the result value is updated.

Note

The remote address must be aligned to 32 bit.

Parameters

[in]	ep	Remote endpoint handle.
[in]	add	Value to add.
[in]	remote_addr	Pointer to the destination remote address of the atomic variable.
[in]	rkey	Remote memory key associated with the remote address.
[out]	result	Pointer to the address that is used to store the previous value of the atomic variable described by the remote_addr

Returns

Error code as defined by ucs_status_t

ucp_atomic_fadd64()

ucs_status_t ucp_atomic_fadd64	(	ucp_ep_h	ep,
		uint64_t	add,
		uint64_t	remote_addr,
		ucp_rkey_h	rkey,
		uint64_t *	result
	)

Deprecated:

Replaced by ucp_atomic_fetch_nb with opcode UCP_ATOMIC_FETCH_OP_FADD.

See also

ucp_put.

This routine performs an add operation on a 64 bit integer value atomically. The remote integer value is described by the combination of the remote memory address remote_addr and the remote memory handle rkey. The add value is the value that is used for the add operation. When the operation completes, the original remote value is stored in the local memory result, and the sum of the original remote value and the operand value is stored in remote memory. The call to the routine returns when the operation is completed and the result value is updated.

Note

The remote address must be aligned to 64 bit.

Parameters

[in]	ep	Remote endpoint handle.
[in]	add	Value to add.
[in]	remote_addr	Pointer to the destination remote address of the atomic variable.
[in]	rkey	Remote memory key associated with the remote address.
[out]	result	Pointer to the address that is used to store the previous value of the atomic variable described by the remote_addr

Returns

Error code as defined by ucs_status_t

ucp_atomic_swap32()

ucs_status_t ucp_atomic_swap32	(	ucp_ep_h	ep,
		uint32_t	swap,
		uint64_t	remote_addr,
		ucp_rkey_h	rkey,
		uint32_t *	result
	)

Deprecated:

Replaced by ucp_atomic_fetch_nb with opcode UCP_ATOMIC_FETCH_OP_SWAP.

See also

ucp_put.

This routine swaps a 32 bit value between local and remote memory. The remote value is described by the combination of the remote memory address remote_addr and the remote memory handle rkey. The swap value is the value that is used for the swap operation. When the operation completes, the remote value is stored in the local memory result, and the operand value (swap) is stored in remote memory. The call to the routine returns when the operation is completed and the result value is updated.

Note

The remote address must be aligned to 32 bit.

Parameters

[in]	ep	Remote endpoint handle.
[in]	swap	Value to swap.
[in]	remote_addr	Pointer to the destination remote address of the atomic variable.
[in]	rkey	Remote memory key associated with the remote address.
[out]	result	Pointer to the address that is used to store the previous value of the atomic variable described by the remote_addr

Returns

Error code as defined by ucs_status_t

ucp_atomic_swap64()

ucs_status_t ucp_atomic_swap64	(	ucp_ep_h	ep,
		uint64_t	swap,
		uint64_t	remote_addr,
		ucp_rkey_h	rkey,
		uint64_t *	result
	)

Deprecated:

Replaced by ucp_atomic_fetch_nb with opcode UCP_ATOMIC_FETCH_OP_SWAP.

See also

ucp_put.

This routine swaps a 64 bit value between local and remote memory. The remote value is described by the combination of the remote memory address remote_addr and the remote memory handle rkey. The swap value is the value that is used for the swap operation. When the operation completes, the remote value is stored in the local memory result, and the operand value (swap) is stored in remote memory. The call to the routine returns when the operation is completed and the result value is updated.

Note

The remote address must be aligned to 64 bit.

Parameters

[in]	ep	Remote endpoint handle.
[in]	swap	Value to swap.
[in]	remote_addr	Pointer to the destination remote address of the atomic variable.
[in]	rkey	Remote memory key associated with the remote address.
[out]	result	Pointer to the address that is used to store the previous value of the atomic variable described by the remote_addr

Returns

Error code as defined by ucs_status_t

ucp_atomic_cswap32()

ucs_status_t ucp_atomic_cswap32	(	ucp_ep_h	ep,
		uint32_t	compare,
		uint32_t	swap,
		uint64_t	remote_addr,
		ucp_rkey_h	rkey,
		uint32_t *	result
	)

Deprecated:

Replaced by ucp_atomic_fetch_nb with opcode UCP_ATOMIC_FETCH_OP_CSWAP.

See also

ucp_put.

This routine conditionally swaps a 32 bit value between local and remote memory. The swap occurs only if the condition value (continue) is equal to the remote value, otherwise the remote memory is not modified. The remote value is described by the combination of the remote memory address remote_addr and the remote memory handle rkey. The swap value is the value that is used to update the remote memory if the condition is true. The call to the routine returns when the operation is completed and the result value is updated.

Note

The remote address must be aligned to 32 bit.

Parameters

[in]	ep	Remote endpoint handle.
[in]	compare	Value to compare to.
[in]	swap	Value to swap.
[in]	remote_addr	Pointer to the destination remote address of the atomic variable.
[in]	rkey	Remote memory key associated with the remote address.
[out]	result	Pointer to the address that is used to store the previous value of the atomic variable described by the remote_addr

Returns

Error code as defined by ucs_status_t

ucp_atomic_cswap64()

ucs_status_t ucp_atomic_cswap64	(	ucp_ep_h	ep,
		uint64_t	compare,
		uint64_t	swap,
		uint64_t	remote_addr,
		ucp_rkey_h	rkey,
		uint64_t *	result
	)

Deprecated:

Replaced by ucp_atomic_fetch_nb with opcode UCP_ATOMIC_FETCH_OP_CSWAP.

See also

ucp_put.

This routine conditionally swaps a 64 bit value between local and remote memory. The swap occurs only if the condition value (continue) is equal to the remote value, otherwise the remote memory is not modified. The remote value is described by the combination of the remote memory address remote_addr and the remote memory handle rkey. The swap value is the value that is used to update the remote memory if the condition is true. The call to the routine returns when the operation is completed and the result value is updated.

Note

The remote address must be aligned to 64 bit.

Parameters

[in]	ep	Remote endpoint handle.
[in]	compare	Value to compare to.
[in]	swap	Value to swap.
[in]	remote_addr	Pointer to the destination remote address of the atomic variable.
[in]	rkey	Remote memory key associated with the remote address.
[out]	result	Pointer to the address that is used to store the previous value of the atomic variable described by the remote_addr

Returns

Error code as defined by ucs_status_t