holoscan::HoloIpcCudaNativeBufferAdapterBase

template <typename TransportType>
class HoloIpcCudaNativeBufferAdapterBase

Shared CUDA IPC + holoipc lifecycle adapter core, parameterized on the holoipc transport.

Owns all transport-independent logic: GPU info caching, CudaTensorDescriptor conversion, CUDA IPC export/import via GXF helpers, holoipc share_pointer/acquire_pointer lifecycle, DNBX (Descriptor Native Buffer eXport) wire-format encode/decode, pending-export tracking, and deferred destruction.

Subclasses provide only the initialize() signature and ipc::Context<Transport> creation.

Threading: three threads access this object –

• GXF scheduler (export_tensor, evict_stale_exports)
• sidecar dispatch (import_tensor)
• IpcCore io_context (handle_last_release callback) exports_mutex_ protects pending_exports_, lifecycle_key_to_seq_, released_entries_.

ExportEntry destruction must happen outside both exports_mutex_ and the io_context thread because the ipc_descriptor deleter takes IpcCore::mutex_ and may re-enter the io_context. The solution is deferred destruction: handle_last_release queues entries into released_entries_; the next export_tensor call drains them on the worker thread, freeing GPU memory inline and moving ipc_descriptors to a background thread.

#include <holoscan/holoipc_cuda_native_buffer_adapter_base.hpp>

Template parameters

Inherits from: holoscan::NativeBufferProtocolAdapter (public)

Constructors

HoloIpcCudaNativeBufferAdapterBase

holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::HoloIpcCudaNativeBufferAdapterBase(
    std::string adapter_name
)

Destructor

~HoloIpcCudaNativeBufferAdapterBase

holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::~HoloIpcCudaNativeBufferAdapterBase() override

Assignment operators

operator=

HoloIpcCudaNativeBufferAdapterBase & holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::operator=(
    const HoloIpcCudaNativeBufferAdapterBase &
) = delete

Methods

shutdown

void holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::shutdown()

is_initialized

bool holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::is_initialized() const override

policy

nvidia::gxf::NativeBufferPolicy holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::policy() const

set_acquire_timeout

void holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::set_acquire_timeout(
    std::chrono::milliseconds timeout
)

set_export_ttl

void holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::set_export_ttl(
    std::chrono::milliseconds ttl
)

set_use_eager_acquire

void holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::set_use_eager_acquire(
    bool enabled
)

default_protocol_name

const std::string & holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::default_protocol_name() const override

supports_protocol

bool holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::supports_protocol(
    const std::string &protocol_name
) const override

can_export_tensor

bool holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::can_export_tensor(
    const nvidia::gxf::Tensor &tensor
) const override

descriptor_format_version

uint8_t holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::descriptor_format_version() const override

export_tensor

nvidia::gxf::Expected<std::vector<uint8_t>> holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::export_tensor(
    void *device_ptr,
    const std::shared_ptr<void> &device_ptr_owner,
    const NativeTensorMetadata &tensor_info,
    const std::string &protocol_name,
    uint32_t sequence_num
) override

import_tensor_generic

nvidia::gxf::Expected<ImportedNativeTensor> holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::import_tensor_generic(
    const std::vector<uint8_t> &descriptor_bytes,
    const std::string &protocol_name,
    std::chrono::milliseconds timeout = std::chrono::milliseconds{0}
) override

NativeBufferProtocolAdapter interface: delegates to import_tensor() and converts the NativeBufferHolder into a generic ImportedNativeTensor.

import_tensor

nvidia::gxf::Expected<NativeBufferHolder> holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::import_tensor(
    const std::vector<uint8_t> &descriptor_bytes,
    std::chrono::milliseconds timeout = std::chrono::milliseconds{0}
)

Decode a DNBX payload and acquire the CUDA IPC mapping via holoipc.

In strict mode (default): sends ACQUIRED, waits for ACK, then opens handle. In eager mode: opens handle locally first, then sends ACQUIRED (no ACK wait). Returns an RAII NativeBufferHolder whose destruction sends RELEASED.

pending_export_count

size_t holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::pending_export_count() const override

set_on_pending_export_count_changed

void holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::set_on_pending_export_count_changed(
    PendingExportCountChangedCallback callback
) override

evict_stale_exports

size_t holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::evict_stale_exports(
    std::chrono::milliseconds max_age
)

initialize_common

nvidia::gxf::Expected<void> holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::initialize_common(
    std::shared_ptr<IpcContextType> ipc_context,
    nvidia::gxf::NativeBufferPolicy policy
)

Called by derived-class initialize() after creating the ipc::Context.

append_bytes

template <typename T>
static void holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::append_bytes(
    std::vector<uint8_t> &out,
    const T &value
)

append_buffer

static void holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::append_buffer(
    std::vector<uint8_t> &out,
    const uint8_t *data,
    size_t sz
)

encode_exported_tensor

static nvidia::gxf::Expected<std::vector<uint8_t>> holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::encode_exported_tensor(
    const nvidia::gxf::CudaIpcDescriptor &gxf_descriptor,
    const PointerDescriptorType &ipc_descriptor
)

Serialize GXF CudaIpcDescriptor + holoipc lifecycle metadata into DNBX wire format.

ensure_gpu_info_initialized

void holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::ensure_gpu_info_initialized()

handle_last_release

void holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::handle_last_release(
    const ipc::Key &key
)

holoipc on_last_release callback (runs on io_context thread).

Moves the released entry to released_entries_ for deferred destruction; must not destroy ExportEntry here (would deadlock the io_context).

evict_stale_exports_locked

size_t holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::evict_stale_exports_locked(
    std::chrono::milliseconds max_age,
    std::vector<ExportEntry> &deferred_destroy
)

Move exports older than max_age into deferred_destroy. Caller holds exports_mutex_.

cleanup_exports

void holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::cleanup_exports(
    std::chrono::milliseconds shutdown_grace_period
)

Drain all pending exports during shutdown, waiting up to shutdown_grace_period for subscribers to send RELEASED before force-evicting.

Static methods

decode_exported_tensor

static nvidia::gxf::Expected<ExportedTensorDescriptor> holoscan::HoloIpcCudaNativeBufferAdapterBase<TransportType>::decode_exported_tensor(
    const std::vector<uint8_t> &descriptor_bytes
)

Types

Typedefs

Member variables

Inner classes

NativeBufferHolder

struct holoscan::HoloIpcCudaNativeBufferAdapterBase::NativeBufferHolder

RAII holder for a lifecycle-managed CUDA IPC mapping.

ExportedTensorDescriptor

struct holoscan::HoloIpcCudaNativeBufferAdapterBase::ExportedTensorDescriptor

Decoded DNBX payload: GXF CUDA IPC descriptor + holoipc lifecycle metadata.

ExportEntry

struct holoscan::HoloIpcCudaNativeBufferAdapterBase::ExportEntry

Tracks a single exported tensor for lifecycle management.

Holds the holoipc descriptor (controls RELEASED on drop), the GPU memory owner (prevents cudaFree while subscribers hold the mapping), and timing for TTL eviction.