Crate nros_rmw_cffi 

C function table adapter for nros RMW backends.

This crate provides a vtable-based bridge so that backends written in C, C++, Zig, Ada, or any language with a C-compatible ABI can implement the nros Session / Publisher / Subscriber / service traits without writing Rust code.

Usage (C backend implementor)

1. Include <nros/rmw_vtable.h>
2. Implement all function pointers in nros_rmw_vtable_t
3. Call nros_rmw_cffi_register(&my_vtable) before creating sessions

Usage (Rust consumer)

Enable the rmw-cffi feature on nros and use Executor<CffiSession>.

Modules

section

RMW backend self-registration (Phase 249 P4b.1 — .init_array ctor).

Macros

nros_rmw_register_backend

Macro emitted by backend crates to self-register their vtable.

Structs

CffiPublisher

Publisher backed by a C vtable.

CffiRmw

RMW factory for the C function table backend.

CffiServiceClient

Service client backed by a C vtable.

CffiServiceServer

Service server backed by a C vtable.

CffiSession

Session backed by a C vtable.

CffiSubscriber

Subscriber backed by a C vtable.

NrosRmwCountStatus

Count payload mirror.

NrosRmwLivelinessChangedStatus

Liveliness payload mirror.

NrosRmwPublisher

Publisher entity. Mirrors nros_rmw_publisher_t.

NrosRmwQos

Full DDS-shaped QoS profile. Mirrors nros_rmw_qos_t from <nros/rmw_entity.h>.

NrosRmwServiceClient

Service-client entity. Mirrors nros_rmw_service_client_t.

NrosRmwServiceServer

Service-server entity. Mirrors nros_rmw_service_server_t.

NrosRmwSession

Per-process RMW session. Mirrors nros_rmw_session_t.

NrosRmwSubscriber

Subscriber entity. Mirrors nros_rmw_subscriber_t.

NrosRmwVtable

C function table for an RMW backend.

Enums

BackendResolution

Phase 128.A.3 — outcome of resolve_backend.

NrosRmwEventKind

Tier-1 event kinds. Stable u8 values matching nros_rmw_event_kind_t in the C header.

NrosRmwLivelinessKind

Liveliness kind values for NrosRmwQos::liveliness_kind.

Constants

MAX_BACKENDS

Compile-time max number of concurrently registered backends. Set via NROS_RMW_MAX_BACKENDS env var at build time (build.rs). Default 8.

NROS_RMW_QOS_PROFILE_DEFAULT

Standard rmw_qos_profile_default-equivalent.

NROS_RMW_QOS_PROFILE_PARAMETERS

Standard rmw_qos_profile_parameters-equivalent.

NROS_RMW_QOS_PROFILE_SENSOR_DATA

Standard rmw_qos_profile_sensor_data-equivalent.

NROS_RMW_QOS_PROFILE_SERVICES_DEFAULT

Standard rmw_qos_profile_services_default-equivalent.

NROS_RMW_QOS_PROFILE_SYSTEM_DEFAULT

Standard rmw_qos_profile_system_default-equivalent.

NROS_RMW_RET_AMBIGUOUS_BACKEND

Phase 128.A.3 — more than one backend is linked and no NROS_RMW=<name> selector was supplied. Caller must either set the env var or use Executor::open_multi.

NROS_RMW_RET_BAD_ALLOC

Memory allocation failed.

NROS_RMW_RET_BUFFER_TOO_SMALL

Caller buffer smaller than the data the backend wants to deliver.

NROS_RMW_RET_CONNECTION_FAILED

Phase 155.B.3 — backend reached the wire but couldn’t establish a session. Maps to / from TransportError::ConnectionFailed / Disconnected. Distinct from NROS_RMW_RET_ERROR so callers can tell “can’t reach the router” from “internal backend invariant tripped”.

NROS_RMW_RET_ERROR

Generic failure not covered by a more specific code.

NROS_RMW_RET_INCOMPATIBLE_ABI

Phase 115.A.2 — caller’s vtable struct has an abi_version the runtime doesn’t know. Returned by entry points that take a versioned vtable struct (nros_set_custom_transport, nros_cpp_set_custom_transport, …) when vtable.abi_version != NROS_RMW_*_ABI_VERSION_VN.

NROS_RMW_RET_INCOMPATIBLE_QOS

QoS profiles incompatible in a way the backend cannot reconcile.

NROS_RMW_RET_INVALID_ARGUMENT

Caller supplied a NULL pointer or an out-of-range value.

NROS_RMW_RET_LOAN_NOT_SUPPORTED

Backend does not support loaned messages on this entity, or slot in use.

NROS_RMW_RET_MESSAGE_TOO_LARGE

Incoming message exceeded the backend’s static capacity.

NROS_RMW_RET_NODE_NAME_NON_EXISTENT

Request referenced a node that does not exist in this session.

NROS_RMW_RET_NO_BACKEND

Phase 128.A.3 — Executor::open / nros::init could not pick a unique backend because no nros-rmw-* crate (or static lib) is linked into this binary.

NROS_RMW_RET_NO_DATA

No data on a non-blocking receive (distinct from TIMEOUT).

NROS_RMW_RET_OK

Operation completed successfully.

NROS_RMW_RET_TIMEOUT

Operation deadline elapsed before completion.

NROS_RMW_RET_TOPIC_NAME_INVALID

Topic, service, or action name failed validation.

NROS_RMW_RET_UNKNOWN_BACKEND

Phase 128.A.3 — selector pointed at a backend name that is not in the registry (mis-spelling or missing nros-rmw-<name> dep).

NROS_RMW_RET_UNSUPPORTED

The backend does not implement this operation.

NROS_RMW_RET_WOULD_BLOCK

Resource momentarily unavailable; caller should retry.

Functions

backend_registered

Phase 104.A — registry-presence probe. Returns true iff at least one backend is registered. Used by Executor::open to detect “user forgot to register a backend before opening the session” and fail with a meaningful error.

backend_resolution_to_ret

Phase 128.A.3 — map a BackendResolution to its canonical NrosRmwRet. BackendResolution::Single is not an error and returns NROS_RMW_RET_OK; callers needing the vtable should pattern-match on the resolution itself.

error_from_ret

Map a nros_rmw_ret_t returned by a C-side vtable function back to a TransportError for the Rust caller. Inverse of ret_from_error — used when nros-rmw-cffi’s CffiSession etc. receive a code from the registered C backend.

nros_rmw_cffi_lookup^⚠

Look up a backend’s vtable by name. Returns NULL if no backend is registered under name.

nros_rmw_cffi_register^⚠Deprecated

Register a custom RMW backend vtable (legacy single-arg form).

nros_rmw_cffi_register_named^⚠

Register a backend under a stable name. Multiple backends can coexist; consumers select via nros_rmw_cffi_lookup or the higher-level Executor::node_builder(...).rmw(...) path.

nros_rmw_cffi_registered_names^⚠

Diagnostic helper — fills buf with pointers to up to cap registered backend names. Returns the number of names available (may exceed cap). Pointer-valid for the program’s lifetime.

nros_rmw_cffi_set_custom_transport^⚠

Phase 115.A.2 — C entry point for installing a custom transport.

resolve_backend

Phase 128.A.3 — selection policy for the single-backend Executor::open / nros::init path.

ret_from_error

Map a TransportError to the corresponding nros_rmw_ret_t code.

Type Aliases

NrosRmwEventCallback

C callback signature. Matches nros_rmw_event_callback_t.

NrosRmwRet

Signed 32-bit status code mirroring the C nros_rmw_ret_t typedef. Zero on success; negative on error.

Unions

NrosRmwEventPayload

Borrow-shaped payload union mirror. C-side ABI — runtime-checked kind tag selects which member is valid.