> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/holoscan/sdk-user-guide/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/holoscan/sdk-user-guide/_mcp/server.

# holoscan::PoseTreeUCXServer

> UCX-based server for remote PoseTree synchronization.

UCX-based server for remote [PoseTree](posetree) synchronization.

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

```cpp showLineNumbers={false}
#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 \[#posetreeucxserver]

#### Construct a new \`PoseTreeUCXServer\` object

```cpp showLineNumbers={false}
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](posetree) with connected clients. The server creates its own internal copy of the [PoseTree](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](posetree) instance to synchronize. Must be initialized.

---

**`config`** `PoseTreeUCXServerConfig` — default: PoseTreeUCXServerConfig\{}

Configuration parameters for the server.

---

#### Deleted overloads

The following overloads are deleted to prevent misuse:

```cpp showLineNumbers={false}
holoscan::PoseTreeUCXServer::PoseTreeUCXServer(const PoseTreeUCXServer &) = delete;
holoscan::PoseTreeUCXServer::PoseTreeUCXServer(PoseTreeUCXServer &&) = delete;
```

### Destructor \[#destructor]

### \~PoseTreeUCXServer

```cpp showLineNumbers={false}
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= \[#operator\_assign]

#### Deleted overloads

The following overloads are deleted to prevent misuse:

```cpp showLineNumbers={false}
PoseTreeUCXServer & holoscan::PoseTreeUCXServer::operator=(const PoseTreeUCXServer &) = delete;
PoseTreeUCXServer & holoscan::PoseTreeUCXServer::operator=(PoseTreeUCXServer &&) = delete;
```

---

## Methods

### start \[#start]

```cpp showLineNumbers={false}
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 \[#stop]

```cpp showLineNumbers={false}
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 \[#isrunning]

```cpp showLineNumbers={false}
bool holoscan::PoseTreeUCXServer::is_running() const
```

Check if the server is running.

**Returns:** true if the server is running, false otherwise

### run \[#run]

```cpp showLineNumbers={false}
void holoscan::PoseTreeUCXServer::run()
```

Main worker thread function.

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

---

## Static methods

### error\_to\_str \[#errortostr]

```cpp showLineNumbers={false}
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](posetree) instance being synchronized.             |
| `pose_tree_init_params_` | `PoseTree::InitParameters`      | Initialization parameters from the original [PoseTree](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](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.                          |