holoscan::PoseTreeUCXServer

Beta

UCX-based server for remote PoseTree synchronization.

This class provides a server that listens for connections from PoseTreeUCXClient instances to synchronize PoseTree updates across distributed systems using UCX (Unified Communication X). The server maintains its own PoseTree instance and broadcasts updates to all connected clients.

#include <holoscan/pose_tree_ucx_server.hpp>

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

Constructors

PoseTreeUCXServer

Construct a new `PoseTreeUCXServer` object

Deleted overloads

holoscan::PoseTreeUCXServer::PoseTreeUCXServer(
    std::shared_ptr<PoseTree> pose_tree,
    PoseTreeUCXServerConfig config = PoseTreeUCXServerConfig{}
)

Construct a new PoseTreeUCXServer object.

Creates a server that will synchronize the provided PoseTree with connected clients. The server creates its own internal copy of the PoseTree to avoid conflicts with the worker thread.

Throws: std::runtime_error if pose_tree is null or not initialized.

Parameters

pose_tree

std::shared_ptr<PoseTree>

The PoseTree instance to synchronize. Must be initialized.

config

PoseTreeUCXServerConfigDefaults to PoseTreeUCXServerConfig{}

Configuration parameters for the server.

Destructor

~PoseTreeUCXServer

holoscan::PoseTreeUCXServer::~PoseTreeUCXServer()

Destructor - ensures clean shutdown.

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

Assignment operators

operator=

Deleted overloads

The following overloads are deleted to prevent misuse:

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

Methods

start

expected<void> holoscan::PoseTreeUCXServer::start(
    uint16_t port
)

Start the server on the specified port.

Starts an internal worker thread that listens for client connections and handles UCX communication. The thread runs until stop() is called or the destructor runs.

This method blocks until the server is fully started or fails to start

Only one server can listen on a given port at a time

Returns: Success (void) or error status

Parameters

port

uint16_t

The port number to listen on (must be non-zero)

stop

expected<void> holoscan::PoseTreeUCXServer::stop()

Stop the server.

Signals the worker thread to stop, notifies all connected clients of shutdown, waits for the thread 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 stopped returns success

This method blocks until the worker thread has fully stopped

Connected clients are given time to disconnect cleanly (controlled by shutdown_timeout_ms)

Returns: Success (void) or error status

is_running

bool holoscan::PoseTreeUCXServer::is_running() const

Check if the server is running.

Returns: true if the server is running, false otherwise

run

void holoscan::PoseTreeUCXServer::run()

Main worker thread function.

Handles UCX worker progress, processes client requests, and manages connections.

Static methods

error_to_str

static const char * holoscan::PoseTreeUCXServer::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
`kAlreadyRunning`	`= 0`	kAlreadyRunning is returned when trying to start while already running
`kInvalidArgument`	`= 1`	kInvalidArgument is returned when invalid parameters are provided
`kStartupFailed`	`= 2`	kStartupFailed is returned when server fails to start
`kNotRunning`	`= 3`	kNotRunning is returned when trying to perform operations that require the server to be running
`kShutdownTimeout`	`= 4`	kShutdownTimeout is returned when shutdown takes too long
`kInternalError`	`= 5`	kInternalError is returned for unexpected internal errors

Member variables

Name	Type	Description
`impl_`	`std::unique_ptr< ServerImpl >`	Implementation details (PIMPL pattern).
`pose_tree_`	`std::shared_ptr< PoseTree >`	The PoseTree instance being synchronized.
`pose_tree_init_params_`	`PoseTree::InitParameters`	Initialization parameters from the original PoseTree.
`port_`	`uint16_t`	The port number the server is listening on.
`running_`	`std::atomic< bool >`	Flag indicating if the server is running.
`server_thread_`	`std::thread`	The worker thread handling UCX communication.
`ready_mutex_`	`std::mutex`	Mutex for synchronizing server startup.
`ready_cv_`	`std::condition_variable`	Condition variable for signaling server readiness.
`ready_`	`std::atomic< bool >`	Flag indicating if the server is ready to accept connections.
`config_`	`PoseTreeUCXServerConfig`	Configuration parameters for the server.

Constructors

PoseTreeUCXServer

Construct a new PoseTreeUCXServer object

Deleted overloads

Destructor

~PoseTreeUCXServer

Assignment operators

operator=

Deleted overloads

Methods

start

stop

is_running

run

Static methods

error_to_str

Types

Typedefs

Error

Member variables

Construct a new `PoseTreeUCXServer` object