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

> UCX-based double buffer receiver class.

UCX-based double buffer receiver class.

The `UcxReceiver` class is used to receive messages from an operator within another fragment of a distributed application. This is based on the same double-buffer queue as the [DoubleBufferReceiver](doublebufferreceiver), but also handles serialization/deserialization of data for sending it over the network via UCX's active message APIs.

[Application](application) authors are not expected to use this class directly. It will be automatically configured for input ports specified via [`Operator::setup`](gpuresidentoperator#setup) when [`Application::add_flow`](application#addflow) has been used to make a connection across fragments of a distributed application.

\==Parameters==

* **capacity** (uint64\_t, optional): The capacity of the double-buffer queue used by the receiver. Defaults to 1.
* **policy** (uint64\_t, optional): The policy to use when a message arrives, but there is no space in the receiver. The possible values are 0: pop, 1: reject, 2: fault (Default: 2).
* **address** (std::string, optional): The (IPv4) address of the receiver. Default of "0.0.0.0" corresponds to INADDR\_ANY.
* **port** (uint32\_t, optional): The receiver port (Default: [holoscan::kDefaultUcxPort](../variables/kdefaultucxport)).
* **buffer** (std::shared\_ptr\<holoscan::UcxSerializationBuffer>, optional): The serialization buffer that should be used. This defaults to [`UcxSerializationBuffer`](ucxserializationbuffer) and should not need to be set by the application author.

```cpp showLineNumbers={false}
#include <holoscan/ucx_receiver.hpp>
```

**Inherits from:** `holoscan::Receiver` (public)

---

## Constructors

### UcxReceiver \[#ucxreceiver]

#### Move

inline

explicit

```cpp showLineNumbers={false}
template <typename ArgT,
          typename... ArgsT,
          typename = std::enable_if_t<!std::is_base_of_v<::holoscan::Resource, std::decay_t<ArgT>> &&   (std::is_same_v<::holoscan::Arg, std::decay_t<ArgT>> ||   std::is_same_v<::holoscan::ArgList, std::decay_t<ArgT>>)>>
holoscan::UcxReceiver::UcxReceiver(
    ArgT &&arg,
    ArgsT &&... args
)
```

#### Default

```cpp showLineNumbers={false}
holoscan::UcxReceiver::UcxReceiver() = default
```

#### Copy

```cpp showLineNumbers={false}
holoscan::UcxReceiver::UcxReceiver(
    const std::string &name,
    nvidia::gxf::Receiver *component
)
```

---

## Methods

### gxf\_typename \[#gxftypename]

```cpp showLineNumbers={false}
const char * holoscan::UcxReceiver::gxf_typename() const override
```

### setup \[#setup]

```cpp showLineNumbers={false}
void holoscan::UcxReceiver::setup(
    ComponentSpec &spec
) override
```

Define the resource specification.

**Parameters**

**`spec`** `ComponentSpec &`

The reference to the component specification.

---

### initialize \[#initialize]

```cpp showLineNumbers={false}
void holoscan::UcxReceiver::initialize() override
```

Initialize the component.

This method is called only once when the component is created for the first time, and use of light-weight initialization.

### address \[#address]

```cpp showLineNumbers={false}
std::string holoscan::UcxReceiver::address()
```

The IPv4 network address used by the receiver.

### port \[#port]

```cpp showLineNumbers={false}
uint32_t holoscan::UcxReceiver::port()
```

The network port used by the receiver.

### get \[#get]

```cpp showLineNumbers={false}
nvidia::gxf::UcxReceiver * holoscan::UcxReceiver::get() const
```

### track \[#track]

```cpp showLineNumbers={false}
void holoscan::UcxReceiver::track()
```

Enable tracking in the underlying [holoscan::HoloscanUcxReceiver](holoscanucxreceiver) class.

### capacity \[#capacity]

```cpp showLineNumbers={false}
size_t holoscan::UcxReceiver::capacity() const
```

Get the current capacity of the [Receiver](receiver) queue.

For double-buffer queues this is the capacity of the main stage

**Returns:** The capacity of the [Receiver](receiver) queue.

### size \[#size]

```cpp showLineNumbers={false}
size_t holoscan::UcxReceiver::size() const
```

Get the number of elements currently in the main stage of the [Receiver](receiver) queue.

**Returns:** The number of elements in the main stage.

### back\_size \[#backsize]

```cpp showLineNumbers={false}
size_t holoscan::UcxReceiver::back_size() const
```

Get the number of elements currently in the back stage of the [Receiver](receiver) queue.

**Returns:** The number of elements in the back stage.

### peek \[#peek]

```cpp showLineNumbers={false}
nvidia::gxf::Expected<nvidia::gxf::Entity> holoscan::UcxReceiver::peek(
    int32_t index = 0
) const
```

Peek at a message in the queue without consuming it.

This method allows inspection of messages in the main stage of the receiver queue without removing them. This is useful for conditions that need to check message contents before the operator executes.

**Returns:** The entity at the given index, or an error if not available.

**Parameters**

**`index`** `int32_t` — default: 0

The index of the message to peek (0 = oldest message in queue).

---

### sync \[#sync]

```cpp showLineNumbers={false}
nvidia::gxf::Expected<void> holoscan::UcxReceiver::sync()
```

Sync messages from back stage to main stage.

For double-buffer queues, this moves messages from the back stage (where they arrive) to the main stage (where they can be consumed). This is typically called by the framework before operator execution, but may be needed for conditions that check queue state before the operator is scheduled.

**Returns:** Success if the sync completed, or an error otherwise.

### resource\_type \[#resourcetype]

```cpp showLineNumbers={false}
ResourceType holoscan::Resource::resource_type() const
```

Get the resource type.

**Returns:** The resource type.

### name \[#name]

#### Set the name of the resource (1)

```cpp showLineNumbers={false}
Resource & holoscan::Resource::name(
    const std::string &name
) &
```

Set the name of the resource.

**Returns:** The reference to the resource.

**Parameters**

**`name`** `const std::string &`

The name of the resource.

---

#### Set the name of the resource (2)

```cpp showLineNumbers={false}
Resource && holoscan::Resource::name(
    const std::string &name
) &&
```

Set the name of the resource.

**Returns:** The reference to the resource.

**Parameters**

**`name`** `const std::string &`

The name of the resource.

---

#### Const

const

```cpp showLineNumbers={false}
const std::string & holoscan::ComponentBase::name() const
```

Get the name of the component.

**Returns:** The name of the component.

### fragment \[#fragment]

#### Set the fragment of the resource

```cpp showLineNumbers={false}
Resource & holoscan::Resource::fragment(
    Fragment *fragment
)
```

Set the fragment of the resource.

**Returns:** The reference to the resource.

**Parameters**

**`fragment`** `Fragment *`

The pointer to the fragment of the resource.

---

#### Get a pointer to \[Fragment]\(fragment) object

```cpp showLineNumbers={false}
Fragment * holoscan::ComponentBase::fragment()
```

Get a pointer to [Fragment](fragment) object.

**Returns:** The Pointer to [Fragment](fragment) object.

#### Const

const

```cpp showLineNumbers={false}
const Fragment * holoscan::ComponentBase::fragment() const
```

Get a const pointer to [Fragment](fragment) object.

**Returns:** The const pointer to [Fragment](fragment) object.

### spec \[#spec]

#### Set the component specification to the resource

```cpp showLineNumbers={false}
Resource & holoscan::Resource::spec(
    const std::shared_ptr<ComponentSpec> &spec
)
```

Set the component specification to the resource.

**Returns:** The reference to the resource.

**Parameters**

**`spec`** `const std::shared_ptr<ComponentSpec> &`

The component specification.

---

#### Get the component specification of the resource

```cpp showLineNumbers={false}
ComponentSpec * holoscan::Resource::spec()
```

Get the component specification of the resource.

**Returns:** The pointer to the component specification.

### spec\_shared \[#specshared]

```cpp showLineNumbers={false}
std::shared_ptr<ComponentSpec> holoscan::Resource::spec_shared()
```

Get the shared pointer to the component spec.

**Returns:** The shared pointer to the component spec.

### id \[#id]

```cpp showLineNumbers={false}
int64_t holoscan::ComponentBase::id() const
```

Get the identifier of the component.

By default, the identifier is set to -1. It is set to a valid value when the component is initialized.

With the default executor (GXFExecutor), the identifier is set to the GXF component ID.

**Returns:** The identifier of the component.

### add\_arg \[#addarg]

#### Add an argument to the component (1)

```cpp showLineNumbers={false}
void holoscan::ComponentBase::add_arg(
    const Arg &arg
)
```

Add an argument to the component.

**Parameters**

**`arg`** `const Arg &`

The argument to add.

---

#### Add an argument to the component (2)

```cpp showLineNumbers={false}
void holoscan::ComponentBase::add_arg(
    Arg &&arg
)
```

Add an argument to the component.

**Parameters**

**`arg`** `Arg &&`

The argument to add.

---

#### Add a list of arguments to the component (1)

```cpp showLineNumbers={false}
void holoscan::ComponentBase::add_arg(
    const ArgList &arg
)
```

Add a list of arguments to the component.

**Parameters**

**`arg`** `const ArgList &`

The list of arguments to add.

---

#### Add a list of arguments to the component (2)

```cpp showLineNumbers={false}
void holoscan::ComponentBase::add_arg(
    ArgList &&arg
)
```

Add a list of arguments to the component.

**Parameters**

**`arg`** `ArgList &&`

The list of arguments to add.

---

### args \[#args]

```cpp showLineNumbers={false}
std::vector<Arg> & holoscan::ComponentBase::args()
```

Get the list of arguments.

**Returns:** The vector of arguments.

### description \[#description]

```cpp showLineNumbers={false}
std::string holoscan::ComponentBase::description() const
```

Get a description of the component.

**Returns:** `YAML` string.

**See also:**
to\_yaml\_node()

### service \[#service]

```cpp showLineNumbers={false}
template <typename ServiceT = DefaultFragmentService>
std::shared_ptr<ServiceT> holoscan::ComponentBase::service(
    std::string_view id = ""
) const
```

Retrieve a registered fragment service or resource.

Retrieves a previously registered fragment service or resource by its type and optional identifier. Returns nullptr if no service/resource is found with the specified type and identifier.

Note that any changes to the service retrieval logic in this method should be synchronized with the implementation in `Fragment::service()` method to maintain consistency.

**Returns:** The shared pointer to the service/resource, or nullptr if not found or if type casting fails.

**Template parameters**

**`ServiceT`** `typename`

The type of the service/resource to retrieve. Must inherit from either [Resource](resource) or [FragmentService](fragmentservice). Defaults to [DefaultFragmentService](defaultfragmentservice) if not specified.

---

**Parameters**

**`id`** `std::string_view` — default: ""

The identifier of the service/resource. If empty, retrieves by type only.

---

### get\_service\_by\_type\_info \[#getservicebytypeinfo]

```cpp showLineNumbers={false}
std::shared_ptr<FragmentService> holoscan::ComponentBase::get_service_by_type_info(
    const std::type_info &service_type,
    std::string_view id = ""
) const
```

Retrieve a registered fragment service or resource for Python bindings.

This is a helper method for Python bindings to retrieve a service by its C++ type info.

**Returns:** The shared pointer to the base service, or nullptr if not found.

**Parameters**

**`service_type`** `const std::type_info &`

The type info of the service/resource to retrieve.

---

**`id`** `std::string_view` — default: ""

The identifier of the service/resource. If empty, retrieves by type only.

---

### gxf\_context \[#gxfcontext]

#### Mutable

```cpp showLineNumbers={false}
void holoscan::gxf::GXFComponent::gxf_context(
    gxf_context_t gxf_context
)
```

#### Const

const

```cpp showLineNumbers={false}
gxf_context_t holoscan::gxf::GXFComponent::gxf_context() const
```

### gxf\_eid \[#gxfeid]

#### Mutable

```cpp showLineNumbers={false}
void holoscan::gxf::GXFComponent::gxf_eid(
    gxf_uid_t gxf_eid
)
```

#### Const

const

```cpp showLineNumbers={false}
gxf_uid_t holoscan::gxf::GXFComponent::gxf_eid() const
```

### gxf\_tid \[#gxftid]

#### Mutable

```cpp showLineNumbers={false}
void holoscan::gxf::GXFComponent::gxf_tid(
    gxf_tid_t gxf_tid
)
```

#### Const

const

```cpp showLineNumbers={false}
gxf_tid_t holoscan::gxf::GXFComponent::gxf_tid() const
```

### gxf\_cid \[#gxfcid]

#### Mutable

```cpp showLineNumbers={false}
void holoscan::gxf::GXFComponent::gxf_cid(
    gxf_uid_t gxf_cid
)
```

#### Const

const

```cpp showLineNumbers={false}
gxf_uid_t holoscan::gxf::GXFComponent::gxf_cid() const
```

### gxf\_cname \[#gxfcname]

#### Overload 1

```cpp showLineNumbers={false}
std::string & holoscan::gxf::GXFComponent::gxf_cname()
```

#### Overload 2

```cpp showLineNumbers={false}
void holoscan::gxf::GXFComponent::gxf_cname(
    const std::string &name
)
```

### gxf\_graph\_entity \[#gxfgraphentity]

#### Overload 1

```cpp showLineNumbers={false}
std::shared_ptr<nvidia::gxf::GraphEntity> holoscan::gxf::GXFComponent::gxf_graph_entity()
```

#### Overload 2

```cpp showLineNumbers={false}
void holoscan::gxf::GXFComponent::gxf_graph_entity(
    std::shared_ptr<nvidia::gxf::GraphEntity> graph_entity
)
```

### gxf\_entity\_group\_name \[#gxfentitygroupname]

```cpp showLineNumbers={false}
std::string holoscan::gxf::GXFComponent::gxf_entity_group_name()
```

The name of the entity group this component belongs to.

### gxf\_entity\_group\_id \[#gxfentitygroupid]

```cpp showLineNumbers={false}
gxf_uid_t holoscan::gxf::GXFComponent::gxf_entity_group_id()
```

The group id of the entity group this component belongs to.

### gxf\_cptr \[#gxfcptr]

```cpp showLineNumbers={false}
void * holoscan::gxf::GXFComponent::gxf_cptr()
```

### gxf\_component \[#gxfcomponent]

```cpp showLineNumbers={false}
nvidia::gxf::Handle<nvidia::gxf::Component> holoscan::gxf::GXFComponent::gxf_component()
```

### gxf\_initialize \[#gxfinitialize]

```cpp showLineNumbers={false}
void holoscan::gxf::GXFComponent::gxf_initialize()
```

### set\_gxf\_parameter \[#setgxfparameter]

```cpp showLineNumbers={false}
void holoscan::gxf::GXFComponent::set_gxf_parameter(
    const std::string &component_name,
    const std::string &key,
    ParameterWrapper &param_wrap
)
```

Set a given parameter on the underlying GXF component.

### reset\_gxf\_graph\_entity \[#resetgxfgraphentity]

```cpp showLineNumbers={false}
void holoscan::gxf::GXFComponent::reset_gxf_graph_entity()
```

### add\_to\_graph\_entity \[#addtographentity]

#### Overload 1

virtual

```cpp showLineNumbers={false}
virtual void holoscan::gxf::GXFResource::add_to_graph_entity(
    Operator *op
)
```

#### Overload 2

```cpp showLineNumbers={false}
void holoscan::gxf::GXFResource::add_to_graph_entity(
    Fragment *fragment,
    const std::shared_ptr<nvidia::gxf::GraphEntity> &graph_entity
)
```

### to\_yaml\_node \[#toyamlnode]

```cpp showLineNumbers={false}
YAML::Node holoscan::gxf::GXFResource::to_yaml_node() const override
```

Get a `YAML` representation of the resource.

**Returns:** `YAML` node including type and specs of the resource in addition to the base component properties.

### set\_parameters \[#setparameters]

```cpp showLineNumbers={false}
void holoscan::gxf::GXFResource::set_parameters() override
```

This method is invoked by `GXFResource::initialize()`.

By overriding this method, we can modify how GXF Codelet's parameters are set from the arguments.

### handle\_dev\_id \[#handledevid]

```cpp showLineNumbers={false}
bool holoscan::gxf::GXFResource::handle_dev_id(
    std::optional<int32_t> &dev_id_value
)
```

### reset\_backend\_objects \[#resetbackendobjects]

```cpp showLineNumbers={false}
void holoscan::gxf::GXFResource::reset_backend_objects() override
```

Reset any backend-specific state.

### update\_params\_from\_args \[#updateparamsfromargs]

#### Update parameters based on the specified arguments

```cpp showLineNumbers={false}
void holoscan::Resource::update_params_from_args()
```

Update parameters based on the specified arguments.

#### Update parameters based on the specified arguments (with params)

```cpp showLineNumbers={false}
void holoscan::ComponentBase::update_params_from_args(
    std::unordered_map<std::string, ParameterWrapper> &params
)
```

Update parameters based on the specified arguments.

### service\_provider \[#serviceprovider]

```cpp showLineNumbers={false}
void holoscan::ComponentBase::service_provider(
    FragmentServiceProvider *provider
)
```

Set the service provider that owns this component.

---

## Static methods

### register\_converter \[#registerconverter]

```cpp showLineNumbers={false}
template <typename typeT>
static void holoscan::ComponentBase::register_converter()
```

Register the argument setter for the given type.

If an operator or resource has an argument with a custom type, the argument setter must be registered using this method.

The argument setter is used to set the value of the argument from the `YAML` configuration.

This method can be called in the initialization phase of the operator/resource (e.g., `initialize()`). The example below shows how to register the argument setter for the custom type (`Vec3`):

It is assumed that `YAML::convert<T>::encode` and `YAML::convert<T>::decode` are implemented for the given type. You need to specialize the `YAML::convert<>` template class.

For example, suppose that you had a `Vec3` class with the following members:

You can define the `YAML::convert<Vec3>` as follows in a '.cpp' file:

Please refer to the [yaml-cpp documentation](https://github.com/jbeder/yaml-cpp/wiki/Tutorial#converting-tofrom-native-data-types) for more details.

**Template parameters**

**`typeT`** `typename`

The type of the argument to register.

---

**Example**

```cpp showLineNumbers={false}
void MyOp::initialize() {
  register_converter<Vec3>();
}
```

**Example**

```cpp showLineNumbers={false}
struct Vec3 {
  // make sure you have overloaded operator==() for the comparison
  double x, y, z;
};
```

**Example**

```cpp showLineNumbers={false}
namespace YAML {
template<>
struct convert<Vec3> {
  static Node encode(const Vec3& rhs) {
    Node node;
    node.push_back(rhs.x);
    node.push_back(rhs.y);
    node.push_back(rhs.z);
    return node;
  }

  static bool decode(const Node& node, Vec3& rhs) {
    if(!node.IsSequence() || node.size() != 3) {
      return false;
    }

    rhs.x = node[0].as<double>();
    rhs.y = node[1].as<double>();
    rhs.z = node[2].as<double>();
    return true;
  }
};
}
```

### register\_argument\_setter \[#registerargumentsetter]

```cpp showLineNumbers={false}
template <typename typeT>
void holoscan::ComponentBase::register_argument_setter()
```

Register the argument setter for the given type.

Please refer to the documentation of `register_converter()` for more details.

**Template parameters**

**`typeT`** `typename`

The type of the argument to register.

---

---

## Types

### ResourceType

[Resource](resource) type used for the initialization of the resource.

| Name      | Value | Description      |
| --------- | ----- | ---------------- |
| `kNative` |       | Native resource. |
| `kGXF`    |       | GXF resource.    |

---

## Member variables

| Name                | Type                                                               | Description                                                                |
| ------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| `capacity_`         | `Parameter< uint64_t >`                                            |                                                                            |
| `policy_`           | `Parameter< uint64_t >`                                            |                                                                            |
| `address_`          | `Parameter< std::string >`                                         |                                                                            |
| `port_`             | `Parameter< uint32_t >`                                            |                                                                            |
| `buffer_`           | `Parameter< std::shared_ptr< holoscan::UcxSerializationBuffer > >` |                                                                            |
| `gxf_typename_`     | `std::string`                                                      | The GXF type name (used for [GXFComponentResource](gxfcomponentresource)). |
| `resource_type_`    | `ResourceType`                                                     | The type of the resource.                                                  |
| `is_initialized_`   | `bool`                                                             | Whether the resource is initialized.                                       |
| `spec_`             | `std::shared_ptr< ComponentSpec >`                                 | The component specification.                                               |
| `id_`               | `int64_t`                                                          | The ID of the component.                                                   |
| `name_`             | `std::string`                                                      | Name of the component.                                                     |
| `fragment_`         | `Fragment *`                                                       | Pointer to the fragment that owns this component.                          |
| `args_`             | `std::vector< Arg >`                                               | List of arguments.                                                         |
| `service_provider_` | `FragmentServiceProvider *`                                        | Pointer to the service provider.                                           |
| `gxf_context_`      | `gxf_context_t`                                                    |                                                                            |
| `gxf_eid_`          | `gxf_uid_t`                                                        |                                                                            |
| `gxf_tid_`          | `gxf_tid_t`                                                        |                                                                            |
| `gxf_cid_`          | `gxf_uid_t`                                                        |                                                                            |
| `gxf_graph_entity_` | `std::shared_ptr< nvidia::gxf::GraphEntity >`                      |                                                                            |
| `gxf_cname_`        | `std::string`                                                      |                                                                            |
| `gxf_component_`    | `nvidia::gxf::Handle< nvidia::gxf::Component >`                    |                                                                            |
| `gxf_cptr_`         | `void *`                                                           |                                                                            |