nros Namespace Reference

Classes
class	ActionClient
class	ActionServer
class	Client
class	Executor
class	Expected
struct	FixedSequence
struct	FixedString
class	Future
class	GuardCondition
struct	LeSpan
class	Node
class	NodeBuilder
class	PollingActionClient
class	PollingActionServer
class	Publisher
class	QoS
class	Result
class	Service
struct	Span
class	Stream
struct	StringView
class	Subscription
class	Timer

Enumerations
enum class	CancelResponse : int32_t { Reject = 0 , Accept = 1 }
	Cancel acceptance response returned from the user's cancel callback. More...
enum class	ErrorCode : int32_t {   Ok = 0 , Error = -1 , Timeout = -2 , InvalidArgument = -3 ,   NotInitialized = -4 , Full = -5 , TryAgain = -6 , Reentrant = -7 ,   TransportError = -100 }
enum class	GoalResponse : int32_t { Reject = 0 , AcceptAndExecute = 1 , AcceptAndDefer = 2 }
	Goal acceptance response returned from the user's goal callback. More...
enum class	GoalStatus : int8_t {   Unknown = 0 , Accepted = 1 , Executing = 2 , Canceling = 3 ,   Succeeded = 4 , Canceled = 5 , Aborted = 6 }

Functions
Result	create_node (Node &out, const char *name, const char *ns=nullptr)
void *	global_handle ()
Result	init (const char *locator, uint8_t domain_id, const char *session_name)
Result	init (const char *locator=nullptr, uint8_t domain_id=0)
Result	init_with_launch (const char *path, int argc=0, char **argv=nullptr, const char *session_name=nullptr)
Result	init_with_launch_auto (int argc=0, char **argv=nullptr, const char *session_name=nullptr)
Expected< Node >	make_node (const char *name, const char *ns=nullptr)
bool	ok ()
	Check if the nros session is initialized.
Result	shutdown ()
Result	spin ()
Result	spin (uint32_t duration_ms, int32_t poll_ms=10)
Result	spin_once (int32_t timeout_ms=10)

Variables
static constexpr size_t	PUBLISHER_TOPIC_NAME_MAX = 256
static constexpr size_t	SUBSCRIPTION_TOPIC_NAME_MAX = 256

Enumeration Type Documentation

CancelResponse

enum class nros::CancelResponse : int32_t

strong

Cancel acceptance response returned from the user's cancel callback.

Enumerator
Reject
Accept

ErrorCode

enum class nros::ErrorCode : int32_t

strong

Error codes returned by nros-cpp functions.

Values match the C nros_cpp_ret_t enum in <nros/nros_cpp_generated.h>.

Enumerator
Ok	Success.
Error	Generic failure not covered by a more specific code.
Timeout	Operation deadline elapsed before completion.
InvalidArgument	Null pointer, empty topic name, or out-of-range value.
NotInitialized	nros::init() was never called or the entity is in a default state. See is_valid() on entity classes.
Full	Static pool exhausted (executor slots, subscription buffers, …).
TryAgain	Transient — no data ready yet (non-blocking take). Retry later.
Reentrant	A blocking call was made from inside a callback.
TransportError	Underlying zenoh-pico / DDS transport rejected the operation.

GoalResponse

enum class nros::GoalResponse : int32_t

strong

Goal acceptance response returned from the user's goal callback.

Enumerator
Reject
AcceptAndExecute
AcceptAndDefer

GoalStatus

enum class nros::GoalStatus : int8_t

strong

Mirror of action_msgs/msg/GoalStatus — lifecycle state reported by for_each_active_goal.

Enumerator
Unknown
Accepted
Executing
Canceling
Succeeded
Canceled
Aborted

Function Documentation

create_node()

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

inline

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 "/".

global_handle()

void * nros::global_handle ( )

inline

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 nros::init ( const char *  locator, uint8_t  domain_id, const char *  session_name  )

inline

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.

init() [2/2]

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

inline

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_with_launch()

Result nros::init_with_launch ( const char *  path, int  argc = 0, char **  argv = nullptr, const char *  session_name = nullptr  )

inline

Phase 212.L.5 Pattern 2 — explicit-path variant of [init_with_launch_auto].

Verifies path exists (so misspelled paths fail fast) but does NOT yet parse the XML — the env overlay is the active source today. See the auto variant's notes for the follow-up plan.

init_with_launch_auto()

Result nros::init_with_launch_auto ( int  argc = 0, char **  argv = nullptr, const char *  session_name = nullptr  )

inline

Phase 212.L.5 Pattern 2 — launch-aware init.

Resolves runtime knobs (domain id, locator, RMW choice) in this order:

1. $NROS_RUNTIME_OVERLAY (JSON sidecar emitted by nros launch --emit-runtime-overlay). NOT yet consumed — placeholder for the follow-up wave.
2. Launch XML at <CARGO_MANIFEST_DIR>/launch/*.xml. NOT yet parsed — the runtime trusts the launcher to project params/remaps into the child env before exec().
3. Env vars: ROS_DOMAIN_ID, NROS_LOCATOR, RMW_IMPLEMENTATION / NROS_RMW. This is the active overlay channel today.

argc / argv are reserved for the structured --ros-args parse that lands with the runtime-overlay wave. They are accepted and ignored for forward-compat.

session_name falls back to "nros_cpp" when null (matches the 2-arg init overload).

make_node()

Expected< Node > nros::make_node ( const char *  name, const char *  ns = nullptr  )

inline

Phase 123.B.4 — value-returning factory. Wraps create_node in the Expected<Node> envelope so users can write auto n = nros::make_node("foo"); in the rclcpp-style.

ok()

bool nros::ok ( )

inline

Check if the nros session is initialized.

shutdown()

Result nros::shutdown ( )

inline

Shut down the nros session.

Closes the middleware connection and frees all resources.

spin() [1/2]

Result nros::spin ( )

inline

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 nros::spin ( uint32_t  duration_ms, int32_t  poll_ms = 10  )

inline

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 nros::spin_once ( int32_t  timeout_ms = 10 )

inline

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.

Variable Documentation

PUBLISHER_TOPIC_NAME_MAX

constexpr size_t nros::PUBLISHER_TOPIC_NAME_MAX = 256

staticconstexpr

Maximum topic name length stored inside nros::Publisher<M> (256). The topic name is owned C++-side, not inside the runtime handle.

SUBSCRIPTION_TOPIC_NAME_MAX

constexpr size_t nros::SUBSCRIPTION_TOPIC_NAME_MAX = 256

staticconstexpr

Maximum topic name length stored inside nros::Subscription<M>. Mirrors PUBLISHER_TOPIC_NAME_MAX. Phase 87.6 thin-wrapper refactor: topic name owned C++-side, not inside a runtime handle.