holoscan::FastDdsEndpoint

Beta

Endpoint implementation for DDS serialization.

This class implements the holoscan::Endpoint interface to enable serialization/deserialization to/from a byte buffer, which can then be used with DDS DataWriter/DataReader.

Two write-mode storage options are provided:

Vector mode: backed by a std::vector<uint8_t> that grows automatically.
Raw-buffer mode: backed by a caller-supplied fixed-size uint8_t* buffer; writes that would exceed the buffer size fail instead of growing.

Read mode always operates over a const std::vector<uint8_t>*.

#include <holoscan/fastdds_endpoint.hpp>

Inherits from: holoscan::Endpoint (public)

Constructors

FastDdsEndpoint

From raw pointer (with output buffer)

Overload 2

From raw pointer (with input buffer)

Move

Copy (deleted)

explicit

holoscan::FastDdsEndpoint::FastDdsEndpoint(holoscan::FastDdsEndpoint::FastDdsEndpoint(
    std::vector<uint8_t> *output_buffer
)

Construct a FastDdsEndpoint in write mode.

Data will be appended to the output buffer.

Throws: std::invalid_argument if output_buffer is nullptr

Parameters

output_buffer

std::vector<uint8_t> *

Non-null pointer to the output buffer. Buffer is NOT cleared; data is appended.

Destructor

~FastDdsEndpoint

holoscan::FastDdsEndpoint::~FastDdsEndpoint() override = defaultholoscan::FastDdsEndpoint::~FastDdsEndpoint() override = default

Default destructor.

Assignment operators

operator=

Move assign

Copy assign (deleted)

FastDdsEndpoint & holoscan::FastDdsEndpoint::operator=(FastDdsEndpoint & holoscan::FastDdsEndpoint::operator=(
    FastDdsEndpoint &&
) = default

Methods

is_write_available

bool holoscan::FastDdsEndpoint::is_write_available() override

Check if write operations are available.

Returns: true if constructed in write mode with valid buffer

is_read_available

bool holoscan::FastDdsEndpoint::is_read_available() override

Check if read operations are available.

Returns: true if constructed in read mode with data remaining

write

expected<size_t, RuntimeError> holoscan::FastDdsEndpoint::write(expected<size_t, RuntimeError> holoscan::FastDdsEndpoint::write(
    const void *data,
    size_t size
) override

Write data to the buffer.

Appends the specified data to the output buffer.

Returns: Number of bytes written, or error if in read mode

Parameters

data

const void *

Pointer to data to write

size

size_t

Number of bytes to write

read

expected<size_t, RuntimeError> holoscan::FastDdsEndpoint::read(expected<size_t, RuntimeError> holoscan::FastDdsEndpoint::read(
    void *data,
    size_t size
) override

Read data from the buffer.

Reads data from the current position and advances the read position.

Returns: Number of bytes read, or error if insufficient data or in write mode

Parameters

data

void *

Pointer to destination buffer

size

size_t

Number of bytes to read

write_ptr

expected<void, RuntimeError> holoscan::FastDdsEndpoint::write_ptr(expected<void, RuntimeError> holoscan::FastDdsEndpoint::write_ptr(
    const void *pointer,
    size_t size,
    holoscan::MemoryStorageType type
) override

Write a pointer reference for zero-copy support.

For DDS, GPU device memory cannot be sent directly. This method fails for kDevice memory — the caller must stage device data to host memory before serialization. kCudaManaged memory is accepted (with a warning to ensure GPU operations are complete), and kHost/kSystem memory is written directly via write().

Returns: Success for host/system/managed memory, error for device memory

Parameters

pointer

const void *

Pointer to data

size

size_t

Size of data in bytes

type

holoscan::MemoryStorageType

Memory storage type (host, device, system, cuda_managed)

reset_read_position

void holoscan::FastDdsEndpoint::reset_read_position()

Reset the read position to the beginning.

Allows re-reading the buffer from the start. Only valid in read mode.

read_position

size_t holoscan::FastDdsEndpoint::read_position() const

Get the current read position.

Returns: Current read position (0 in write mode)

size

size_t holoscan::FastDdsEndpoint::size() const

Get the total bytes written (write mode) or buffer size (read mode).

Returns: Total size in bytes

bytes_remaining

size_t holoscan::FastDdsEndpoint::bytes_remaining() const

Get remaining bytes available for reading.

Returns: Bytes remaining (0 in write mode)

bytes_written

size_t holoscan::FastDdsEndpoint::bytes_written() const

Get the number of bytes written (raw buffer mode).

Returns: Bytes written in raw buffer mode, or vector size in vector mode, or 0.

is_write_mode

bool holoscan::FastDdsEndpoint::is_write_mode() const

Check if in write mode.

Returns: true if constructed with output buffer (vector or raw)

is_read_mode

bool holoscan::FastDdsEndpoint::is_read_mode() const

Check if in read mode.

Returns: true if constructed with input buffer

write_trivial_type

template <typename T>
expected<size_t, RuntimeError> holoscan::FastDdsEndpoint::write_trivial_type(expected<size_t, RuntimeError> holoscan::FastDdsEndpoint::write_trivial_type(
    const T *object
)

read_trivial_type

template <typename T>
expected<size_t, RuntimeError> holoscan::FastDdsEndpoint::read_trivial_type(expected<size_t, RuntimeError> holoscan::FastDdsEndpoint::read_trivial_type(
    T *object
)

resource_type

ResourceType holoscan::Resource::resource_type() const

Get the resource type.

Returns: The resource type.

name

Set the name of the resource (1)

Set the name of the resource (2)

Const

Resource & holoscan::Resource::name(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.

fragment

Set the fragment of the resource

Get a pointer to Fragment object

Const

Resource & holoscan::Resource::fragment(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.

spec

Set the component specification to the resource

Get the component specification of the resource

Resource & holoscan::Resource::spec(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.

spec_shared

std::shared_ptr<ComponentSpec> holoscan::Resource::spec_shared()

Get the shared pointer to the component spec.

Returns: The shared pointer to the component spec.

setup

virtual void holoscan::Resource::setup(
    ComponentSpec &spec
)

Define the resource specification.

Parameters

spec

ComponentSpec &

The reference to the component specification.

initialize

void holoscan::Resource::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.

to_yaml_node

YAML::Node holoscan::Resource::to_yaml_node() const override

Get a YAML representation of the resource.

Returns: YAML node including spec of the resource in addition to the base component properties.

set_parameters

void holoscan::Resource::set_parameters() override

Set the parameters based on defaults (sets GXF parameters for GXF components).

id

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

Add an argument to the component (1)

Add an argument to the component (2)

Add a list of arguments to the component (1)

Add a list of arguments to the component (2)

void holoscan::ComponentBase::add_arg(
    const Arg &arg
)

Add an argument to the component.

Parameters

arg

const Arg &

The argument to add.

args

std::vector<Arg> & holoscan::ComponentBase::args()

Get the list of arguments.

Returns: The vector of arguments.

description

std::string holoscan::ComponentBase::description() const

Get a description of the component.

Returns: YAML string.

See also: to_yaml_node()

service

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 or FragmentService. Defaults to DefaultFragmentService if not specified.

Parameters

std::string_viewDefaults to ""

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

get_service_by_type_info

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.

std::string_viewDefaults to ""

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

reset_backend_objects

virtual void holoscan::ComponentBase::reset_backend_objects()

Reset any backend-specific objects (e.g. GXF GraphEntity).

update_params_from_args

Update parameters based on the specified arguments

Update parameters based on the specified arguments (with params)

void holoscan::Resource::update_params_from_args()

Update parameters based on the specified arguments.

service_provider

void holoscan::ComponentBase::service_provider(
    FragmentServiceProvider *provider
)

Set the service provider that owns this component.

Static methods

register_converter

template <typename typeT>
static void holoscan::ComponentBase::register_converter()

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 for more details.

Template parameters

typeT

typename

The type of the argument to register.

Example

void MyOp::initialize() {
  register_converter<Vec3>();
}

Example

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

Example

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

template <typename typeT>
void holoscan::ComponentBase::register_argument_setter()

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 type used for the initialization of the resource.

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

Member variables

Name	Type	Description
`output_buffer_`	`std::vector< uint8_t > *`	Write mode buffer (non-owning, vector).
`raw_output_buffer_`	`uint8_t *`	Write mode buffer (non-owning, raw).
`raw_buffer_size_`	`size_t`	Raw buffer capacity.
`write_position_`	`size_t`	Current write position (raw buffer mode).
`input_buffer_`	`const std::vector< uint8_t > *`	Read mode buffer (non-owning).
`read_position_`	`size_t`	Current read position.
`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.