Class PoseTreeUCXServer

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.

Public Types

enum class Error

Error codes used by this class.

Values:

enumerator kAlreadyRunning

kAlreadyRunning is returned when trying to start while already running

enumerator kInvalidArgument

kInvalidArgument is returned when invalid parameters are provided

enumerator kStartupFailed

kStartupFailed is returned when server fails to start

enumerator kNotRunning

kNotRunning is returned when trying to perform operations that require the server to be running

enumerator kShutdownTimeout

kShutdownTimeout is returned when shutdown takes too long

enumerator kInternalError

kInternalError is returned for unexpected internal errors

template<typename T>
using expected = holoscan::expected<T, Error>

Expected type used by this class.

using unexpected = holoscan::unexpected<Error>

Unexpected type used by this class.

Public Functions

explicit 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.

Parameters

• pose_tree – The PoseTree instance to synchronize. Must be initialized.

• config – Configuration parameters for the server.

Throws

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

~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).

PoseTreeUCXServer(const PoseTreeUCXServer&) = delete

PoseTreeUCXServer &operator=(const PoseTreeUCXServer&) = delete

PoseTreeUCXServer(PoseTreeUCXServer&&) = delete

PoseTreeUCXServer &operator=(PoseTreeUCXServer&&) = delete

expected<void> 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.

Note

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

Note

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

Parameters

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

Returns

Success (void) or error status

expected<void> 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.

Note

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

Note

This method blocks until the worker thread has fully stopped

Note

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

Returns

Success (void) or error status

inline bool is_running() const

Check if the server is running.

Returns

true if the server is running, false otherwise

Public Static Functions

static const char *error_to_str(Error error)

Convert an error code to a human readable error string.

Parameters

error – Error code to convert.

Returns

Human-readable error string.

Friends

friend void connection_callback(ucp_conn_request_h req, void *arg)