> This page is for version 3.0 (Latest) (default). > For other versions, use one of these documentation indexes: > - 3.0 (Latest) (default): https://docs.nvidia.com/holoscan/sensor-bridge/3-0/llms.txt > - 2.7: https://docs.nvidia.com/holoscan/sensor-bridge/2-7/llms.txt > - Archives: https://docs.nvidia.com/holoscan/sensor-bridge/archives/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/holoscan/sensor-bridge/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/holoscan/sensor-bridge/_mcp/server. # hololink::module::RoceReceiverInterfaceV2 > RoceReceiverInterfaceV1, plus whether the receive path has failed. [RoceReceiverInterfaceV1](rocereceiverinterfacev1), plus whether the receive path has failed. A fatal event on the network adapter (a completion queue or queue pair error, or the device failing) stops a RoCE receiver for good: no frame arrives until it is started again. Through [RoceReceiverInterfaceV1](rocereceiverinterfacev1) alone, that looks like a receiver that is merely waiting for frames. The receivers this module provides publish this interface next to [RoceReceiverInterfaceV1](rocereceiverinterfacev1). Resolve it with `allow_null` and fall back to [RoceReceiverInterfaceV1](rocereceiverinterfacev1) for a module that doesn't publish it. ```cpp showLineNumbers={false} #include ``` **Inherits from:** `hololink::module::RoceReceiverInterfaceV1` (public), `hololink::module::Service< RoceReceiverInterfaceV2 >` (public) --- ## Methods ### receive_path_failed \[#receivepathfailed] ```cpp showLineNumbers={false} virtual bool hololink::module::RoceReceiverInterfaceV2::receive_path_failed() ``` Whether a fatal event has stopped the receive path. get_next_frame() then returns false at once, and frames_ready() returns true so that a caller waiting for it isn't left waiting. No frame arrives until start() is called again. **Returns:** True once the receive path has failed. ### start \[#start] ```cpp showLineNumbers={false} virtual hololink_module_status_t hololink::module::RoceReceiverInterfaceV2::start( const std::string &ibv_name, unsigned ibv_port, uint64_t cu_buffer, size_t cu_buffer_size, size_t cu_frame_size, size_t cu_page_size, unsigned pages, size_t metadata_offset, const std::string &peer_ip, unsigned queue_size ) ``` Configure the receiver and network adapter for RDMA. Frames are delivered into `cu_buffer`, which is a single contiguous region with enough space to accommodate the total number of frames indicated by the [`pages`](rocereceiverinterfacev1#pages) parameter; each frame is `cu_page_size` bytes apart; `cu_page_size` needs to include space for received frame metadata (and its alignment). **Returns:** HOLOLINK_MODULE_OK or an error status. **Throws:** `std::runtime_error` if the receiver cannot be brought up, for example the named device is not found or `peer_ip` is not a valid address. **Parameters** **`ibv_name`** `const std::string &` Name of the InfiniBand verbs device of the network adapter that receives the frames, e.g. "roceP5p3s0f0". --- **`ibv_port`** `unsigned` Port of that device to use. --- **`cu_buffer`** `uint64_t` CUDA memory frames are delivered into, as a CUdeviceptr. --- **`cu_buffer_size`** `size_t` Bytes available at `cu_buffer`. --- **`cu_frame_size`** `size_t` Bytes of frame data expected for each received data frame: the HSB device is programmed to trigger an end-of-frame when this many bytes are received; but an earlier TLAST signal will trigger end-of-frame at an earlier point. --- **`cu_page_size`** `size_t` Bytes from one page to the next. --- **`pages`** `unsigned` Pages the device cycles through. --- **`metadata_offset`** `size_t` Offset, in bytes from the start of a page, of the metadata block the device writes after the frame data. --- **`peer_ip`** `const std::string &` IPv4 address of the device, in dotted-decimal form. The receiver accepts data only from this address. --- **`queue_size`** `unsigned` Completed frames the receiver holds while the application is busy with an earlier one. When a frame completes with this many already waiting, the oldest waiting frame is discarded (see RoceReceiverFrameInfoV1::dropped). --- ### close \[#close] ```cpp showLineNumbers={false} virtual void hololink::module::RoceReceiverInterfaceV2::close() ``` End the run, returning blocking_monitor() to its caller. Callable from any thread, including while blocking_monitor() runs. Does nothing if the receiver was never started. ### blocking_monitor \[#blockingmonitor] ```cpp showLineNumbers={false} virtual void hololink::module::RoceReceiverInterfaceV2::blocking_monitor() ``` Run the receiver until close() is called. Frames arrive only while this runs, so it gets a thread of its own, and that thread carries the CUDA context the receiver was started with. Clients typically execute this in its own thread. **Throws:** `std::runtime_error` if start() has not been called. ### get_next_frame \[#getnextframe] ```cpp showLineNumbers={false} virtual bool hololink::module::RoceReceiverInterfaceV2::get_next_frame( unsigned timeout_ms, RoceReceiverFrameInfoV1 &info ) ``` Take the next completed frame. Waits up to `timeout_ms` for a frame. On successful reception of a frame, `info` is updated with various metadata about the data, which is present at the indicated address within the `cu_buffer` passed to [`start`](rocereceiverinterfacev1#start). Frames are returned in the order they are received. **Returns:** True when a frame was taken; false when the timeout elapsed first. **Throws:** `std::runtime_error` if start() has not been called. **Parameters** **`timeout_ms`** `unsigned` How long to wait for a frame, in milliseconds. --- **`info`** `RoceReceiverFrameInfoV1 &` Describes the frame that was taken. --- ### frames_ready \[#framesready] ```cpp showLineNumbers={false} virtual bool hololink::module::RoceReceiverInterfaceV2::frames_ready() ``` **Returns:** False when get_next_frame() will block waiting for a new frame to arrive. ### set_frame_ready \[#setframeready] ```cpp showLineNumbers={false} virtual void hololink::module::RoceReceiverInterfaceV2::set_frame_ready( std::function callback ) ``` Register a callback run each time a frame becomes available. An application that cannot afford to wait in get_next_frame() is told from here that a frame is waiting, and takes it when it is ready to. The callback runs on the thread running blocking_monitor(). Register it before that starts; pass an empty std::function to stop being called. It stays registered across calls to start(). **Parameters** **`callback`** `std::function` Run once per frame that becomes available. --- ### get_qp_number \[#getqpnumber] ```cpp showLineNumbers={false} virtual uint32_t hololink::module::RoceReceiverInterfaceV2::get_qp_number() ``` The number of the queue pair that receives this channel's frames. The channel programs this into the device so it sends to the right queue pair. **Returns:** The number. Only meaningful once start() has run. **Throws:** `std::runtime_error` if start() has not been called. ### get_rkey \[#getrkey] ```cpp showLineNumbers={false} virtual uint32_t hololink::module::RoceReceiverInterfaceV2::get_rkey() ``` The key the device presents when it writes a frame into the receiver's memory. **Returns:** The key. Only meaningful once start() has run. **Throws:** `std::runtime_error` if start() has not been called. ### external_frame_memory \[#externalframememory] ```cpp showLineNumbers={false} virtual uint64_t hololink::module::RoceReceiverInterfaceV2::external_frame_memory() ``` The address, in the device's view of the receiver's memory, where the first page begins. The device addresses page `n` at this value plus `n` times page_size(). This is not a CUDA address. **Returns:** The address. Only meaningful once start() has run. **Throws:** `std::runtime_error` if start() has not been called. ### frame_size \[#framesize] ```cpp showLineNumbers={false} virtual size_t hololink::module::RoceReceiverInterfaceV2::frame_size() ``` Bytes of frame data the device sends per frame. **Returns:** The `cu_frame_size` start() was given. ### page_size \[#pagesize] ```cpp showLineNumbers={false} virtual size_t hololink::module::RoceReceiverInterfaceV2::page_size() ``` Bytes from one page to the next. **Returns:** The `cu_page_size` start() was given. ### pages \[#pages] ```cpp showLineNumbers={false} virtual unsigned hololink::module::RoceReceiverInterfaceV2::pages() ``` Pages the device cycles through. **Returns:** The [`pages`](rocereceiverinterfacev1#pages) start() was given. ### configure \[#configure] ```cpp showLineNumbers={false} virtual void hololink::module::ConfigurableService::configure( const EnumerationMetadata & ) ``` Use `metadata` contents to initialize this instance. This routine is guaranteed to be called the first time a call to get_service(metadata) is called on a specific service instance. ### module \[#module] #### Const (1) ```cpp showLineNumbers={false} std::shared_ptr hololink::module::ServiceBase::module() const ``` The [Module](module) that this service was published from. The service holds no strong reference to its [Module](module), so this does not extend the [Module](module)'s lifetime. **Returns:** The owning [Module](module), or an empty pointer if the service has not been published or its [Module](module) no longer exists. #### Const (2) ```cpp showLineNumbers={false} std::shared_ptr hololink::module::ServiceBase::module() const ``` The [Module](module) that this service was published from. The service holds no strong reference to its [Module](module), so this does not extend the [Module](module)'s lifetime. **Returns:** The owning [Module](module), or an empty pointer if the service has not been published or its [Module](module) no longer exists. --- ## Static methods ### get_service \[#getservice] #### Fetch the receiver for a data channel ```cpp showLineNumbers={false} static std::shared_ptr hololink::module::RoceReceiverInterfaceV2::get_service( const EnumerationMetadata &metadata, bool allow_null = false ) ``` Fetch the receiver for a data channel, as RoceReceiverInterfaceV1::get_service(metadata) does. **Returns:** The receiver, configured by `metadata` on first use. **Throws:** `std::runtime_error` when allow_null is false and the receiver cannot be resolved. **Parameters** **`metadata`** `const EnumerationMetadata &` Enumeration metadata naming the data channel. --- **`allow_null`** `bool` — default: false Use `true` to return nullptr when the module doesn't provide this interface; the default `false` raises a std::runtime_error. --- #### Overload 2 ```cpp showLineNumbers={false} static std::shared_ptr hololink::module::Service::get_service( std::shared_ptr module, const char *instance_id, bool allow_null = false ) ``` Type-safe way to fetch a std::shared_ptr to an instance of \ from a [Module](module). Note that [Module](module) usually caches instances, it's likely that calls to get_service with the same locator_id will return pointers to the same implementation object. **Returns:** A shared pointer to the service instance. **Parameters** **`module`** `std::shared_ptr` Is the shared object that owns the instance we wish to fetch --- **`instance_id`** `const char *` Names the specific object, usually expressed as a set of "name=value;..." pairs, as defined by the implementations themselves. This name is normally fetched by calling `Derived::locator_id(enumeration_metadata)`. --- **`allow_null`** `bool` — default: false The default value of `false` causes this routine to throw a std::runtime_error if the service cannot be found within the module; this would be expected to terminate the calling program. If the application wants to handle the error, pass in `true` here and get_service will return `nullptr` when this module doesn't provide the requested service. --- #### Overload 3 ```cpp showLineNumbers={false} static std::shared_ptr hololink::module::Service::get_service( std::shared_ptr module, const char *instance_id, bool allow_null = false ) ``` Type-safe way to fetch a std::shared_ptr to an instance of \ from a [Module](module). Note that [Module](module) usually caches instances, it's likely that calls to get_service with the same locator_id will return pointers to the same implementation object. **Returns:** A shared pointer to the service instance. **Parameters** **`module`** `std::shared_ptr` Is the shared object that owns the instance we wish to fetch --- **`instance_id`** `const char *` Names the specific object, usually expressed as a set of "name=value;..." pairs, as defined by the implementations themselves. This name is normally fetched by calling `Derived::locator_id(enumeration_metadata)`. --- **`allow_null`** `bool` — default: false The default value of `false` causes this routine to throw a std::runtime_error if the service cannot be found within the module; this would be expected to terminate the calling program. If the application wants to handle the error, pass in `true` here and get_service will return `nullptr` when this module doesn't provide the requested service. --- ### for_each_type_id \[#foreachtypeid] #### Overload 1 ```cpp showLineNumbers={false} static bool hololink::module::Service::for_each_type_id( Callback &&cb ) ``` Iterate over every type_id supported by this instance. The callback signature is `bool(const char*)` — returning false halts the walk; true continues. Iteration is depth-first, so you'll see the most specific implementation types first. #### Overload 2 ```cpp showLineNumbers={false} static bool hololink::module::Service::for_each_type_id( Callback &&cb ) ``` Iterate over every type_id supported by this instance. The callback signature is `bool(const char*)` — returning false halts the walk; true continues. Iteration is depth-first, so you'll see the most specific implementation types first.