#include <node.hpp>

Public Member Functions
template<typename A >
Result	create_action_client (ActionClient< A > &out, const char *action_name, const QoS &qos=QoS::services())

template<typename A >
Result	create_action_server (ActionServer< A > &out, const char *action_name, const QoS &qos=QoS::services(), const ActionServerOptions &options={})

template<typename S >
Result	create_client (Client< S > &out, const char *service_name, const QoS &qos=QoS::services())

template<typename S , typename F , typename = typename std::enable_if< std::is_convertible<F, void (*)(const typename S::Response&)>::value>::type>
Result	create_client (Client< S > &out, const char *service_name, F callback, const QoS &qos=QoS::services(), const ClientOptions &options={})

Result	create_guard_condition (GuardCondition &out, nros_cpp_guard_callback_t callback, void *context=nullptr)

template<typename A >
Result	create_polling_action_client (PollingActionClient< A > &out, const char *action_name)
	Phase 122.3.d.b — Create an L1 polling-mode action client.

template<typename A >
Result	create_polling_action_server (PollingActionServer< A > &out, const char *action_name)

template<typename M >
Result	create_publisher (Publisher< M > &out, const char *topic, const QoS &qos, const PublisherOptions &options)

template<typename M >
Result	create_publisher (Publisher< M > &out, const char *topic, const QoS &qos=QoS::default_profile())

template<typename S >
Result	create_service (Service< S > &out, const char *service_name, const QoS &qos=QoS::services())

template<typename S , typename F , typename = typename std::enable_if<std::is_convertible< F, void (*)(const typename S::Request&, typename S::Response&)>::value>::type>
Result	create_service (Service< S > &out, const char *service_name, F callback, const QoS &qos=QoS::services(), const ServiceOptions &options={})

template<typename M >
Result	create_subscription (Subscription< M > &out, const char *topic, const QoS &qos, const SubscriptionOptions &options)

template<typename M >
Result	create_subscription (Subscription< M > &out, const char *topic, const QoS &qos=QoS::default_profile())

template<typename M , typename F , typename = typename std::enable_if<std::is_convertible<F, void (*)(const M&)>::value>::type>
Result	create_subscription (Subscription< M > &out, const char *topic, F callback, const QoS &qos=QoS::default_profile(), const SubscriptionOptions &options={})

template<typename M , typename F , typename = typename std::enable_if< std::is_convertible<F, void ()(const M&, const uint8_t, size_t)>::value>::type>
Result	create_subscription_with_info (Subscription< M > &out, const char *topic, F callback, const QoS &qos=QoS::default_profile(), const SubscriptionOptions &options={})

Result	create_timer (Timer &out, uint64_t period_ms, nros_cpp_timer_callback_t callback, void *context=nullptr)

Result	create_timer_oneshot (Timer &out, uint64_t delay_ms, nros_cpp_timer_callback_t callback, void *context=nullptr)

void *	executor_handle () const

const nros_cpp_node_t *	ffi_handle () const

const void *	get_logger () const

const char *	get_name () const
	Get the node name.

const char *	get_namespace () const
	Get the node namespace.

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

	Node ()
	Default constructor — creates an uninitialized node.

	Node (Node &&other)

Node &	operator= (Node &&other)

void	set_qos_overrides (const nros_cpp_qos_override_t *overrides, size_t len)

	~Node ()
	Destructor — releases node resources.

Static Public Member Functions
static Result	create (Node &out, const char name, const char ns=nullptr)

Friends
class	ComponentNode

Result	create_node (Node &out, const char name, const char ns)

class	Executor

void *	global_handle ()

Result	init (const char *locator, uint8_t domain_id)

Result	init (const char locator, uint8_t domain_id, const char session_name)

class	NodeBuilder

bool	ok ()
	Check if the nros session is initialized.

Result	shutdown ()

Result	spin ()

Result	spin (uint32_t duration_ms, int32_t poll_ms)

Result	spin_once (int32_t timeout_ms)

Detailed Description

Node — the primary interface for creating ROS entities.

Mirrors rclcpp::Node. Entities (publishers, subscriptions, services, etc.) are created through the node. The node holds a reference to the parent executor session.

Usage:

nros::Node node;

NROS_TRY(nros::Node::create(node, "my_node"));

nros::Future

Definition future.hpp:40

nros::Node

Definition node.hpp:158

nros::Node::create

static Result create(Node &out, const char *name, const char *ns=nullptr)

Definition node.hpp:169

NROS_TRY

#define NROS_TRY(expr)

Definition result.hpp:90

Constructor & Destructor Documentation

◆ Node() [1/2]

nros::Node::Node ( )

inline

Default constructor — creates an uninitialized node.

◆ ~Node()

nros::Node::~Node ( )

inline

Destructor — releases node resources.

◆ Node() [2/2]

nros::Node::Node ( Node && other )

inline

Member Function Documentation

◆ create()

static Result nros::Node::create	(	Node &	out,
		const char *	name,
		const char *	ns = `nullptr`
	)

inlinestatic

Create a new node.

Parameters

out	Receives the initialized node.
name	Node name (null-terminated).
ns	Node namespace (null-terminated), or nullptr for "/".

Returns: Result indicating success or failure.

◆ create_action_client()

template<typename A >

Result nros::Node::create_action_client	(	ActionClient< A > &	out,
		const char *	action_name,
		const QoS &	qos = `QoS::services()`
	)

Create an action client.

Template Parameters

A	Action type (must define nested Goal, Result, Feedback with TYPE_NAME/TYPE_HASH).

Parameters

out	Receives the initialized action client.
action_name	Action name (null-terminated).
qos	QoS profile (default: services preset).

◆ create_action_server()

template<typename A >

Result nros::Node::create_action_server	(	ActionServer< A > &	out,
		const char *	action_name,
		const QoS &	qos = `QoS::services()`,
		const ActionServerOptions &	options = `{}`
	)

Create an action server.

Goals are auto-accepted during spin_once(). Use try_recv_goal() to poll.

Template Parameters

A	Action type (must define nested Goal, Result, Feedback with TYPE_NAME/TYPE_HASH).

Parameters

out	Receives the initialized action server.
action_name	Action name (null-terminated).
qos	QoS profile (default: services preset).
options	Named options; `options.sched_context` (M3.3.c) binds the goal-service dispatch onto a scheduling context.

◆ create_client() [1/2]

template<typename S >

Result nros::Node::create_client	(	Client< S > &	out,
		const char *	service_name,
		const QoS &	qos = `QoS::services()`
	)

Create a service client.

Template Parameters

S	Service type (must define nested Request and Response with TYPE_NAME/TYPE_HASH).

Parameters

out	Receives the initialized service client.
service_name	Service name (null-terminated).
qos	QoS profile (default: services preset).

◆ create_client() [2/2]

template<typename S , typename F , typename >

Result nros::Node::create_client	(	Client< S > &	out,
		const char *	service_name,
		F	callback,
		const QoS &	qos = `QoS::services()`,
		const ClientOptions &	options = `{}`
	)

Create a callback-style service client (rclcpp async dispatch; Phase 189.M3.3.f). Arena-registered, so it owns a real executor handle and its response handler runs during spin_once — making options.sched_context functional. callback must be convertible to void(const S::Response&); send requests with Client<S>::async_send_request. The SFINAE guard keeps the future-style 3-arg overload unambiguous.

CONSTRAINT: do not move out after this returns — the executor arena holds &out as the response dispatch context.

◆ create_guard_condition()

Result nros::Node::create_guard_condition	(	GuardCondition &	out,
		nros_cpp_guard_callback_t	callback,
		void *	context = `nullptr`
	)

inline

Create a guard condition for cross-thread signaling.

The callback fires during spin_once() when guard.trigger() is called.

Parameters

out	Receives the initialized guard condition.
callback	C function pointer invoked when triggered.
context	User context passed to the callback (may be nullptr).

◆ create_polling_action_client()

template<typename A >

Result nros::Node::create_polling_action_client	(	PollingActionClient< A > &	out,
		const char *	action_name
	)

Phase 122.3.d.b — Create an L1 polling-mode action client.

◆ create_polling_action_server()

template<typename A >

Result nros::Node::create_polling_action_server	(	PollingActionServer< A > &	out,
		const char *	action_name
	)

Phase 122.3.d.b — Create an L1 polling-mode action server. Caller drives the lifecycle (no executor callback). See polling_action_server.hpp for usage.

◆ create_publisher() [1/2]

template<typename M >

Result nros::Node::create_publisher	(	Publisher< M > &	out,
		const char *	topic,
		const QoS &	qos,
		const PublisherOptions &	options
	)

Create a publisher with rclcpp-style named options (Phase 189.M3.1).

options sits alongside qos (rclcpp convention). PublisherOptions is currently a reserved/empty struct, so this overload is observably identical to the qos-only form — it exists for API symmetry and as the seam for future intra-process / loaned-message knobs.

Template Parameters

M	Message type (must define TYPE_NAME and TYPE_HASH).

Parameters

out	Receives the initialized publisher.
topic	Topic name (null-terminated).
qos	QoS profile.
options	Named publisher options.

Phase 189.M3.1 — named-options overload. PublisherOptions is a reserved/empty struct (a publisher has no callback ⇒ no sched-context or message-info axis), so this simply forwards to the qos-only create. It exists for rclcpp symmetry and as the seam for future intra-process / loaned-message knobs.

◆ create_publisher() [2/2]

template<typename M >

Result nros::Node::create_publisher	(	Publisher< M > &	out,
		const char *	topic,
		const QoS &	qos = `QoS::default_profile()`
	)

Create a publisher for a topic.

Template Parameters

M	Message type (must define TYPE_NAME and TYPE_HASH).

Parameters

out	Receives the initialized publisher.
topic	Topic name (null-terminated).
qos	QoS profile (default: reliable, keep-last(10)).

◆ create_service() [1/2]

template<typename S >

Result nros::Node::create_service	(	Service< S > &	out,
		const char *	service_name,
		const QoS &	qos = `QoS::services()`
	)

Create a service server.

Template Parameters

S	Service type (must define nested Request and Response with TYPE_NAME/TYPE_HASH).

Parameters

out	Receives the initialized service server.
service_name	Service name (null-terminated).
qos	QoS profile (default: services preset).

◆ create_service() [2/2]

template<typename S , typename F , typename >

Result nros::Node::create_service	(	Service< S > &	out,
		const char *	service_name,
		F	callback,
		const QoS &	qos = `QoS::services()`,
		const ServiceOptions &	options = `{}`
	)

Create a callback-style service server (rclcpp dispatch model; Phase 189.M3.3.e). Unlike the poll-style overload above, this arena-registers the service so it owns a real executor handle and its request handler runs during spin_once — making options.sched_context functional. callback must be convertible to void(const S::Request&, S::Response&) (a plain function pointer or empty-capture lambda); it fills response from request. The SFINAE guard keeps the poll-style 3-arg overload unambiguous (a QoS is not convertible to the handler type).

CONSTRAINT: do not move out after this returns — the executor arena holds &out as the dispatch context.

◆ create_subscription() [1/3]

template<typename M >

Result nros::Node::create_subscription	(	Subscription< M > &	out,
		const char *	topic,
		const QoS &	qos,
		const SubscriptionOptions &	options
	)

Create a subscription with rclcpp-style named options (Phase 189.M3.1).

options sits alongside qos (rclcpp convention) and carries the non-QoS creation axes. options.sched_context (when set) lowers to a create-then-bind via nros_cpp_bind_handle_to_sched_context; options.message_info is reserved (M3.4). See SubscriptionOptions.

Template Parameters

M	Message type (must define TYPE_NAME and TYPE_HASH).

Parameters

out	Receives the initialized subscription.
topic	Topic name (null-terminated).
qos	QoS profile.
options	Named subscription options.

Phase 189.M3.1 — named-options overload. Delegates to the qos-only create, then lowers the non-QoS axes:

sched_context — when set (!= SCHED_CONTEXT_UNSET) and the created subscription exposes a bindable executor HandleId, create-then-bind via nros_cpp_bind_handle_to_sched_context; a failing bind tears the subscription back down and surfaces the FFI error. The current thin-wrapper subscription has no bindable handle (see Subscription<M>::has_sched_handle()), so the bind is skipped until a handle-returning create FFI lands (tracked with M3.4); the field is honoured transparently once that exists.
message_info — reserved (M3.4); ignored today.

◆ create_subscription() [2/3]

template<typename M >

Result nros::Node::create_subscription	(	Subscription< M > &	out,
		const char *	topic,
		const QoS &	qos = `QoS::default_profile()`
	)

Create a subscription for a topic.

Template Parameters

M	Message type (must define TYPE_NAME and TYPE_HASH).

Parameters

out	Receives the initialized subscription.
topic	Topic name (null-terminated).
qos	QoS profile (default: reliable, keep-last(10)).

◆ create_subscription() [3/3]

template<typename M , typename F , typename >

Result nros::Node::create_subscription	(	Subscription< M > &	out,
		const char *	topic,
		F	callback,
		const QoS &	qos = `QoS::default_profile()`,
		const SubscriptionOptions &	options = `{}`
	)

Create a callback-style subscription (rclcpp dispatch model; Phase 189.M3.x). The executor arena owns the subscriber and invokes callback during spin_once() on each new sample, so options.sched_context is functional (poll-style subscriptions have no dispatched callback to schedule). callback must be convertible to void(const M&) (a plain function pointer or empty-capture lambda); the SFINAE guard keeps the poll-style overloads unambiguous (a QoS is not convertible to the handler type).

CONSTRAINT: do not move out after this returns — the executor arena holds &out as the dispatch context.

Template Parameters

M	Message type (must define TYPE_NAME, TYPE_HASH, ffi_deserialize).

Parameters

out	Receives the initialized subscription (callback mode).
topic	Topic name (null-terminated).
callback	Handler invoked as `callback(const M&)` per sample.
qos	QoS profile.
options	Named subscription options (e.g. sched_context).

◆ create_subscription_with_info()

template<typename M , typename F , typename >

Result nros::Node::create_subscription_with_info	(	Subscription< M > &	out,
		const char *	topic,
		F	callback,
		const QoS &	qos = `QoS::default_profile()`,
		const SubscriptionOptions &	options = `{}`
	)

Create a callback-style subscription that also delivers each sample's wire attachment (Phase 189.M3.4 — the callback analogue of Subscription::try_recv_raw_with_attachment). Arena-registered like the callback overload above (so options.sched_context is functional), but the handler is invoked as callback(const M&, const uint8_t* attachment, size_t attachment_len); attachment_len == 0 means the sample carried none. Cross-RMW bridges read the bridge_origin tag from the attachment.

◆ create_timer()

Result nros::Node::create_timer	(	Timer &	out,
		uint64_t	period_ms,
		nros_cpp_timer_callback_t	callback,
		void *	context = `nullptr`
	)

inline

Create a repeating timer.

The callback fires during spin_once() at the specified period.

Parameters

out	Receives the initialized timer.
period_ms	Timer period in milliseconds.
callback	C function pointer invoked on each tick.
context	User context passed to the callback (may be nullptr).

◆ create_timer_oneshot()

Result nros::Node::create_timer_oneshot	(	Timer &	out,
		uint64_t	delay_ms,
		nros_cpp_timer_callback_t	callback,
		void *	context = `nullptr`
	)

inline

Create a one-shot timer.

The callback fires once after the specified delay.

Parameters

out	Receives the initialized timer.
delay_ms	Delay in milliseconds before the callback fires.
callback	C function pointer invoked once.
context	User context passed to the callback (may be nullptr).

◆ executor_handle()

void * nros::Node::executor_handle ( ) const

inline

Phase 240.5 (RFC-0043) — the opaque executor handle this node was opened against (from nros_cpp_init). The component layer needs it for the raw FFI that is executor- rather than node-scoped (action server register / complete_goal / publish_feedback) — Node::create_* use it internally, but a stateful component binding those transports raw needs direct access. nullptr on an uninitialized node.

◆ ffi_handle()

const nros_cpp_node_t * nros::Node::ffi_handle ( ) const

inline

Phase 235.A — internal: raw FFI node handle for the Entry-pkg NodeContext runtime.

The declarative NodeContextOps boundary (<nros/node_pkg.hpp>) is type-erased — entities arrive as descriptor strings (type_name / type_hash), with no message type M available at the op-function-pointer callsite. The native runtime in <nros/main.hpp> therefore constructs publishers / subscriptions through the raw nros_cpp_{publisher,subscription}_create FFI, which takes a const nros_cpp_node_t*. This accessor hands that pointer to the runtime. Not part of the public rclcpp-style surface — user code creates entities via the typed create_publisher<M> / create_subscription<M> templates.

Returns nullptr on an uninitialized node.

◆ get_logger()

const void * nros::Node::get_logger ( ) const

inline

Phase 88.12 — return the nros_log::Logger keyed on this node's name. The returned opaque handle is passed to the NROS_LOG_* macros in <nros/log.hpp>. Lifetime is 'static; callers must NOT free.

Returns NULL on an uninitialized node.

◆ get_name()

const char * nros::Node::get_name ( ) const

inline

Get the node name.

◆ get_namespace()

const char * nros::Node::get_namespace ( ) const

inline

Get the node namespace.

◆ is_valid()

bool nros::Node::is_valid ( ) const

inline

Check if the node is initialized and valid.

◆ operator=()

Node & nros::Node::operator= ( Node && other )

inline

◆ set_qos_overrides()

void nros::Node::set_qos_overrides	(	const nros_cpp_qos_override_t *	overrides,
		size_t	len
	)

inline

Phase 211.H (issue #52) — install the per-topic QoS override table the deploy plan lowered from qos_overrides.<topic>.<role>.<policy> launch params. Every publisher/subscription created on this node afterwards folds the matching (topic, role) entries into its QoS before the backend-compat check — the C++ mirror of Rust's NodeHandle::set_qos_overrides. Call once, before creating entities (a generated/hand-written entry does this before configure(node)).

overrides must outlive the node (e.g. a static array in the entry). Pass len == 0 to clear. No-op on an uninitialized node.

Friends And Related Symbol Documentation

◆ ComponentNode

friend class ComponentNode

friend

◆ create_node

Result create_node	(	Node &	out,
		const char *	name,
		const char *	ns = `nullptr`
	)

friend

Create a node (convenience — uses the global executor).

This is the primary way to create nodes after calling nros::init().

Parameters

out	Receives the initialized node.
name	Node name.
ns	Node namespace, or nullptr for "/".

◆ Executor

friend class Executor

friend

◆ global_handle

void * global_handle ( )

friend

Get the global executor handle for Future::wait().

Returns the raw storage pointer used by the global init()/spin_once() free functions. Use with Future::wait(nros::global_handle(), ...).

Returns: Executor handle, or nullptr if not initialized.

◆ init [1/2]

Result init	(	const char *	locator = `nullptr`,
		uint8_t	domain_id = `0`
	)

friend

Initialize an nros session.

Opens a middleware connection. Must be called before creating nodes. Call shutdown() to clean up.

Parameters

locator	Middleware locator (e.g., "tcp/127.0.0.1:7447"), or nullptr for default.
domain_id	ROS domain ID (0-232).

Returns: Result indicating success or failure.

◆ init [2/2]

Result init	(	const char *	locator,
		uint8_t	domain_id,
		const char *	session_name
	)

friend

Initialize the nros session with an explicit session name.

session_name is the process-wide identifier used by the XRCE-DDS RMW backend to derive a unique session key. Two processes connecting to the same XRCE Agent MUST use distinct session names — otherwise the agent treats them as the same client and topic publishes don't cross-route. For zenoh / DDS backends the value is informational only.

Pick a name that's stable for the process and distinct from every other nros process you intend to share an agent with. Typical choice: the process's primary node name (e.g. "talker", "listener").

Parameters

locator	Middleware locator, or nullptr for default.
domain_id	ROS domain ID (0-232).
session_name	Per-process session identifier. Must not be nullptr.

Returns: Result indicating success or failure.

◆ NodeBuilder

friend class NodeBuilder

friend

◆ ok

bool ok ( )

friend

Check if the nros session is initialized.

◆ shutdown

Result shutdown ( )

friend

Shut down the nros session.

Closes the middleware connection and frees all resources.

◆ spin [1/2]

Result spin ( )

friend

Phase 123.B.2 — block until nros::ok() returns false.

Mirror of rclcpp::spin(node). The typical pattern in user code is: install a SIGINT handler that calls nros::shutdown() (which flips ok() to false), then nros::spin() from main.

Returns the first non-success spin_once result, or Result::success() after a clean shutdown.

◆ spin [2/2]

Result spin	(	uint32_t	duration_ms,
		int32_t	poll_ms = `10`
	)

friend

Spin for a duration (blocking).

Repeatedly calls spin_once() until duration_ms has elapsed. Convenience wrapper around the global executor.

Parameters

duration_ms	Total time to spin, in milliseconds.
poll_ms	Individual spin_once timeout (default: 10ms).

Returns: Result from the last spin_once call.

◆ spin_once

Result spin_once ( int32_t timeout_ms = 10 )

friend

Drive transport I/O and dispatch callbacks.

Call this periodically so subscriptions can receive data. When using manual-poll (no callbacks), this drives the network layer.

Parameters

timeout_ms Maximum time to block waiting for I/O (default: 10ms).

Returns: Result indicating success or failure.

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

include/nros/node.hpp
include/nros/publisher.hpp
include/nros/subscription.hpp
include/nros/service.hpp
include/nros/client.hpp
include/nros/action_server.hpp
include/nros/action_client.hpp

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Node() [1/2]

◆ ~Node()

◆ Node() [2/2]

Member Function Documentation

◆ create()

◆ create_action_client()

◆ create_action_server()

◆ create_client() [1/2]

◆ create_client() [2/2]

◆ create_guard_condition()

◆ create_polling_action_client()

◆ create_polling_action_server()

◆ create_publisher() [1/2]

◆ create_publisher() [2/2]

◆ create_service() [1/2]

◆ create_service() [2/2]

◆ create_subscription() [1/3]

◆ create_subscription() [2/3]

◆ create_subscription() [3/3]

◆ create_subscription_with_info()

◆ create_timer()

◆ create_timer_oneshot()

◆ executor_handle()

◆ ffi_handle()

◆ get_logger()

◆ get_name()

◆ get_namespace()

◆ is_valid()

◆ operator=()

◆ set_qos_overrides()

Friends And Related Symbol Documentation

◆ ComponentNode

◆ create_node

◆ Executor

◆ global_handle

◆ init [1/2]

◆ init [2/2]

◆ NodeBuilder

◆ ok

◆ shutdown

◆ spin [1/2]

◆ spin [2/2]

◆ spin_once