#include <subscription.hpp>

Classes
class	View

Public Types
using	TypedSubscriptionFn = void(*)(const M &msg)

using	TypedSubscriptionFnWithCtx = void()(const M &msg, void ctx)

using	TypedSubscriptionInfoFn = void()(const M &msg, const uint8_t attachment, size_t attachment_len)

Public Member Functions
const char *	get_topic_name () const
	Get the topic name.

bool	has_sched_handle () const

bool	is_valid () const
	Check if the subscription is initialized and valid.

Result	on_liveliness_changed (nros_cpp_liveliness_changed_cb_t cb, void *user_context=nullptr)

Result	on_message_lost (nros_cpp_subscriber_count_cb_t cb, void *user_context=nullptr)
	Register a callback for message-lost events.

Result	on_requested_deadline_missed (uint32_t deadline_ms, nros_cpp_subscriber_count_cb_t cb, void *user_context=nullptr)
	Register a callback for requested-deadline-missed events.

Subscription &	operator= (Subscription &&other)

size_t	sched_handle_id () const

Stream< M > &	stream ()

const Stream< M > &	stream () const

	Subscription ()

	Subscription (Subscription &&other)

Expected< View >	try_borrow ()

Result	try_recv (M &msg)

Result	try_recv_raw (uint8_t *buf, size_t capacity, size_t &out_len)

Result	try_recv_raw_with_attachment (uint8_t buf, size_t capacity, size_t &out_len, uint8_t att, size_t att_capacity, size_t &out_att_len)

Result	try_recv_sequence (uint8_t buf, size_t per_msg_cap, size_t max_msgs, size_t out_lens, size_t &out_count)

Result	try_recv_validated (M &msg, nros_cpp_integrity_status_t &status)

	~Subscription ()

Friends
class	Node

Detailed Description

template<typename M>
class nros::Subscription< M >

Typed subscription for a ROS 2 topic.

Mirrors rclcpp::Subscription<M>. The message type M must provide TYPE_NAME, TYPE_HASH, and deserialization support (generated by codegen).

Manual-poll style: call try_recv_raw() after nros::spin_once().

Usage:

nros::Subscription<std_msgs::msg::String> sub;
NROS_TRY(node.create_subscription(sub, "/chatter"));
nros::spin_once(10);
uint8_t buf[256];
size_t len;
if (sub.try_recv_raw(buf, sizeof(buf), len)) {
    // process buf[0..len]
}

Member Typedef Documentation

◆ TypedSubscriptionFn

template<typename M >

using nros::Subscription< M >::TypedSubscriptionFn = void (*)(const M& msg)

Phase 189.M3.x — typed message-handler signatures for the callback-style subscription (rclcpp dispatch model). The executor invokes the handler during spin_once() on each new sample.

◆ TypedSubscriptionFnWithCtx

template<typename M >

using nros::Subscription< M >::TypedSubscriptionFnWithCtx = void (*)(const M& msg, void* ctx)

◆ TypedSubscriptionInfoFn

template<typename M >

using nros::Subscription< M >::TypedSubscriptionInfoFn = void (*)(const M& msg, const uint8_t* attachment, size_t attachment_len)

Constructor & Destructor Documentation

◆ ~Subscription()

template<typename M >

nros::Subscription< M >::~Subscription ( )

inline

Destructor — releases subscription resources.

Poll-style subscriptions own an RmwSubscriber in storage_ and free it here. Callback-style subscriptions (Phase 189.M3.x) are owned by the executor arena (freed when the executor drops), so the dtor must NOT touch storage_ for them.

◆ Subscription() [1/2]

template<typename M >

nros::Subscription< M >::Subscription ( Subscription< M > && other )

inline

◆ Subscription() [2/2]

template<typename M >

nros::Subscription< M >::Subscription ( )

inline

Default constructor — creates an uninitialized subscription. Use Node::create_subscription() to initialize.

Member Function Documentation

◆ get_topic_name()

template<typename M >

const char * nros::Subscription< M >::get_topic_name ( ) const

inline

Get the topic name.

◆ has_sched_handle()

template<typename M >

bool nros::Subscription< M >::has_sched_handle ( ) const

inline

Phase 189.M3.1 — internal: executor HandleId usable with nros_cpp_bind_handle_to_sched_context, or SIZE_MAX when the subscription has no bindable handle.

The current thin-wrapper create path (nros_cpp_subscription_create) stores a bare RmwSubscriber and registers no executor callback entry, so no HandleId exists and this stays SIZE_MAX. The accessor

setter are wired so SubscriptionOptions::sched_context lowering activates transparently once a handle-returning create FFI lands. Node is a friend and sets this on create when a handle is available.

◆ is_valid()

template<typename M >

bool nros::Subscription< M >::is_valid ( ) const

inline

Check if the subscription is initialized and valid.

◆ on_liveliness_changed()

template<typename M >

Result nros::Subscription< M >::on_liveliness_changed	(	nros_cpp_liveliness_changed_cb_t	cb,
		void *	user_context = `nullptr`
	)

inline

Register a callback for liveliness-changed events.

Returns Result(ErrorCode::Unsupported) until the active backend wires up liveliness detection.

◆ on_message_lost()

template<typename M >

Result nros::Subscription< M >::on_message_lost	(	nros_cpp_subscriber_count_cb_t	cb,
		void *	user_context = `nullptr`
	)

inline

Register a callback for message-lost events.

◆ on_requested_deadline_missed()

template<typename M >

Result nros::Subscription< M >::on_requested_deadline_missed	(	uint32_t	deadline_ms,
		nros_cpp_subscriber_count_cb_t	cb,
		void *	user_context = `nullptr`
	)

inline

Register a callback for requested-deadline-missed events.

◆ operator=()

template<typename M >

Subscription & nros::Subscription< M >::operator= ( Subscription< M > && other )

inline

◆ sched_handle_id()

template<typename M >

size_t nros::Subscription< M >::sched_handle_id ( ) const

inline

◆ stream() [1/2]

template<typename M >

Stream< M > & nros::Subscription< M >::stream ( )

inline

Get a reference to the subscription's message stream.

Use for blocking reception with executor spin:

M msg;

NROS_TRY(sub.stream().wait_next(executor.handle(), 1000, msg));

◆ stream() [2/2]

template<typename M >

const Stream< M > & nros::Subscription< M >::stream ( ) const

inline

◆ try_borrow()

template<typename M >

Expected< View > nros::Subscription< M >::try_borrow ( )

inline

Phase 124.A.7 — try to borrow the next message in place. Returns View with data when a message is ready, empty View when not. On error returns Expected::error.

◆ try_recv()

template<typename M >

Result nros::Subscription< M >::try_recv ( M & msg )

inline

Try to receive a typed message (non-blocking).

Receives raw CDR data into a stack buffer, then deserializes into msg using the codegen-generated M::ffi_deserialize().

Parameters

msg	Output message struct (filled on success).

Returns: Result::success() if a message was received and deserialized; ErrorCode::TryAgain if no data is available right now; ErrorCode::NotInitialized if the subscription is not initialized; ErrorCode::Error if deserialization failed.

◆ try_recv_raw()

template<typename M >

Result nros::Subscription< M >::try_recv_raw	(	uint8_t *	buf,
		size_t	capacity,
		size_t &	out_len
	)

inline

Try to receive raw CDR data (non-blocking).

Sets out_len to the number of bytes received (0 if no data).

Parameters

buf	Buffer to receive CDR data.
capacity	Size of the buffer.
out_len	Receives the number of bytes (0 if no data available).

Returns: Result::success() if data was received; ErrorCode::TryAgain if no data is available; ErrorCode::NotInitialized or the FFI error code otherwise.

◆ try_recv_raw_with_attachment()

template<typename M >

Result nros::Subscription< M >::try_recv_raw_with_attachment	(	uint8_t *	buf,
		size_t	capacity,
		size_t &	out_len,
		uint8_t *	att,
		size_t	att_capacity,
		size_t &	out_att_len
	)

inline

Try to receive raw CDR data plus the sample's wire attachment (non-blocking) — the C++ poll-side analog of the Rust node.subscription(t).generic(..).message_info() builder (Phase 189.M3.4b). The attachment carries out-of-band tags such as a cross-RMW bridge's bridge_origin; out_att_len is 0 when the sample carried none.

Parameters

buf	Buffer to receive CDR payload.
capacity	Size of `buf`.
out_len	Receives payload length (0 if no data).
att	Buffer to receive the attachment.
att_capacity	Size of `att`.
out_att_len	Receives attachment length (0 if none).

Returns: Result::success() if a sample was received; ErrorCode::TryAgain if none is available; NotInitialized / FFI error otherwise.

◆ try_recv_sequence()

template<typename M >

Result nros::Subscription< M >::try_recv_sequence	(	uint8_t *	buf,
		size_t	per_msg_cap,
		size_t	max_msgs,
		size_t *	out_lens,
		size_t &	out_count
	)

inline

Phase 124.D.1 — burst-take.

Drain up to max_msgs queued samples in a single call. The i-th delivered sample lives at buf + i * per_msg_cap with length out_lens[i]. Writes the count to out_count. Returns Result::success() on success (count may be 0), the matching FFI error otherwise.

Backends without a native batch take fall back to a try_recv_raw loop — same shape, same observable result; the batched API just lets sensor loops commit to one call shape regardless of backend support.

◆ try_recv_validated()

template<typename M >

Result nros::Subscription< M >::try_recv_validated	(	M &	msg,
		nros_cpp_integrity_status_t &	status
	)

inline

Issue 0073 — try_recv that ALSO returns the E2E message-integrity status (CRC + sequence gap/dup) of the received sample. The safety-e2e analog of try_recv: the backend recomputes + compares the CRC the publisher attached and tracks the sequence, writing the verdict to status.

Requires the build to enable safety-e2e on both ends (the zenoh backend's own feature, lowered from a declared [safety] axis); a binary built without it cannot link this (the FFI symbol is gated). With it, but against a publisher built without safety, status.crc_valid reports -1.

Parameters

msg	Output message struct (filled on success).
status	Receives `{ gap, duplicate, crc_valid }` (crc_valid: 1=valid, 0=mismatch, -1=no CRC on the wire).

Returns: Result::success() on a received+deserialized message; TryAgain if none available; NotInitialized / Error otherwise.

Friends And Related Symbol Documentation

◆ Node

template<typename M >

friend class Node

friend

The documentation for this class was generated from the following files:

include/nros/node.hpp
include/nros/subscription.hpp

Classes

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ TypedSubscriptionFn

◆ TypedSubscriptionFnWithCtx

◆ TypedSubscriptionInfoFn

Constructor & Destructor Documentation

◆ ~Subscription()

◆ Subscription() [1/2]

◆ Subscription() [2/2]

Member Function Documentation

◆ get_topic_name()

◆ has_sched_handle()

◆ is_valid()

◆ on_liveliness_changed()

◆ on_message_lost()

◆ on_requested_deadline_missed()

◆ operator=()

◆ sched_handle_id()

◆ stream() [1/2]

◆ stream() [2/2]

◆ try_borrow()

◆ try_recv()

◆ try_recv_raw()

◆ try_recv_raw_with_attachment()

◆ try_recv_sequence()

◆ try_recv_validated()

Friends And Related Symbol Documentation

◆ Node