nros::Subscription< M > Class Template Reference

#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)
Result	take (M &msg)
Result	take_sequence (uint8_t *buf, size_t per_msg_cap, size_t max_msgs, size_t *out_lens, size_t &out_count)
Result	take_serialized (uint8_t *buf, size_t capacity, size_t &out_len)
Result	take_serialized_with_attachment (uint8_t *buf, size_t capacity, size_t &out_len, uint8_t *att, size_t att_capacity, size_t &out_att_len)
template<size_t Cap>
Result	take_sized (M &msg)
Result	take_validated (M &msg, nros_cpp_integrity_status_t &status)
template<size_t Cap>
Result	take_validated_sized (M &msg, nros_cpp_integrity_status_t &status)
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)
template<size_t Cap>
Result	try_recv_sized (M &msg)
Result	try_recv_validated (M &msg, nros_cpp_integrity_status_t &status)
template<size_t Cap>
Result	try_recv_validated_sized (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 take_serialized() 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.take_serialized(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

take()

template<typename M >

Result nros::Subscription< M >::take ( 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.

take_sequence()

template<typename M >

Result nros::Subscription< M >::take_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 take_serialized loop — same shape, same observable result; the batched API just lets sensor loops commit to one call shape regardless of backend support.

take_serialized()

template<typename M >

Result nros::Subscription< M >::take_serialized ( 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.

take_serialized_with_attachment()

template<typename M >

Result nros::Subscription< M >::take_serialized_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.

take_sized()

template<typename M >

template<size_t Cap>

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

inline

take with the receive buffer sized by the CALLER.

The escape hatch for a type with no derived bound, and the way to deliberately override a bounded type's own number. Mirrors how bind_subscription_sized relates to bind_subscription (issue 0964).

Template Parameters

Cap	Stack bytes to receive into. A sample larger than this is refused by the backend, so under-sizing DROPS messages.

take_validated()

template<typename M >

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

inline

Issue 0073 — take that ALSO returns the E2E message-integrity status (CRC + sequence gap/dup) of the received sample. The safety-e2e analog of take: 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.

take_validated_sized()

template<typename M >

template<size_t Cap>

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

inline

take_validated with the receive buffer sized by the CALLER. See take_sized (issue 0964).

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

Deprecated:

Use take(M&).

try_recv_raw()

template<typename M >

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

inline

Deprecated:

Use take_serialized(uint8_t*, size_t, size_t&).

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

Deprecated:

Use take_serialized_with_attachment(...).

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

Deprecated:

Use take_sequence(...).

try_recv_sized()

template<typename M >

template<size_t Cap>

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

inline

Deprecated:

Use take_sized<Cap>(M&).

phase-379 W6 — this pair arrived on main (issue 0964) between the W6 decision and its execution, so it gets the same forwarder treatment as the five spellings the decision named. Retired with them in W7 step 4.

try_recv_validated()

template<typename M >

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

inline

Deprecated:

Use take_validated(M&, nros_cpp_integrity_status_t&).

try_recv_validated_sized()

template<typename M >

template<size_t Cap>

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

inline

Deprecated:

Use take_validated_sized<Cap>(M&, nros_cpp_integrity_status_t&).

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