holoscan::PoseTreeUCXClient

Beta

UCX-based client for remote PoseTree synchronization.

This class provides a client that connects to a PoseTreeUCXServer to synchronize PoseTree updates across distributed systems using UCX (Unified Communication X).

#include <holoscan/pose_tree_ucx_client.hpp>

This class is NOT thread-safe for its public methods. All public methods must be called from the same thread.

Constructors

PoseTreeUCXClient

Overload 1

Deleted overloads

holoscan::PoseTreeUCXClient::PoseTreeUCXClient(holoscan::PoseTreeUCXClient::PoseTreeUCXClient(
    std::shared_ptr<PoseTree> pose_tree,
    PoseTreeUCXClientConfig config = PoseTreeUCXClientConfig{}    PoseTreeUCXClientConfig config = PoseTreeUCXClientConfig{}
)

Destructor

~PoseTreeUCXClient

holoscan::PoseTreeUCXClient::~PoseTreeUCXClient()holoscan::PoseTreeUCXClient::~PoseTreeUCXClient()

Destructor - ensures clean shutdown.

Automatically disconnects if still connected, joins the worker thread, and releases all resources. Any errors during disconnect are logged but do not throw exceptions (no-throw guarantee).

Assignment operators

operator=

Deleted overloads

The following overloads are deleted to prevent misuse:

PoseTreeUCXClient & holoscan::PoseTreeUCXClient::operator=(const PoseTreeUCXClient &) = delete;PoseTreeUCXClient & holoscan::PoseTreeUCXClient::operator=(const PoseTreeUCXClient &) = delete;PoseTreeUCXClient & holoscan::PoseTreeUCXClient::operator=(const PoseTreeUCXClient &) = delete;
PoseTreeUCXClient & holoscan::PoseTreeUCXClient::operator=(PoseTreeUCXClient &&) = delete;PoseTreeUCXClient & holoscan::PoseTreeUCXClient::operator=(PoseTreeUCXClient &&) = delete;PoseTreeUCXClient & holoscan::PoseTreeUCXClient::operator=(PoseTreeUCXClient &&) = delete;

Methods

connect

expected<void> holoscan::PoseTreeUCXClient::connect(
    std::string_view host,
    uint16_t port,
    bool request_snapshot
)

Connect to a PoseTreeUCXServer.

Starts an internal worker thread that handles UCX communication with the server. The thread runs until disconnect() is called or the destructor runs.

This method blocks until the connection is established or fails

Returns: Success (void) or error status

Parameters

host

std::string_view

The hostname or IP address of the server

port

uint16_t

The port number of the server

request_snapshot

bool

Whether to request a full snapshot of the pose tree upon connection

disconnect

expected<void> holoscan::PoseTreeUCXClient::disconnect()

Disconnect from the server.

Signals the worker thread to stop, waits for it to finish (join), and cleans up all UCX resources. This method is automatically called by the destructor if needed.

This method is idempotent - calling it when already disconnected returns success

This method blocks until the worker thread has fully stopped

Returns: Success (void) or error status

is_running

bool holoscan::PoseTreeUCXClient::is_running() const

run

void holoscan::PoseTreeUCXClient::run()

Main worker thread function.

Handles UCX worker progress, processes server messages, and manages the connection. Runs in a separate thread started by connect() and stopped by disconnect().

Static methods

error_to_str

static const char * holoscan::PoseTreeUCXClient::error_to_str(
    Error error
)

Convert an error code to a human readable error string.

Returns: Human-readable error string.

Parameters

error

Error

Error code to convert.

Types

Typedefs

Name	Definition	Description
`expected`	`holoscan::expected< T, Error >`	Expected type used by this class.
`unexpected`	`holoscan::unexpected< Error >`	Unexpected type used by this class.

Error

Error codes used by this class.

Name	Value	Description
`kAlreadyConnected`	`= 0`	kAlreadyConnected is returned when trying to connect while already connected
`kInvalidArgument`	`= 1`	kInvalidArgument is returned when invalid parameters are provided (e.g., empty host, invalid port)
`kConnectionFailed`	`= 2`	kConnectionFailed is returned when connection to the server fails
`kNotConnected`	`= 3`	kNotConnected is returned when trying to perform operations that require a connection
`kThreadError`	`= 4`	kThreadError is returned when thread operations fail
`kShutdownError`	`= 5`	kShutdownError is returned when errors occur during shutdown/disconnect
`kInternalError`	`= 6`	kInternalError is returned for unexpected internal errors

Member variables

Name	Type	Description
`impl_`	`std::unique_ptr< ClientImpl >`	Implementation details (PIMPL pattern) containing UCX objects.
`pose_tree_`	`std::shared_ptr< PoseTree >`	The local PoseTree instance to synchronize.
`host_`	`std::string`	Hostname or IP address of the server.
`port_`	`uint16_t`	Port number of the server.
`request_snapshot_`	`bool`	Whether to request a full snapshot on connection.
`running_`	`std::atomic< bool >`	Flag indicating if the client is running.
`client_thread_`	`std::thread`	The worker thread handling UCX communication.
`is_external_pose_tree_update_`	`std::atomic< bool >`	Flag to prevent feedback loops during updates.
`startup_callbacks_registered_`	`std::atomic< bool >`	True once local PoseTree callbacks are registered.
`initial_snapshot_applied_`	`std::atomic< bool >`	True once the initial requested snapshot has been applied.
`ready_mutex_`	`std::mutex`	Mutex for synchronizing connection startup.
`ready_cv_`	`std::condition_variable`	Condition variable for signaling connection readiness.
`ready_`	`std::atomic< bool >`	Flag indicating if the connection is established.
`connect_failed_`	`std::atomic< bool >`	Flag indicating if connection attempt failed.
`config_`	`PoseTreeUCXClientConfig`	Configuration parameters for the client.