Address

Address#

2026-03-31

3 min read time

Applies to Linux

The ucxx::Address class represents a worker address that can be used to establish connections between endpoints. Addresses are obtained from workers and can be serialized for out-of-band exchange.

#include <ucxx/address.h>

namespace ucxx

class Address : public ucxx::Component#

Component encapsulating the address of a UCP worker.

A UCP worker has a unique address that can is contained in a ucp_address_t* object, this class encapsulates that object and provides methods to simplify its handling.

Public Functions

ucp_address_t *getHandle(
) const#

Get the underlying ucp_address_t* handle.

Lifetime of the ucp_address_t* handle is managed by the ucxx::Address object and its ownership is non-transferrable. Once the ucxx::Address is destroyed the handle is not valid anymore, it is the user’s responsibility to ensure the owner’s lifetime while using the handle.

// address is `std::shared_ptr<ucxx::Address>`
ucp_address_t* addressHandle = address->getHandle();
Returns:

The underlying ucp_address_t handle.

size_t getLength(
) const#

Get the length of the ucp_address_t* handle.

Get the length of the ucp_address_t* handle, required to access the complete address and prevent reading out-of-bound.

Returns:

The length of the ucp_address_t* handle in bytes.

std::string getString(
) const#

Get the address as a string.

Convenience method to copy the underlying address to a std::string and return it as a single object.

Returns:

The underlying ucp_address_t handle.

Friends

friend std::shared_ptr<Address> createAddressFromWorker(
std::shared_ptr<Worker> worker
)#

Constructor for shared_ptr<ucxx::Address> from worker.

The constructor for a shared_ptr<ucxx::Address> object from a std::shared_ptr<ucxx::Worker> to obtain its address.

Parameters:

worker – [in] parent worker from which to get the address.

Returns:

The shared_ptr<ucxx::Address> object.

friend std::shared_ptr<Address> createAddressFromString(
std::string addressString
)#

Constructor for shared_ptr<ucxx::Address> from string.

The constructor for a shared_ptr<ucxx::Address> object from the address extracted as string from a remote std::shared_ptr<ucxx::Worker>.

Parameters:

addressString – [in] the string from which to create the address.

Returns:

The shared_ptr<ucxx::Address> object.

Factory Functions#

#include <ucxx/constructors.h>

std::shared_ptr<Address> ucxx::createAddressFromWorker(
std::shared_ptr<Worker> worker
)#

The constructor for a shared_ptr<ucxx::Address> object from a std::shared_ptr<ucxx::Worker> to obtain its address.

Parameters:

worker – [in] parent worker from which to get the address.

Returns:

The shared_ptr<ucxx::Address> object.

std::shared_ptr<Address> ucxx::createAddressFromString(
std::string addressString
)#

The constructor for a shared_ptr<ucxx::Address> object from the address extracted as string from a remote std::shared_ptr<ucxx::Worker>.

Parameters:

addressString – [in] the string from which to create the address.

Returns:

The shared_ptr<ucxx::Address> object.