nros::Executor Class Reference

#include <executor.hpp>

Public Member Functions
Result	create_node (Node &out, const char *name, const char *ns=nullptr)
	Executor ()
	Default constructor — creates an uninitialized executor.
	Executor (Executor &&other)
void *	handle ()
NodeBuilder	node_builder (const char *name)
bool	ok () const
	Check if the executor is initialized.
Executor &	operator= (Executor &&other)
Result	ping (int32_t timeout_ms)
Result	shutdown ()
	Shut down the executor and close the middleware connection.
Result	spin (uint32_t duration_ms, int32_t poll_ms=10)
Result	spin_once (int32_t timeout_ms=10)
	~Executor ()
	Destructor — shuts down if still active.

Static Public Member Functions
static Result	create (Executor &out, const char *locator, uint8_t domain_id, const char *session_name)
static Result	create (Executor &out, const char *locator=nullptr, uint8_t domain_id=0)

Detailed Description

Explicit executor for managing ROS 2 entities and spinning.

Mirrors rclcpp::executors::SingleThreadedExecutor. Provides an explicit alternative to the global nros::init()/nros::spin_once() free functions.

The executor uses inline opaque storage — no heap allocation required.

Usage:

nros::Executor executor;
NROS_TRY(nros::Executor::create(executor));
 
nros::Node node;
NROS_TRY(executor.create_node(node, "my_node"));
 
// Create publishers, subscriptions, etc. on node...
 
while (executor.ok()) {
    executor.spin_once(10);
}
executor.shutdown();

Constructor & Destructor Documentation

Executor() [1/2]

nros::Executor::Executor ( )

inline

Default constructor — creates an uninitialized executor.

~Executor()

nros::Executor::~Executor ( )

inline

Destructor — shuts down if still active.

Executor() [2/2]

nros::Executor::Executor ( Executor &&  other )

inline

Member Function Documentation

create() [1/2]

static Result nros::Executor::create ( Executor &  out, const char *  locator, uint8_t  domain_id, const char *  session_name  )

inlinestatic

Create and initialize an executor with an explicit session name.

session_name flows through to the XRCE-DDS RMW backend as the per-process key derivation seed. Two processes sharing one XRCE Agent MUST use distinct names; see nros::init's named overload for the full discussion.

create() [2/2]

static Result nros::Executor::create ( Executor &  out, const char *  locator = nullptr, uint8_t  domain_id = 0  )

inlinestatic

Create and initialize an executor.

Opens a middleware connection. This is the explicit alternative to nros::init().

Parameters

out	Receives the initialized executor.
locator	Middleware locator (e.g., "tcp/127.0.0.1:7447"), or nullptr.
domain_id	ROS domain ID (0-232).

Returns

Result indicating success or failure.

create_node()

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

inline

Create a node on this executor.

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.

handle()

void * nros::Executor::handle ( )

inline

Get the raw executor storage (for advanced use).

Non-const: downstream FFI mutates executor state through this pointer (e.g. spin_once), so exposing it as const would be a lie. Callers that only need to observe the handle should do so through methods on Executor directly.

node_builder()

NodeBuilder nros::Executor::node_builder ( const char *  name )

inline

Phase 104.C.9 — chainable Node-creation builder.

Mirrors Rust's Executor::node_builder(name).rmw(...).locator(...) .domain_id(...).namespace(...).sched(...).build(). Use this when binding a Node to a specific RMW backend, locator, domain, or SchedContext. Definition follows the full NodeBuilder class in node.hpp.

ok()

bool nros::Executor::ok ( ) const

inline

Check if the executor is initialized.

operator=()

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

inline

ping()

Result nros::Executor::ping ( int32_t  timeout_ms )

inline

Phase 124.F.3 — session-level connectivity probe.

Wire-level round-trip ("is the peer / agent / router reachable?") with timeout_ms budget. Returns Result::success() on reply, ErrorCode::Timeout on no reply, ErrorCode::Unsupported when the active backend can't probe. Mirrors micro-ROS's rmw_uros_ping_agent.

Useful for reconnect-on-link-loss patterns — call periodically and tear down / re-open the executor on timeout.

shutdown()

Result nros::Executor::shutdown ( )

inline

Shut down the executor and close the middleware connection.

spin()

Result nros::Executor::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.

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

inline

Drive transport I/O and dispatch callbacks.

Processes pending subscriptions, timers, services, and guard conditions. Call this periodically in your main loop.

Parameters

timeout_ms

Maximum time to block waiting for I/O.

Returns

Result indicating success or failure.

---

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

• include/nros/executor.hpp
• include/nros/node.hpp