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

> Provide device-side support for LinuxReceiver.

Provide device-side support for LinuxReceiver.

The device transmits a data channel's frames to a host socket as a stream of UDP datagrams. This receiver reassembles that stream into whole frames and delivers each one into CUDA memory the application supplies, along with a [LinuxReceiverFrameInfoV1](linuxreceiverframeinfov1) describing it. One receiver serves one data channel; [RoceReceiverInterfaceV1](rocereceiverinterfacev1) is the counterpart for channels the NIC receives without the host reading packets.

Fetch it with the [EnumerationMetadata](enumerationmetadata) describing the channel, after fetching that channel's [LinuxDataChannelInterfaceV1](linuxdatachannelinterfacev1).

The application drives the receiver:

* start() prepares the receiver over a socket the channel has already prepared, and over the CUDA buffer frames are delivered into. The values the channel programs the device with are readable once it returns, so this precedes LinuxDataChannelInterfaceV1::attach_receiver().
* blocking_monitor() runs the receiver and returns when close() is called, so it gets a thread of its own.
* get_next_frame() hands over frames as they complete; frames_ready() and set_frame_ready() tell an application when one is waiting.
* close() ends the run, and start() may then run the receiver again.

```cpp showLineNumbers={false}
#include <hololink/module/linux_receiver.hpp>
```

**Inherits from:** `hololink::module::ConfigurableService< LinuxReceiverInterfaceV1 >` (public)

---

## Methods

### start \[#start]

```cpp showLineNumbers={false}
virtual hololink_module_status_t hololink::module::LinuxReceiverInterfaceV1::start(
    int data_socket,
    uint64_t cu_buffer,
    size_t cu_buffer_size,
    size_t cu_frame_size,
    size_t cu_page_size,
    unsigned pages,
    unsigned queue_size
)
```

Prepare the receiver to run over a socket and a CUDA buffer.

Frames are delivered into `cu_buffer`, one frame at a time. The device writes each frame to one of [`pages`](#pages) pages, `cu_page_size` bytes apart, so a page holds a frame's data, the padding that aligns it, and the metadata block that follows it.

get_qp_number(), get_rkey(), local_port(), frame_size(), page_size() and pages() report what the device is programmed with once this returns, so an application calls this before LinuxDataChannelInterfaceV1::attach_receiver(). Calling it again after close() runs the receiver a second time.

**Returns:** HOLOLINK_MODULE_OK or an error status.

**Parameters**

**`data_socket`** `int`

Socket prepared by LinuxDataChannelInterfaceV1::configure_socket(). The device transmits to the port it is bound to.

---

**`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 the device sends per frame.

---

**`cu_page_size`** `size_t`

Bytes from one page to the next.

---

**`pages`** `unsigned`

Pages the device cycles through.

---

**`queue_size`** `unsigned`

Completed frames the receiver holds while the application is busy with an earlier one.

---

### close \[#close]

```cpp showLineNumbers={false}
virtual void hololink::module::LinuxReceiverInterfaceV1::close()
```

End the run, returning blocking_monitor() to its caller.

Callable from any thread, including while blocking_monitor() runs.

### blocking_monitor \[#blockingmonitor]

```cpp showLineNumbers={false}
virtual void hololink::module::LinuxReceiverInterfaceV1::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.

### get_next_frame \[#getnextframe]

```cpp showLineNumbers={false}
virtual bool hololink::module::LinuxReceiverInterfaceV1::get_next_frame(
    unsigned timeout_ms,
    LinuxReceiverFrameInfoV1 &info,
    void *cuda_stream
)
```

Take the next completed frame.

Waits up to `timeout_ms` for a frame, then delivers it into the CUDA buffer start() was given and describes it in `info`. The copy runs on `cuda_stream`, so work already queued on that stream precedes it and work queued afterwards sees the frame.

**Returns:** True when a frame was delivered; false when the timeout elapsed first.

**Parameters**

**`timeout_ms`** `unsigned`

How long to wait for a frame, in milliseconds.

---

**`info`** `LinuxReceiverFrameInfoV1 &`

Describes the frame that was delivered.

---

**`cuda_stream`** `void *`

Stream the frame is delivered on, as a CUstream.

---

### frames_ready \[#framesready]

```cpp showLineNumbers={false}
virtual bool hololink::module::LinuxReceiverInterfaceV1::frames_ready()
```

Whether a frame is waiting to be taken.

**Returns:** True when get_next_frame() has a frame to hand over; false when it would wait for one.

### set_frame_ready \[#setframeready]

```cpp showLineNumbers={false}
virtual void hololink::module::LinuxReceiverInterfaceV1::set_frame_ready(
    std::function<void()> 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.

**Parameters**

**`callback`** `std::function<void()>`

Run once per frame that becomes available.

---

### get_qp_number \[#getqpnumber]

```cpp showLineNumbers={false}
virtual uint32_t hololink::module::LinuxReceiverInterfaceV1::get_qp_number()
```

The connection number the device stamps into this channel's packets.

**Returns:** The number, once start() has run.

### get_rkey \[#getrkey]

```cpp showLineNumbers={false}
virtual uint32_t hololink::module::LinuxReceiverInterfaceV1::get_rkey()
```

The key the device presents when it writes a frame.

**Returns:** The key, once start() has run.

### local_port \[#localport]

```cpp showLineNumbers={false}
virtual uint32_t hololink::module::LinuxReceiverInterfaceV1::local_port()
```

The UDP port the device transmits this channel's frames to.

The port the socket given to start() is bound to.

**Returns:** The port, once start() has run.

### frame_size \[#framesize]

```cpp showLineNumbers={false}
virtual size_t hololink::module::LinuxReceiverInterfaceV1::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::LinuxReceiverInterfaceV1::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::LinuxReceiverInterfaceV1::pages()
```

Pages the device cycles through.

**Returns:** The [`pages`](#pages) start() was given.

### configure \[#configure]

```cpp showLineNumbers={false}
virtual void hololink::module::ConfigurableService<LinuxReceiverInterfaceV1>::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]

```cpp showLineNumbers={false}
std::shared_ptr<Module> 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 a service

```cpp showLineNumbers={false}
static std::shared_ptr<LinuxReceiverInterfaceV1> hololink::module::ConfigurableService<LinuxReceiverInterfaceV1>::get_service(
    const EnumerationMetadata &metadata,
    bool allow_null = false
)
```

Fetch a service, configured by [EnumerationMetadata](enumerationmetadata).

[Module](module) usually caches service objects; so when a specific service instance isn't found, it will be constructed with the current values in [EnumerationMetadata](enumerationmetadata). Later calls to get_service are likely to return that cached instance, ignoring changes to any enumeration metadata that aren't specifically related to service addressing.

**Returns:** A shared pointer to the requested service (\<Derived>).

**Throws:** `std::runtime_error` when allow_null==false and the service lookup (or construction) fails.

**Parameters**

**`metadata`** `const EnumerationMetadata &`

Addressing and configuration for the service.

---

**`allow_null`** `bool` — default: false

Use `true` to return nullptr when the service cannot be resolved; the default `false` value raises a std::runtime_error.

---

#### Overload 2

inline

```cpp showLineNumbers={false}
static std::shared_ptr<LinuxReceiverInterfaceV1> hololink::module::Service<LinuxReceiverInterfaceV1>::get_service(
    std::shared_ptr<Module> module,
    const char *instance_id,
    bool allow_null = false
)
```

Type-safe way to fetch a std::shared_ptr to an instance of \<Derived> 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<Module>`

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]

```cpp showLineNumbers={false}
static bool hololink::module::Service<LinuxReceiverInterfaceV1>::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.