C function table for plugging third-party RMW backends into nros. More...

#include <stdint.h>
#include <stddef.h>
#include "nros/rmw_ret.h"
#include "nros/rmw_entity.h"
#include "nros/rmw_event.h"

Include dependency graph for rmw_vtable.h:

Go to the source code of this file.

Data Structures
struct	nros_rmw_vtable_t

Macros
#define	NROS_RMW_REGISTER_BACKEND(REGISTER_FN)

Functions
const nros_rmw_vtable_t *	nros_rmw_cffi_lookup (const char *name)

nros_rmw_ret_t	nros_rmw_cffi_register (const nros_rmw_vtable_t *vtable)

nros_rmw_ret_t	nros_rmw_cffi_register_named (const char name, const nros_rmw_vtable_t vtable)

size_t	nros_rmw_cffi_registered_names (const char **buf, size_t cap)

size_t	nros_rmw_cffi_walk_init_section (void)

Detailed Description

C function table for plugging third-party RMW backends into nros.

Implement the functions in nros_rmw_vtable_t and call nros_rmw_cffi_register() before creating any nros sessions.

Storage ownership. The runtime owns the entity-struct storage (nros_rmw_session_t, nros_rmw_publisher_t, nros_rmw_subscriber_t, nros_rmw_service_server_t, nros_rmw_service_client_t). Each create_* call receives a runtime-allocated, zero-initialised struct via the out pointer; the backend writes its backend_data (and can_loan_messages for pub/sub) into it. The runtime fills the metadata fields (topic_name, type_name, qos) before calling create_*; the backend reads them through the same struct.

destroy_* releases the backend's backend_data only. The struct shell stays valid until the runtime drops its owner.

Return-value conventions.

open / close / drive_io / create_* / publish_raw / send_reply: NROS_RMW_RET_OK on success, negative nros_rmw_ret_t constant on error (see <nros/rmw_ret.h>).
try_recv_raw / try_recv_request / call_raw: non-negative = bytes produced, negative = nros_rmw_ret_t error.
has_data / has_request: 1 = yes, 0 = no.
destroy_*: void (best-effort cleanup).

Macro Definition Documentation

◆ NROS_RMW_REGISTER_BACKEND

#define NROS_RMW_REGISTER_BACKEND ( REGISTER_FN )

Phase 249 P4b.2 — convenience macro for static-library backends. Place in exactly one TU per backend to self-register the backend on library load. REGISTER_FN is a no-arg function that calls nros_rmw_cffi_register_named for the backend.

Example: static void zenoh_register(void) { nros_rmw_cffi_register_named("zenoh", &VTABLE); } NROS_RMW_REGISTER_BACKEND(zenoh_register)

HOSTED (Rust + C/C++ on a hosted loader): the macro expands to an .init_array constructor (__attribute__((constructor))) that the loader fires before main() — hence before nros_support_init / nros::init — calling REGISTER_FN. The --whole-archive link keeps this object's .init_array slot. nros_rmw_cffi_register_named is idempotent (same-name overwrite), so re-registration is harmless. This consolidates the former linkme section walk onto the ctor (RFC-0042 §D3.3; the linkme distributed slice / section walker is deleted).

EMBEDDED (bare-metal / RTOS: Zephyr, NuttX, esp-idf, VxWorks): the loader does not run .init_array constructors on the startup path, so the macro expands to nothing. Registration is wired explicitly by the board / typed carrier via an explicit nros_rmw_<x>_register() call (phase-249 P1). For C/C++-via-cmake the nano_ros_link_rmw strong stub is the primary registration trigger (P2b/P4a); this hosted ctor is belt-and-suspenders.

Gating mirrors the cyclonedds vtable.cpp constructor (off the RTOS targets) and requires GCC/Clang constructor-attribute support.

Function Documentation

◆ nros_rmw_cffi_lookup()

const nros_rmw_vtable_t * nros_rmw_cffi_lookup ( const char * name )

Look up a backend's vtable by name. Returns NULL if no backend is registered under name. The returned pointer is valid for the program's lifetime.

◆ nros_rmw_cffi_register()

nros_rmw_ret_t nros_rmw_cffi_register ( const nros_rmw_vtable_t * vtable )

Register a custom RMW backend under the implicit name "default". Legacy single-arg form retained for source compatibility with backend ctors authored before the named registry (Phase 104.B.2).

Deprecated (Phase 128.B.5): every in-tree backend now calls nros_rmw_cffi_register_named with its canonical name. The unnamed shim will be removed in a follow-up phase. Returns NROS_RMW_RET_OK.

◆ nros_rmw_cffi_register_named()

nros_rmw_ret_t nros_rmw_cffi_register_named	(	const char *	name,
		const nros_rmw_vtable_t *	vtable
	)

Phase 104.B.2 — register a backend under a stable name. Multiple backends can coexist (bridge nodes); consumers select via nros_rmw_cffi_lookup or the higher-level Executor::node_builder(...).rmw(...) path.

Names: UTF-8, NUL-terminated, ≤ 31 bytes (excluding NUL). Reserved: "zenoh", "dds", "xrce", "cyclonedds", future "uorb". "default" is the implicit name used by nros_rmw_cffi_register.

Duplicate registration of the same name overwrites the previous vtable (idempotent for ctor-fires-twice).

Returns:

NROS_RMW_RET_OK on success.
NROS_RMW_RET_INVALID_ARGUMENT if name or vtable is NULL, the name is empty, or exceeds 31 bytes.
NROS_RMW_RET_ERROR if the registry is full (NROS_RMW_MAX_BACKENDS reached).

◆ nros_rmw_cffi_registered_names()

size_t nros_rmw_cffi_registered_names	(	const char **	buf,
		size_t	cap
	)

Diagnostic helper — fills buf with pointers to up to cap registered backend names. Returns the total number of registered backends (may exceed cap; caller can re-query with a larger buffer). Pointer-valid for the program's lifetime. Pass buf=NULL, cap=0 to query the count only.

◆ nros_rmw_cffi_walk_init_section()

size_t nros_rmw_cffi_walk_init_section ( void )

Phase 128.A.2 — walk the .nros_rmw_init linker section, invoking every backend init entry exactly once. Idempotent; subsequent calls are no-ops. Returns the number of entries invoked on this call (0 on the second and later calls, or when no nros-rmw-* library is linked).

Called automatically from Executor::open / nros::init; backends should not call this themselves.

Data Structures

Macros

Functions