Utilities

Contents

Utilities#

2026-03-31

20 min read time

Applies to Linux

This page provides references for utility types and functions in the ucxx library, including type definitions, multi-buffer header metadata, exception handling, and miscellaneous helpers.

Type Definitions#

#include <ucxx/typedefs.h>

namespace ucxx

namespace ucxx

Typedefs

typedef std::unordered_map<std::string, std::string> ConfigMap#

A UCP configuration map.

A UCP configuration map, with keys being the configuration name and value being the actual value set.

typedef std::function<void(ucs_status_t, std::shared_ptr<void>)> RequestCallbackUserFunction#

A user-defined function to execute as part of a ucxx::Request callback.

A user-defined function to execute as part of a ucxx::Request callback, allowing execution of custom code upon request completion.

typedef std::shared_ptr<void> RequestCallbackUserData#

Data for the user-defined function provided to the ucxx::Request callback.

Data passed to the user-defined function provided to the ucxx::Request callback, which the custom user-defined function may act upon.

typedef RequestCallbackUserFunction EndpointCloseCallbackUserFunction#

A user-defined function to execute after an endpoint closes.

A user-defined function to execute after an endpoint closes, allowing execution of custom code after such event.

typedef RequestCallbackUserData EndpointCloseCallbackUserData#

Data for the user-defined function provided to endpoint close callback.

Data passed to the user-defined function provided to the endpoint close callback, which the custom user-defined function may act upon.

std::function< std::shared_ptr< Buffer >size_t)> AmAllocatorType

Custom Active Message allocator type.

Type for a custom Active Message allocator that can be registered by a user so that the Active Message receiver can allocate a buffer of such type upon receiving message.

typedef std::function<void(std::shared_ptr<Request>, ucp_ep_h)> AmReceiverCallbackType#

Active Message receiver callback.

Type for a custom Active Message receiver callback, executed by the remote worker upon Active Message request completion. The first parameter is the request that completed, the second is the handle of the UCX endpoint of the sender.

typedef std::string AmReceiverCallbackOwnerType#

Active Message receiver callback owner name.

A string containing the owner’s name of an Active Message receiver callback. The owner should be a reasonably unique name, usually identifying the application, to allow other applications to coexist and register their own receiver callbacks.

typedef uint64_t AmReceiverCallbackIdType#

Active Message receiver callback identifier.

A 64-bit unsigned integer unique identifier type of an Active Message receiver callback.

typedef const std::string SerializedRemoteKey#

Serialized form of a remote key.

A string type representing the serialized form of a remote key, used for transmission and storage of remote memory access information.

Enums

enum ucxx_log_level_t#

Available logging levels.

Available logging levels that are used to enable specific log types based on user’s configuration and also to define appropriate functions to be used in UCXX code to log only when the appropriate level is enabled.

Values:

enumerator UCXX_LOG_LEVEL_FATAL#
enumerator UCXX_LOG_LEVEL_ERROR#
enumerator UCXX_LOG_LEVEL_WARN#
enumerator UCXX_LOG_LEVEL_DIAG#
enumerator UCXX_LOG_LEVEL_INFO#
enumerator UCXX_LOG_LEVEL_DEBUG#
enumerator UCXX_LOG_LEVEL_TRACE#
enumerator UCXX_LOG_LEVEL_TRACE_REQ#
enumerator UCXX_LOG_LEVEL_TRACE_DATA#
enumerator UCXX_LOG_LEVEL_TRACE_ASYNC#
enumerator UCXX_LOG_LEVEL_TRACE_FUNC#
enumerator UCXX_LOG_LEVEL_TRACE_POLL#
enumerator UCXX_LOG_LEVEL_LAST#
enumerator UCXX_LOG_LEVEL_PRINT#
enum class TransferDirection#

The direction of a UCXX transfer.

The direction of a UCXX transfer, can be either Send or Receive.

Values:

enumerator Send#
enumerator Receive#
enum Tag#

Strong type for a UCP tag.

Strong type for a UCP tag, preventing accidental mixing with wrong types, especially useful to prevent passing an argument in wrong order.

Values:

enum TagMask#

Strong type for a UCP tag mask.

Strong type for a UCP tag mask, preventing accidental mixing with wrong types, especially useful to prevent passing an argument in wrong order.

Values:

Variables

static constexpr TagMask TagMaskFull = {std::numeric_limits<std::underlying_type_t<TagMask>>::max()}#

A full UCP tag mask.

A convenience constant providing a full UCP tag mask (all bits set).

class TagRecvInfo#
#include <typedefs.h>

Information about probed tag message.

Contains information returned when probing by a tag message received by the worker but not yet consumed.

Public Functions

explicit TagRecvInfo(
const ucp_tag_recv_info_t &info
)#

Construct a TagRecvInfo object from a UCP tag receive info structure.

Parameters:

info – [in] The UCP tag receive info structure containing the sender tag and received data length.

Public Members

Tag senderTag#

Sender tag.

size_t length#

The size of the received data.

class AmReceiverCallbackInfo#
#include <typedefs.h>

Information of an Active Message receiver callback.

Type identifying an Active Message receiver callback’s owner name and unique identifier.

Public Functions

AmReceiverCallbackInfo(
) = delete#
AmReceiverCallbackInfo(
const AmReceiverCallbackOwnerType owner,
AmReceiverCallbackIdType id
)#

Construct an AmReceiverCallbackInfo object.

Parameters:

  • owner – [in] The owner name of the callback.

  • id – [in] The unique identifier of the callback.

Public Members

const AmReceiverCallbackOwnerType owner#

The owner name of the callback.

const AmReceiverCallbackIdType id#

The unique identifier of the callback.

Exceptions#

#include <ucxx/exception.h>

namespace ucxx

namespace ucxx
class Error : public std::exception#
#include <exception.h>

The base class for all UCX exceptions.

The base class for all UCX errors that may occur made into C++ exceptions.

Subclassed by ucxx::AlreadyExistsError, ucxx::BufferTooSmallError, ucxx::BusyError, ucxx::CanceledError, ucxx::ConnectionResetError, ucxx::EndpointTimeoutError, ucxx::ExceedsLimitError, ucxx::FirstEndpointFailureError, ucxx::FirstLinkFailureError, ucxx::IOError, ucxx::InvalidAddrError, ucxx::InvalidParamError, ucxx::LastEndpointFailureError, ucxx::LastLinkFailureError, ucxx::MessageTruncatedError, ucxx::NoDeviceError, ucxx::NoElemError, ucxx::NoMemoryError, ucxx::NoMessageError, ucxx::NoProgressError, ucxx::NoResourceError, ucxx::NotConnectedError, ucxx::NotImplementedError, ucxx::OutOfRangeError, ucxx::RejectedError, ucxx::ShmemSegmentError, ucxx::SomeConnectsFailedError, ucxx::TimedOutError, ucxx::UnreachableError, ucxx::UnsupportedError

Public Functions

inline explicit Error(
const std::string &msg
)#

The base class constructor.

The base class constructor taking the explanatory string of the error.

Parameters:

msg – [in] the explanatory string of the error.

inline const char *what(
) const noexcept override#

Returns an explanatory string.

Returns an explanatory string of the UCX error that has occurred.

Returns:

the explanatory string.

Private Members

std::string _msg = {}#
class NoMessageError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_NO_MESSAGE.

The exception raised when UCS_ERR_NO_MESSAGE occurs in UCX.

Public Functions

inline explicit NoMessageError(
const std::string &msg
)#

The UCS_ERR_NO_MESSAGE constructor.

The constructor for an exception raised with UCS_ERR_NO_MESSAGE occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class NoResourceError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_NO_RESOURCE.

The exception raised when UCS_ERR_NO_RESOURCE occurs in UCX.

Public Functions

inline explicit NoResourceError(
const std::string &msg
)#

The UCS_ERR_NO_RESOURCE constructor.

The constructor for an exception raised with UCS_ERR_NO_RESOURCE occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class IOError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_IO_ERROR.

The exception raised when UCS_ERR_IO_ERROR occurs in UCX.

Public Functions

inline explicit IOError(
const std::string &msg
)#

The UCS_ERR_IO_ERROR constructor.

The constructor for an exception raised with UCS_ERR_IO_ERROR occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class NoMemoryError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_NO_MEMORY.

The exception raised when UCS_ERR_NO_MEMORY occurs in UCX.

Public Functions

inline explicit NoMemoryError(
const std::string &msg
)#

The UCS_ERR_NO_MEMORY constructor.

The constructor for an exception raised with UCS_ERR_NO_MEMORY occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class InvalidParamError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_INVALID_PARAM.

The exception raised when UCS_ERR_INVALID_PARAM occurs in UCX.

Public Functions

inline explicit InvalidParamError(
const std::string &msg
)#

The UCS_ERR_INVALID_PARAM constructor.

The constructor for an exception raised with UCS_ERR_INVALID_PARAM occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class UnreachableError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_UNREACHABLE.

The exception raised when UCS_ERR_UNREACHABLE occurs in UCX.

Public Functions

inline explicit UnreachableError(
const std::string &msg
)#

The UCS_ERR_UNREACHABLE constructor.

The constructor for an exception raised with UCS_ERR_UNREACHABLE occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class InvalidAddrError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_INVALID_ADDR.

The exception raised when UCS_ERR_INVALID_ADDR occurs in UCX.

Public Functions

inline explicit InvalidAddrError(
const std::string &msg
)#

The UCS_ERR_INVALID_ADDR constructor.

The constructor for an exception raised with UCS_ERR_INVALID_ADDR occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class NotImplementedError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_NOT_IMPLEMENTED.

The exception raised when UCS_ERR_NOT_IMPLEMENTED occurs in UCX.

Public Functions

inline explicit NotImplementedError(
const std::string &msg
)#

The UCS_ERR_NOT_IMPLEMENTED constructor.

The constructor for an exception raised with UCS_ERR_NOT_IMPLEMENTED occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class MessageTruncatedError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_MESSAGE_TRUNCATED.

The exception raised when UCS_ERR_MESSAGE_TRUNCATED occurs in UCX.

Public Functions

inline explicit MessageTruncatedError(
const std::string &msg
)#

The UCS_ERR_MESSAGE_TRUNCATED constructor.

The constructor for an exception raised with UCS_ERR_MESSAGE_TRUNCATED occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class NoProgressError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_NO_PROGRESS.

The exception raised when UCS_ERR_NO_PROGRESS occurs in UCX.

Public Functions

inline explicit NoProgressError(
const std::string &msg
)#

The UCS_ERR_NO_PROGRESS constructor.

The constructor for an exception raised with UCS_ERR_NO_PROGRESS occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class BufferTooSmallError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_BUFFER_TOO_SMALL.

The exception raised when UCS_ERR_BUFFER_TOO_SMALL occurs in UCX.

Public Functions

inline explicit BufferTooSmallError(
const std::string &msg
)#

The UCS_ERR_BUFFER_TOO_SMALL constructor.

The constructor for an exception raised with UCS_ERR_BUFFER_TOO_SMALL occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class NoElemError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_NO_ELEM.

The exception raised when UCS_ERR_NO_ELEM occurs in UCX.

Public Functions

inline explicit NoElemError(
const std::string &msg
)#

The UCS_ERR_NO_ELEM constructor.

The constructor for an exception raised with UCS_ERR_NO_ELEM occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class SomeConnectsFailedError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_SOME_CONNECTS_FAILED.

The exception raised when UCS_ERR_SOME_CONNECTS_FAILED occurs in UCX.

Public Functions

inline explicit SomeConnectsFailedError(
const std::string &msg
)#

The UCS_ERR_SOME_CONNECTS_FAILED constructor.

The constructor for an exception raised with UCS_ERR_SOME_CONNECTS_FAILED occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class NoDeviceError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_NO_DEVICE.

The exception raised when UCS_ERR_NO_DEVICE occurs in UCX.

Public Functions

inline explicit NoDeviceError(
const std::string &msg
)#

The UCS_ERR_NO_DEVICE constructor.

The constructor for an exception raised with UCS_ERR_NO_DEVICE occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class BusyError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_BUSY.

The exception raised when UCS_ERR_BUSY occurs in UCX.

Public Functions

inline explicit BusyError(
const std::string &msg
)#

The UCS_ERR_BUSY constructor.

The constructor for an exception raised with UCS_ERR_BUSY occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class CanceledError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_CANCELED.

The exception raised when UCS_ERR_CANCELED occurs in UCX.

Public Functions

inline explicit CanceledError(
const std::string &msg
)#

The UCS_ERR_CANCELED constructor.

The constructor for an exception raised with UCS_ERR_CANCELED occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class ShmemSegmentError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_SHMEM_SEGMENT.

The exception raised when UCS_ERR_SHMEM_SEGMENT occurs in UCX.

Public Functions

inline explicit ShmemSegmentError(
const std::string &msg
)#

The UCS_ERR_SHMEM_SEGMENT constructor.

The constructor for an exception raised with UCS_ERR_SHMEM_SEGMENT occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class AlreadyExistsError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_ALREADY_EXISTS.

The exception raised when UCS_ERR_ALREADY_EXISTS occurs in UCX.

Public Functions

inline explicit AlreadyExistsError(
const std::string &msg
)#

The UCS_ERR_ALREADY_EXISTS constructor.

The constructor for an exception raised with UCS_ERR_ALREADY_EXISTS occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class OutOfRangeError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_OUT_OF_RANGE.

The exception raised when UCS_ERR_OUT_OF_RANGE occurs in UCX.

Public Functions

inline explicit OutOfRangeError(
const std::string &msg
)#

The UCS_ERR_OUT_OF_RANGE constructor.

The constructor for an exception raised with UCS_ERR_OUT_OF_RANGE occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class TimedOutError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_TIMED_OUT.

The exception raised when UCS_ERR_TIMED_OUT occurs in UCX.

Public Functions

inline explicit TimedOutError(
const std::string &msg
)#

The UCS_ERR_TIMED_OUT constructor.

The constructor for an exception raised with UCS_ERR_TIMED_OUT occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class ExceedsLimitError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_EXCEEDS_LIMIT.

The exception raised when UCS_ERR_EXCEEDS_LIMIT occurs in UCX.

Public Functions

inline explicit ExceedsLimitError(
const std::string &msg
)#

The UCS_ERR_EXCEEDS_LIMIT constructor.

The constructor for an exception raised with UCS_ERR_EXCEEDS_LIMIT occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class UnsupportedError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_UNSUPPORTED.

The exception raised when UCS_ERR_UNSUPPORTED occurs in UCX.

Public Functions

inline explicit UnsupportedError(
const std::string &msg
)#

The UCS_ERR_UNSUPPORTED constructor.

The constructor for an exception raised with UCS_ERR_UNSUPPORTED occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class RejectedError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_REJECTED.

The exception raised when UCS_ERR_REJECTED occurs in UCX.

Public Functions

inline explicit RejectedError(
const std::string &msg
)#

The UCS_ERR_REJECTED constructor.

The constructor for an exception raised with UCS_ERR_REJECTED occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class NotConnectedError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_NOT_CONNECTED.

The exception raised when UCS_ERR_NOT_CONNECTED occurs in UCX.

Public Functions

inline explicit NotConnectedError(
const std::string &msg
)#

The UCS_ERR_NOT_CONNECTED constructor.

The constructor for an exception raised with UCS_ERR_NOT_CONNECTED occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class ConnectionResetError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_CONNECTION_RESET.

The exception raised when UCS_ERR_CONNECTION_RESET occurs in UCX.

Public Functions

inline explicit ConnectionResetError(
const std::string &msg
)#

The UCS_ERR_CONNECTION_RESET constructor.

The constructor for an exception raised with UCS_ERR_CONNECTION_RESET occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class FirstLinkFailureError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_FIRST_LINK_FAILURE.

The exception raised when UCS_ERR_FIRST_LINK_FAILURE occurs in UCX.

Public Functions

inline explicit FirstLinkFailureError(
const std::string &msg
)#

The UCS_ERR_FIRST_LINK_FAILURE constructor.

The constructor for an exception raised with UCS_ERR_FIRST_LINK_FAILURE occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class LastLinkFailureError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_LAST_LINK_FAILURE.

The exception raised when UCS_ERR_LAST_LINK_FAILURE occurs in UCX.

Public Functions

inline explicit LastLinkFailureError(
const std::string &msg
)#

The UCS_ERR_LAST_LINK_FAILURE constructor.

The constructor for an exception raised with UCS_ERR_LAST_LINK_FAILURE occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class FirstEndpointFailureError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_FIRST_ENDPOINT_FAILURE.

The exception raised when UCS_ERR_FIRST_ENDPOINT_FAILURE occurs in UCX.

Public Functions

inline explicit FirstEndpointFailureError(
const std::string &msg
)#

The UCS_ERR_FIRST_ENDPOINT_FAILURE constructor.

The constructor for an exception raised with UCS_ERR_FIRST_ENDPOINT_FAILURE occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class EndpointTimeoutError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_ENDPOINT_TIMEOUT.

The exception raised when UCS_ERR_ENDPOINT_TIMEOUT occurs in UCX.

Public Functions

inline explicit EndpointTimeoutError(
const std::string &msg
)#

The UCS_ERR_ENDPOINT_TIMEOUT constructor.

The constructor for an exception raised with UCS_ERR_ENDPOINT_TIMEOUT occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

class LastEndpointFailureError : public ucxx::Error#
#include <exception.h>

The exception for UCS_ERR_LAST_ENDPOINT_FAILURE.

The exception raised when UCS_ERR_LAST_ENDPOINT_FAILURE occurs in UCX.

Public Functions

inline explicit LastEndpointFailureError(
const std::string &msg
)#

The UCS_ERR_LAST_ENDPOINT_FAILURE constructor.

The constructor for an exception raised with UCS_ERR_LAST_ENDPOINT_FAILURE occurs in UCX.

Parameters:

msg – [in] the explanatory string of the error.

Utility Helpers#

Socket Address Utilities#

#include <ucxx/utils/sockaddr.h>

namespace ucxx::utils

namespace ucxx
namespace utils#

Functions

std::unique_ptr<struct addrinfo, void (*)(struct addrinfo*)> get_addrinfo(
const char *ip_address,
uint16_t port
)#

Get an addrinfo struct corresponding to an address and port.

This information can later be used to bind a UCP listener or endpoint.

Parameters:

  • ip_address – [in] valid socket address (e.g., IP address or hostname) or NULL as a wildcard for “all” to set the socket address storage to.

  • port – [in] port to set the socket address storage to.

Returns:

unique pointer wrapping a struct addrinfo (frees the addrinfo when out of scope)

void sockaddr_get_ip_port_str(
const struct sockaddr_storage *sock_addr,
char *ip_str,
char *port_str,
size_t max_str_size
)#

Get socket address and port of a socket address storage.

Get the socket address (usually the IP address) and port from a socket address storage pointer.

Parameters:

  • sock_addr – [in] pointer to the socket address storage.

  • ip_str – [in] socket address (or IP) contained the socket address storage.

  • port_str – [in] port contained the socket address storage.

  • max_str_size – [in] size of the ip_str and port_str strings.

File Descriptor Utilities#

#include <ucxx/utils/file_descriptor.h>

namespace ucxx::utils

namespace ucxx
namespace utils

Functions

FILE *createTextFileDescriptor(
)#

Create a file descriptor from a temporary file.

Create a file descriptor from a temporary file.

Throws:

std::ios_base::failure – if creating a temporary file fails, a common cause being lack of write permissions to /tmp.

Returns:

The file descriptor created.

std::string decodeTextFileDescriptor(
FILE *textFileDescriptor
)#

Decode text file descriptor.

Decode a text file descriptor and return it as a string.

Throws:

std::ios_base::failure – if reading the file descriptor fails.

Returns:

The string with a copy of the file descriptor contents.

UCX Wrappers#

#include <ucxx/utils/ucx.h>

namespace ucxx::utils

namespace ucxx
namespace utils

Functions

void ucsErrorThrow(
const ucs_status_t status,
std::string userMessage = ""
)#

Throw appropriate exception on UCS error.

Throw an exception appropriately mapped from a UCS error. For status UCS_OK and UCS_INPROGRESS or unknown values, calling this function acts as a no-op. Additionally set the msg_context string to a human-readable error message.

Parameters:

  • status – [in] UCS status for which to check state.

  • userMessage – [out] user-defined, human-readable error message.

Throws:
Contents