Skip to content

api/transport_registry.h

Namespaces

Name
cvedia
cvedia::rt
API for controlling the server and lifecycle management of runtime instances.
cvedia::rt::api
cvedia::rt::api::transport

Classes

Name
struct cvedia::rt::api::transport::TransportInfo
Transport information structure.
struct cvedia::rt::api::transport::PluginSupport
Aggregated per-plugin entry for a transport URI.

Types

Name
enum class PluginKind { Other = 0, Decoder, Encoder, Inference}
Declare plugin support for a transport URI.

Functions

Name
void registerTransportPlugin(std::unique_ptr< iface::TransportPlugin > plugin)
Register a transport plugin.
void declareSupportForUri(std::string const & pluginId, std::string const & transportUri, std::string const & pluginDescription ="", bool isZeroCopy =true, PluginKind kind =PluginKind::Other)
std::optional< std::string > identifyDevice(void * handle, iface::NativeHandleType type)
Identify transport URI from a native API handle.
bool isSamePhysicalDevice(std::string const & uri1, std::string const & uri2)
Check if two transport URIs refer to the same physical device.
std::vector< std::string > getTransportUrisForDevice(std::string const & anyUri)
Get all transport URIs for a physical device.
std::vector< std::string > getAvailableSchemes()
Get all available transport schemes.
std::vector< TransportInfo > getAllTransports()
Get all registered transports.
std::vector< TransportInfo > getTransportsForScheme(std::string const & scheme, std::string const & targetInteropScheme ="")
Get transports for a specific scheme.
bool hasTransportsForScheme(std::string const & scheme)
Check whether a scheme currently provides at least one transport.
std::vector< std::string > getPluginsSupportingUri(std::string const & uri)
Get plugins supporting a transport URI.
std::vector< PluginSupport > getPluginSupportForUri(std::string const & uri)
Get full plugin-support entries (id + kind + description + zeroCopy) for a URI.
std::string getPluginDescription(std::string const & pluginId)
Get description for a plugin ID.
bool isZeroCopySupport(std::string const & uri, std::string const & pluginId)
Check if a plugin supports a transport URI with zero-copy.
void declareBackendHandlesScheme(std::string const & backendName, std::string const & scheme)
Declare buffer backend handles a transport scheme.
void declareSchemeInterop(std::string const & backendName, std::string const & sourceScheme, std::string const & targetScheme, bool requiresSameDevice)
Declare interop capability between two transport schemes.
bool isValidTransportUri(std::string const & transportUri)
Check if transport URI is valid and registered.
std::optional< std::string > getUriScheme(std::string const & transportUri)
Extract scheme from transport URI.
std::optional< std::string > getBackendForUri(std::string const & transportUri)
Get buffer backend for a transport URI.
std::vector< std::pair< std::string, std::string > > getInteropPaths(std::string const & sourceUri)
Get interop paths available from a transport URI.
std::shared_ptr< void > createNativeContext(std::string const & transportUri, iface::NativeHandleType type)
Create a new native context handle for a transport URI.
void setNativeContext(std::string const & transportUri, iface::NativeHandleType type, std::shared_ptr< void > handle)
Store (or replace) the shared native context handle for a transport URI.
void clearNativeContext(std::string const & transportUri, iface::NativeHandleType type)
Remove the native context handle entry for a transport URI.
std::recursive_mutex & nativeContextMutex(std::string const & transportUri)
Serialize all access to the single shared native context for a URI.
std::mutex & nativeSubmissionMutex(std::string const & transportUri)
Serialize native API command submission across plugin modules.

Types Documentation

enum PluginKind

Enumerator Value Description
Other 0
Decoder
Encoder
Inference

Declare plugin support for a transport URI.

Parameters:

  • pluginId Plugin identifier (e.g., "nvidia.nvdec", "tensorrt", "intel.vpl")
  • transportUri Transport URI the plugin supports (e.g., "cuda://0")

Called by decoder/inference/processing plugins to declare which transport URIs they support. This information is used to visualize zero-copy opportunities and track data transfers.

Example usage in NVDEC decoder: 

NvidiaVideoDecoder::NvidiaVideoDecoder(...) {
    // ... create CUDA context ...
    auto uri = api::transport::identifyDevice(context,
                                              NativeHandleType::CUDA_CONTEXT);
    if (uri) {
        api::transport::declareSupportForUri("nvidia.nvdec", *uri);
    }
}

Thread-safe. Multiple plugins can declare support concurrently.

Functional role of a plugin in the transport ledger.

Two subplugins that target the same device (e.g. Blaize decoder and Blaize inference engine) may share the same pluginId (e.g. "blaize.1") because it identifies the device, not the capability. PluginKind disambiguates them in the ledger so both show up on the same URI without colliding.

Functions Documentation

function registerTransportPlugin

void registerTransportPlugin(
    std::unique_ptr< iface::TransportPlugin > plugin
)

Register a transport plugin.

Parameters:

  • plugin Unique pointer to transport plugin implementation

Called by transport plugins during their registerHandler() function. The plugin is stored and its transports are enumerated immediately.

Example usage in TransportCUDA plugin: 

extern "C" EXPORT void registerHandler() {
    auto plugin = std::make_unique<TransportCUDA>();
    api::transport::registerTransportPlugin(std::move(plugin));
}

Thread-safe. Can be called from multiple plugin loaders concurrently.

function declareSupportForUri

void declareSupportForUri(
    std::string const & pluginId,
    std::string const & transportUri,
    std::string const & pluginDescription ="",
    bool isZeroCopy =true,
    PluginKind kind =PluginKind::Other
)

function identifyDevice

std::optional< std::string > identifyDevice(
    void * handle,
    iface::NativeHandleType type
)

Identify transport URI from a native API handle.

Parameters:

  • handle Pointer to native API handle
  • type Type of the native handle

Return: Transport URI if identified, std::nullopt otherwise

Queries all registered transport plugins to identify which transport URI corresponds to the given native handle. Used by plugins to discover their transport URI without manually tracking device indices.

Example usage in TensorRT: 

TrtCore::loadBackend() {
    cudaSetDevice(deviceID_);

    auto uri = api::transport::identifyDevice(&deviceID_,
                                              NativeHandleType::CUDA_DEVICE);
    if (uri) {
        api::transport::declareSupportForUri("tensorrt", *uri);
    }
}

Thread-safe.

function isSamePhysicalDevice

bool isSamePhysicalDevice(
    std::string const & uri1,
    std::string const & uri2
)

Check if two transport URIs refer to the same physical device.

Parameters:

  • uri1 First transport URI
  • uri2 Second transport URI

Return: true if both URIs refer to the same physical device, false otherwise

Uses physical device identifiers to match devices across different APIs. Matching priority: UUID > PCI Address > LUID > Vendor+Device ID

Example: 

bool sameDevice = api::transport::isSamePhysicalDevice("cuda://0",
                                                        "opencl://0-0");
// Returns true if both are NVIDIA GPU on PCI bus 0000:01:00.0

Used for:

  • Detecting zero-copy opportunities between plugins
  • Buffer interop capability checking
  • Device topology visualization Thread-safe.

function getTransportUrisForDevice

std::vector< std::string > getTransportUrisForDevice(
    std::string const & anyUri
)

Get all transport URIs for a physical device.

Parameters:

  • anyUri Any transport URI for the device

Return: Vector of all transport URIs referring to the same physical device

Example: 

auto uris = api::transport::getTransportUrisForDevice("cuda://0");
// Might return: ["cuda://0", "opencl://0-0", "d3d11://0"]

Used for visualizing multi-API access to same device.

Thread-safe.

function getAvailableSchemes

std::vector< std::string > getAvailableSchemes()

Get all available transport schemes.

Return: Vector of scheme names (e.g., ["cpu", "cuda", "opencl"])

Used by rtcmd for tab-completion and filtering.

Thread-safe.

function getAllTransports

std::vector< TransportInfo > getAllTransports()

Get all registered transports.

Return: Vector of TransportInfo for all registered transport URIs

Used by rtcmd transport command to display all available transports.

Thread-safe.

function getTransportsForScheme

std::vector< TransportInfo > getTransportsForScheme(
    std::string const & scheme,
    std::string const & targetInteropScheme =""
)

Get transports for a specific scheme.

Parameters:

  • scheme Scheme name (e.g., "cuda", "opencl")
  • targetInteropScheme Optional: only return transports capable of interop with this target scheme

Return: Vector of TransportInfo for the specified scheme

Used by rtcmd transport command with scheme filter.

Thread-safe.

function hasTransportsForScheme

inline bool hasTransportsForScheme(
    std::string const & scheme
)

Check whether a scheme currently provides at least one transport.

Parameters:

  • scheme Scheme name (e.g., "cuda", "opencl")

Return: true if at least one transport is available for the scheme

A transport plugin can be registered successfully while providing no transports, for example when its driver is installed but no usable device is available. Hardware-dependent plugins can use this check before entering their own vendor runtime during registration.

Thread-safe.

function getPluginsSupportingUri

std::vector< std::string > getPluginsSupportingUri(
    std::string const & uri
)

Get plugins supporting a transport URI.

Parameters:

  • uri Transport URI

Return: Vector of plugin IDs that declared support for this URI

Example: 

auto plugins = api::transport::getPluginsSupportingUri("cuda://0");
// Might return: ["nvidia.nvdec", "tensorrt", "opencv.cuda"]

Used by rtcmd to visualize plugin compatibility and zero-copy opportunities.

Thread-safe.

function getPluginSupportForUri

std::vector< PluginSupport > getPluginSupportForUri(
    std::string const & uri
)

Get full plugin-support entries (id + kind + description + zeroCopy) for a URI.

Prefer this over the tuple of getPluginsSupportingUri/getPluginDescription/ isZeroCopySupport when rendering the transport ledger: it preserves the (pluginId, kind) distinction so two subplugins sharing a pluginId don't collide into a single row.

function getPluginDescription

std::string getPluginDescription(
    std::string const & pluginId
)

Get description for a plugin ID.

Parameters:

  • pluginId Plugin identifier

Return: Plugin description if available, empty string otherwise

Used by rtcmd to display plugin info like "nvidia.1 (NVIDIA Decoder)"

Thread-safe.

function isZeroCopySupport

bool isZeroCopySupport(
    std::string const & uri,
    std::string const & pluginId
)

Check if a plugin supports a transport URI with zero-copy.

Parameters:

  • uri Transport URI
  • pluginId Plugin identifier

Return: true if plugin supports URI with zero-copy, false if copy required or not supported

Thread-safe.

function declareBackendHandlesScheme

void declareBackendHandlesScheme(
    std::string const & backendName,
    std::string const & scheme
)

Declare buffer backend handles a transport scheme.

Parameters:

  • backendName Buffer backend name (e.g., "BufferCpu", "BufferCuda")
  • scheme Transport scheme (e.g., "cpu", "cuda", "opencl")

Example: declareBackendHandlesScheme("BufferCuda", "cuda") This declares BufferCuda handles all cuda:// URIs (cuda://0, cuda://1, etc.)

Thread-safe.

function declareSchemeInterop

void declareSchemeInterop(
    std::string const & backendName,
    std::string const & sourceScheme,
    std::string const & targetScheme,
    bool requiresSameDevice
)

Declare interop capability between two transport schemes.

Parameters:

  • backendName Backend providing interop (e.g., "BufferOpenCL")
  • sourceScheme Source transport scheme (e.g., "d3d11")
  • targetScheme Target transport scheme (e.g., "opencl")
  • requiresSameDevice Whether interop requires same physical device

Example: declareSchemeInterop("BufferOpenCL", "d3d11", "opencl", true) This declares BufferOpenCL can convert d3d11://N ↔ opencl://M when both on same device.

Thread-safe.

function isValidTransportUri

bool isValidTransportUri(
    std::string const & transportUri
)

Check if transport URI is valid and registered.

Parameters:

  • transportUri Transport URI to validate

Return: true if URI is registered in transport registry, false otherwise

Example: 

if (api::transport::isValidTransportUri("cuda://0")) {
    // URI is available on this system
}

Thread-safe.

function getUriScheme

std::optional< std::string > getUriScheme(
    std::string const & transportUri
)

Extract scheme from transport URI.

Parameters:

  • transportUri Transport URI (e.g., "cuda://0", "opencl://0-0")

Return: Scheme string if valid URI format, nullopt otherwise

Example: "cuda://0" → "cuda", "opencl://0-0" → "opencl"

This is a pure parsing function that does NOT check if the scheme is registered. Use isValidTransportUri() to validate URI existence.

Thread-safe (no registry access).

function getBackendForUri

std::optional< std::string > getBackendForUri(
    std::string const & transportUri
)

Get buffer backend for a transport URI.

Parameters:

  • transportUri Transport URI (e.g., "cuda://0", "cpu://")

Return: Backend name if found, nullopt otherwise

Matches by URI scheme. Example: "cuda://0" → "BufferCuda"

Thread-safe.

function getInteropPaths

std::vector< std::pair< std::string, std::string > > getInteropPaths(
    std::string const & sourceUri
)

Get interop paths available from a transport URI.

Parameters:

  • sourceUri Source transport URI

Return: Vector of (target URI, backend name) pairs

Example: "d3d11://0" → [("opencl://1-0", "BufferOpenCL")] if on same Intel GPU

Applies requiresSameDevice rules automatically.

Thread-safe.

function createNativeContext

std::shared_ptr< void > createNativeContext(
    std::string const & transportUri,
    iface::NativeHandleType type
)

Create a new native context handle for a transport URI.

Creates a fresh native context (D3D11 device, OpenCL context, etc.) each time called. Contexts are reference-counted via std::shared_ptr with a custom deleter that releases the underlying native object (clReleaseContext, ID3D11Device::Release, etc.). Caller controls lifetime by holding the returned shared_ptr.

function setNativeContext

void setNativeContext(
    std::string const & transportUri,
    iface::NativeHandleType type,
    std::shared_ptr< void > handle
)

Store (or replace) the shared native context handle for a transport URI.

function clearNativeContext

void clearNativeContext(
    std::string const & transportUri,
    iface::NativeHandleType type
)

Remove the native context handle entry for a transport URI.

function nativeContextMutex

std::recursive_mutex & nativeContextMutex(
    std::string const & transportUri
)

Serialize all access to the single shared native context for a URI.

Some accelerators (e.g. the Blaize GSP) permit exactly one native context per device, so the decode buffer plugin and the inference engine share a single context published under "vx://:". Executing graphs and creating/releasing context objects on that shared context from decode and inference threads concurrently corrupts context state (intermittent garbled frames). Every operation on the shared context must be performed while holding this per-URI mutex.

The mutex is owned by the core (not by a plugin module) so a single instance is visible across the separately loaded plugin modules that share the context. Recursive, so a thread already holding it may re-enter helpers that re-acquire it. Thread-safe.

function nativeSubmissionMutex

std::mutex & nativeSubmissionMutex(
    std::string const & transportUri
)

Serialize native API command submission across plugin modules.

This mutex is owned by the core so separately loaded buffer and inference plugins can coordinate short command-submission sections for the same transport without holding the lock while device work completes.