> 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::PoseTreeUCXClient

> UCX-based client for remote PoseTree synchronization.

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

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

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

#### Overload 1

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

#### Deleted overloads

The following overloads are deleted to prevent misuse:

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

### Destructor \[#destructor]

### \~PoseTreeUCXClient

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

#### Deleted overloads

The following overloads are deleted to prevent misuse:

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

---

## Methods

### connect \[#connect]

```cpp showLineNumbers={false}
expected<void> holoscan::PoseTreeUCXClient::connect(
    std::string_view host,
    uint16_t port,
    bool request_snapshot
)
```

Connect to a [PoseTreeUCXServer](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 \[#disconnect]

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

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

### run \[#run]

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

```cpp showLineNumbers={false}
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](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](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](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.                            |