rmw_vtable.h

Go to the documentation of this file.

#ifndef NROS_RMW_VTABLE_H
#define NROS_RMW_VTABLE_H
 
/* Phase 376 W3.a — this header defines the GENERIC RMW ABI: its types are
 * `rmw_publisher_t`, `rmw_ret_t`, and so on, with no vendor prefix, because a
 * backend author implements RMW rather than nano-ros.
 *
 * That makes it impossible to share a translation unit with upstream's
 * `<rmw/rmw.h>`, which defines the same names differently. Refuse LOUDLY rather
 * than let one definition silently win a redefinition race — two types of one
 * name whose layouts disagree is the class this repo has already paid for three
 * times in hand-mirrored FFI structs.
 *
 * A target image never links real rmw, and host-side consumers reach the
 * backend through Rust, so nothing in this repo trips this today. It exists for
 * the day something does. */
#if defined(RMW_RMW_H_) || defined(RMW__RMW_H_)
#error "nros/rmw_vtable.h defines the generic RMW ABI and cannot share a translation unit with upstream <rmw/rmw.h>. Include one or the other."
#endif
 
#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
 
#include "nros/rmw_ret.h"
#include "nros/rmw_entity.h"
#include "nros/rmw_event.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ---- Phase 376 W4 — graph enumeration visitors ----
 *
 * Upstream returns `rcutils_string_array_t` and `rmw_names_and_types_t`, which
 * ALLOCATE — two levels deep for names-and-types. There is no allocator at this
 * seam, and a caller-provides-the-buffer shape is worse than it looks: the ROS
 * graph has no bound the CALLER can know, so a 128 KiB image would have to
 * reserve permanently for the worst graph it might ever meet, and the backend
 * would still have to materialise the whole list to fill the buffer.
 *
 * So enumeration is a VISITOR. Peak extra RAM is one entry, the backend streams
 * from state it already holds, and a caller with a bound stops early by
 * returning `false` — a normal outcome, not a truncation error. Same shape as
 * `process_raw_in_place` and `publish_streamed` already use here.
 *
 * Every string handed to a visitor is BORROWED for that call only.
 */
 
typedef bool (*rmw_node_visit_fn)(void *ctx, const char *node_name,
    const char *node_namespace, const char *enclave);
 
typedef bool (*rmw_names_and_types_visit_fn)(void *ctx, const char *name,
    const char *const *types, size_t types_count);
 
typedef bool (*rmw_topic_endpoint_info_visit_fn)(void *ctx,
    const rmw_topic_endpoint_info_t *info);
 
typedef struct rmw_loan_token_t rmw_loan_token_t;
 
#define NROS_RMW_VISITOR_DEFINED 1
typedef struct rmw_node_visitor_t {
    /* Named `visit`, not `fn`: `fn` is a Rust keyword, and this struct is
       mirrored into Rust by bindgen (RFC-0054 — the C header is the SSoT,
       so the C side is where a name has to be chosen that both languages
       can spell). */
    rmw_node_visit_fn visit;
    void *ctx;
} rmw_node_visitor_t;
 
typedef struct rmw_names_and_types_visitor_t {
    /* Named `visit`, not `fn`: `fn` is a Rust keyword, and this struct is
       mirrored into Rust by bindgen (RFC-0054 — the C header is the SSoT,
       so the C side is where a name has to be chosen that both languages
       can spell). */
    rmw_names_and_types_visit_fn visit;
    void *ctx;
} rmw_names_and_types_visitor_t;
 
typedef struct rmw_topic_endpoint_info_visitor_t {
    /* Named `visit`, not `fn`: `fn` is a Rust keyword, and this struct is
       mirrored into Rust by bindgen (RFC-0054 — the C header is the SSoT,
       so the C side is where a name has to be chosen that both languages
       can spell). */
    rmw_topic_endpoint_info_visit_fn visit;
    void *ctx;
} rmw_topic_endpoint_info_visitor_t;
 
 
/* Phase 376 W5 — teardown and loan-return REPORT.
 *
 * These six returned `void`. That was never a target constraint: upstream
 * returns `rmw_ret_t` from all of them, and a backend that cannot release a
 * handle — a queue still draining, a token from another publisher, a
 * double-destroy — had no way to say so. The runtime then reported success it
 * had not verified, which on an RTOS is the difference between a leak that
 * shows up in a log and a leak that shows up as an allocation failure an hour
 * later with no provenance.
 *
 * A caller that genuinely has nothing to do with the status may ignore it;
 * `void` denied it the choice. Backends that cannot fail return
 * `NROS_RMW_RET_OK` unconditionally, which costs one instruction and keeps the
 * signature honest for the ones that can.
 */
typedef struct nros_rmw_vtable_t {
    /* ---- Session lifecycle ---- */
    rmw_ret_t (*create_session)(const char *locator, uint8_t mode,
                           uint32_t domain_id, const char *node_name,
                           const rmw_session_options_t *options,
                           rmw_session_t *out);
    rmw_ret_t (*destroy_session)(rmw_session_t *session);
    rmw_ret_t (*drive_io)(rmw_session_t *session, int32_t timeout_ms);
 
    /* ---- Publisher ---- */
    rmw_ret_t (*create_publisher)(const rmw_node_t *node,
        const rmw_message_type_support_t *type_support,
        const char *topic_name,
        uint32_t domain_id, const rmw_qos_profile_t *qos,
        const rmw_publisher_options_t *options,
        rmw_publisher_t *out);
    rmw_ret_t (*destroy_publisher)(rmw_publisher_t *publisher);
    rmw_ret_t (*publish)(const rmw_publisher_t *publisher,
        rmw_byte_span_t payload);
 
    /* ---- Subscription (phase-301: rmw's term; was `subscriber`) ---- */
    rmw_ret_t (*create_subscription)(const rmw_node_t *node,
        const rmw_message_type_support_t *type_support,
        const char *topic_name,
        uint32_t domain_id, const rmw_qos_profile_t *qos,
        const rmw_subscription_options_t *options,
        rmw_subscription_t *out);
    rmw_ret_t (*destroy_subscription)(rmw_subscription_t *subscription);
    rmw_ret_t (*take)(const rmw_subscription_t *subscription,
        rmw_mut_byte_span_t *out, bool *taken);
    rmw_ret_t (*has_data)(rmw_subscription_t *subscription,
        bool *out_has_data);
 
    /* ---- Service (phase-301: rmw's term; was `service_server`) ---- */
    /* Phase 193.1b — `qos` applies to both the request + reply endpoints
       (one profile per service, mirrors create_publisher/subscription). */
    rmw_ret_t (*create_service)(const rmw_node_t *node,
        const rmw_service_type_support_t *type_support,
        const char *service_name,
        uint32_t domain_id, const rmw_qos_profile_t *qos,
        rmw_service_t *out);
    rmw_ret_t (*destroy_service)(rmw_service_t *server);
    rmw_ret_t (*take_request)(const rmw_service_t *server,
        rmw_mut_byte_span_t *request, int64_t *seq_out, bool *taken);
    rmw_ret_t (*has_request)(rmw_service_t *server,
        bool *out_has_request);
    rmw_ret_t (*send_response)(const rmw_service_t *server,
        int64_t seq, rmw_byte_span_t response);
 
    /* ---- Client (phase-301: rmw's term; was `service_client`) ---- */
    rmw_ret_t (*create_client)(const rmw_node_t *node,
        const rmw_service_type_support_t *type_support,
        const char *service_name,
        uint32_t domain_id, const rmw_qos_profile_t *qos,
        rmw_client_t *out);
    rmw_ret_t (*destroy_client)(rmw_client_t *client);
 
    rmw_ret_t (*send_request)(const rmw_client_t *client,
        rmw_byte_span_t request, int64_t *sequence_id);
 
    rmw_ret_t (*take_response)(const rmw_client_t *client,
        rmw_mut_byte_span_t *reply, int64_t *seq_out, bool *taken);
 
    /* ---- Phase 108 — status events (optional) ---- */
    rmw_ret_t (*subscription_event_init)(
        const rmw_subscription_t *subscription,
        rmw_event_type_t  kind,
        uint32_t               deadline_ms,
        rmw_status_event_callback_t cb,
        void                  *user_context);
 
    /* ---- Status events: how the three upstream parts map here ----
     *
     * Upstream's model is three-part: `*_event_init` fills an `rmw_event_t`
     * HANDLE, `rmw_event_set_callback` attaches a callback to that handle, and
     * `rmw_take_event` polls it for a status.
     *
     *  - `rmw_event_set_callback` is FUSED into `*_event_init`, which takes the
     *    callback directly. There is no handle to attach one to afterwards.
     *    What that costs is real and small: upstream can replace or clear a
     *    callback later, and we cannot.
     *
     *  - `rmw_take_event` is a SLOT (issue 0780), split per entity kind
     *    because we have no `rmw_event_t` to carry the entity — see
     *    `subscription_take_event` / `publisher_take_event` below.
     *
     * It was DECLINED until 2026-08-25 on two clauses that both turned out
     * false, and they are worth recording because each sounded right:
     *
     *   "Upstream polls because the WAIT SET said one was ready, and the wait
     *   set is declined here, so a poll would be blind."
     *      — This ABI is a poll-WITHOUT-a-wait-set design by construction.
     *        `has_data`'s own doc says so: "the poll a loop with no wait-set
     *        needs, and it allocates nothing." A poll with no wait set is the
     *        model here, not a blindness.
     *
     *   "Our callback already runs on the safe context — from inside
     *   `drive_io`, on the executor thread, never an ISR or a transport
     *   thread."
     *      — True of no backend. zenoh fires from `try_recv_raw` and
     *        `has_data`; cyclonedds' DDS listeners fire on Cyclone's own
     *        worker thread while its `drive_io` is a sleep with no callback
     *        path at all. So a cyclonedds status event has nowhere safe to be
     *        delivered from, and buffer-plus-poll IS `take_event`. A
     *        per-backend fact stated ABI-wide — the same shape as the
     *        network-flow decline W5 flipped.
     */
 
    rmw_ret_t (*subscription_take_event)(const rmw_subscription_t *subscription,
        rmw_event_type_t kind, rmw_event_payload_t *out, bool *taken);
 
    rmw_ret_t (*publisher_take_event)(const rmw_publisher_t *publisher,
        rmw_event_type_t kind, rmw_event_payload_t *out, bool *taken);
 
    rmw_ret_t (*publisher_event_init)(
        const rmw_publisher_t  *publisher,
        rmw_event_type_t  kind,
        uint32_t               deadline_ms,
        rmw_status_event_callback_t cb,
        void                  *user_context);
 
    rmw_ret_t (*publisher_assert_liveliness)(
        const rmw_publisher_t *publisher);
 
    rmw_ret_t (*next_deadline_ms)(const rmw_session_t *session,
        uint32_t *out_ms, bool *has_deadline);
 
    rmw_ret_t (*set_wake_callback)(rmw_session_t *session,
                                         void (*cb)(void *ctx),
                                         void *ctx);
 
    rmw_ret_t (*borrow_loaned_message)(const rmw_publisher_t *publisher,
                                size_t                 requested_len,
                                rmw_mut_byte_span_t   *out_slot,
                                rmw_loan_token_t     **out_token);
 
    rmw_ret_t (*publish_loaned_message)(const rmw_publisher_t *publisher,
                                  rmw_loan_token_t     *token,
                                  size_t                actual_len);
 
    rmw_ret_t (*return_loaned_message_from_publisher)(const rmw_publisher_t *publisher, rmw_loan_token_t *token);
 
    rmw_ret_t (*take_loaned_message)(const rmw_subscription_t *subscription,
                           rmw_byte_span_t       *out_view,
                           rmw_loan_token_t     **out_token,
                           bool                  *taken);
 
    rmw_ret_t (*return_loaned_message_from_subscription)(const rmw_subscription_t *subscription, rmw_loan_token_t *token);
 
    rmw_ret_t (*service_server_is_available)(
        const rmw_client_t *client,
        bool *out_available);
 
    rmw_ret_t (*take_sequence)(const rmw_subscription_t *subscription,
                                  uint8_t              *buf,
                                  size_t                per_msg_cap,
                                  size_t                max_msgs,
                                  size_t               *out_lens,
                                  size_t               *taken);
 
    rmw_ret_t (*publish_streamed)(
        rmw_publisher_t *publisher,
        void (*size_cb)(size_t *out_total_len, void *user_ctx),
        void (*chunk_cb)(uint8_t *out_buf, size_t cap,
                         size_t *out_written, void *user_ctx),
        void *user_ctx);
 
    rmw_ret_t (*ping_session)(
        rmw_session_t *session,
        int32_t             timeout_ms);
 
    /* ---- Phase 231 (RFC-0038) — zero-copy in-place subscription take ---- */
 
    rmw_ret_t (*subscription_supports_in_place)(
        rmw_subscription_t *subscription,
        bool *out_supports);
 
    rmw_ret_t (*process_raw_in_place)(
        rmw_subscription_t *subscription,
        void                  *ctx,
        void                 (*cb)(void *ctx, rmw_byte_span_t message),
        bool                  *out_processed);
    /* ---- Phase 376 W4 — identity + matched counts (all optional) ---- */
 
    const char *(*get_implementation_identifier)(void);
 
    const char *(*get_serialization_format)(void);
 
    bool (*feature_supported)(rmw_feature_t feature);
 
    rmw_ret_t (*get_gid_for_publisher)(const rmw_publisher_t *publisher,
        rmw_gid_t *gid);
 
    rmw_ret_t (*publisher_count_matched_subscriptions)(
        const rmw_publisher_t *publisher, size_t *subscription_count);
 
    rmw_ret_t (*subscription_count_matched_publishers)(
        const rmw_subscription_t *subscription, size_t *publisher_count);
 
    /* ---- Phase 376 W4 — QoS read-back + clean shutdown (all optional) ---- */
 
    rmw_ret_t (*publisher_get_actual_qos)(const rmw_publisher_t *publisher,
        rmw_qos_profile_t *qos);
 
    rmw_ret_t (*subscription_get_actual_qos)(const rmw_subscription_t *subscription,
        rmw_qos_profile_t *qos);
 
    rmw_ret_t (*client_request_publisher_get_actual_qos)(const rmw_client_t *client,
        rmw_qos_profile_t *qos);
 
    rmw_ret_t (*client_response_subscription_get_actual_qos)(const rmw_client_t *client,
        rmw_qos_profile_t *qos);
 
    rmw_ret_t (*service_request_subscription_get_actual_qos)(const rmw_service_t *service,
        rmw_qos_profile_t *qos);
 
    rmw_ret_t (*service_response_publisher_get_actual_qos)(const rmw_service_t *service,
        rmw_qos_profile_t *qos);
 
    rmw_ret_t (*publisher_wait_for_all_acked)(const rmw_publisher_t *publisher,
        uint32_t timeout_ms);
 
    /* ---- Phase 376 W4 — with-info takes + entity callbacks (optional) ---- */
 
    rmw_ret_t (*take_with_info)(const rmw_subscription_t *subscription,
        rmw_mut_byte_span_t *message, bool *taken, rmw_message_info_t *message_info);
 
    rmw_ret_t (*take_loaned_message_with_info)(const rmw_subscription_t *subscription,
        rmw_byte_span_t *out_view, rmw_loan_token_t **out_token,
        bool *taken, rmw_message_info_t *message_info);
 
    /* ---- Phase 376 W4 — graph introspection (all optional) ----
     *
     * NONE of these may block on the wire, and none takes a timeout: this
     * vtable's premise is that no background transport thread is assumed, so a
     * query-based backend keeps a `drive_io`-fed cache or leaves the slot NULL
     * rather than stalling the executor's only thread inside an introspection
     * call.
     *
     * A 128 KiB target cannot hold a graph cache, and NULL is the expected
     * answer there — the runtime surfaces UNSUPPORTED. XRCE cannot enumerate
     * participants at all.
     */
 
    rmw_ret_t (*get_node_names)(const rmw_session_t *session,
        rmw_node_visitor_t visitor);
 
    rmw_ret_t (*get_topic_names_and_types)(const rmw_session_t *session,
        bool no_demangle, rmw_names_and_types_visitor_t visitor);
 
    rmw_ret_t (*get_service_names_and_types)(const rmw_session_t *session,
        rmw_names_and_types_visitor_t visitor);
 
    rmw_ret_t (*get_publisher_names_and_types_by_node)(const rmw_session_t *session,
        const char *node_name, const char *node_namespace, bool no_demangle,
        rmw_names_and_types_visitor_t visitor);
 
    rmw_ret_t (*get_subscriber_names_and_types_by_node)(const rmw_session_t *session,
        const char *node_name, const char *node_namespace, bool no_demangle,
        rmw_names_and_types_visitor_t visitor);
 
    rmw_ret_t (*get_service_names_and_types_by_node)(const rmw_session_t *session,
        const char *node_name, const char *node_namespace,
        rmw_names_and_types_visitor_t visitor);
 
    rmw_ret_t (*get_client_names_and_types_by_node)(const rmw_session_t *session,
        const char *node_name, const char *node_namespace,
        rmw_names_and_types_visitor_t visitor);
 
    rmw_ret_t (*get_publishers_info_by_topic)(const rmw_session_t *session,
        const char *topic_name, bool no_mangle,
        rmw_topic_endpoint_info_visitor_t visitor);
 
    rmw_ret_t (*get_subscriptions_info_by_topic)(const rmw_session_t *session,
        const char *topic_name, bool no_mangle,
        rmw_topic_endpoint_info_visitor_t visitor);
 
    rmw_ret_t (*count_publishers)(const rmw_session_t *session,
        const char *topic_name, size_t *count);
 
    rmw_ret_t (*count_subscribers)(const rmw_session_t *session,
        const char *topic_name, size_t *count);
 
    rmw_ret_t (*node_get_graph_guard_condition)(rmw_session_t *session,
        rmw_event_callback_t callback, const void *user_data);
 
    /* ---- Phase 376 W4 — graph node lifecycle (optional) ----
     *
     * The rest of upstream's lifecycle group is deliberately absent, and the
     * absences are decisions rather than omissions:
     *
     *  - `rmw_init` / `rmw_shutdown` / `rmw_context_fini` are
     *    `create_session` / `destroy_session`. There is no second teardown
     *    phase: the session shell is caller-owned, so there is nothing left to
     *    free after the backend releases `backend_data`.
     *
     *  - `rmw_init_options_{init,copy,fini}` have nothing to do here. Upstream
     *    needs the trio because its options OWN heap and carry an
     *    `rcutils_allocator_t`, which cannot cross this seam; ours is a
     *    build-time POD, so "copy" is `=` and "fini" is nothing.
     *
     *    This does NOT decide what the options CARRY. Of Humble's eight
     *    fields, `create_session` takes `domain_id`; `implementation_identifier`
     *    and `impl` are answered elsewhere (the identity slot,
     *    `rmw_session_t::backend_data`); `allocator` is declined ABI-wide and
     *    `instance_id` is rcl-side process identity. `security_options` is
     *    declined on the target: it is a DDS-SROS2 keystore PATH plus an
     *    enforcement switch, and neither a filesystem nor a security plugin
     *    exists where this ABI runs. `localhost_only` and `enclave` are real
     *    GAPS — issue 0785, to be carried by whatever shape issue 0808 gives
     *    backend-private session config, because this flat argument list
     *    cannot grow either without another ABI break.
     *
     *    `discovery_options` is NOT in this list: it is an IRON field, and the
     *    recorded contract is Humble. It was named here until issue 0785, the
     *    third unchecked sentence about an upstream struct in this campaign
     *    (issue 0777 supplied the other two). Read the header, not the memory.
     *
     *  - `rmw_wait`, the wait set, and the guard conditions are declined
     *    together, because `has_data` / `has_request` + `drive_io` +
     *    `set_wake_callback` + `next_deadline_ms` ARE upstream's `rmw_wait`,
     *    decomposed. What a vtable `wait` would add is only the BLOCK, moved
     *    from the platform into the backend — and the block cannot live there:
     *    one executor drives sessions from several backends at once
     *    (`create_node_on(name, rmw)`), timers fire off the platform clock, and
     *    guard conditions fire from another thread or an ISR. A backend can
     *    only block on its own handles. `next_deadline_ms` is exactly the piece
     *    of `rmw_wait` that CANNOT be answered above the seam, and it is
     *    already a slot; that is the decomposition working, not a gap.
     */
 
    rmw_ret_t (*create_node)(rmw_session_t *session,
        const char *name, const char *namespace_,
        rmw_node_t *out);
 
    rmw_ret_t (*destroy_node)(rmw_node_t *node);
 
    rmw_ret_t (*set_log_severity)(rmw_log_severity_t severity);
 
    /* ---- Phase 403 W1 — receive-buffer sizing (optional) ---- */
 
    rmw_ret_t (*required_rx_bytes)(const char *type_name,
        const char *type_hash, size_t hint, size_t *out_bytes);
 
} nros_rmw_vtable_t;
 
typedef enum nros_rmw_session_mode_t {
    NROS_RMW_SESSION_MODE_CLIENT = 0,
    NROS_RMW_SESSION_MODE_PEER = 1,
} nros_rmw_session_mode_t;
 
rmw_ret_t nros_rmw_cffi_register(const nros_rmw_vtable_t *vtable);
 
rmw_ret_t nros_rmw_cffi_register_named(const char *name,
                                            const nros_rmw_vtable_t *vtable);
 
const nros_rmw_vtable_t *nros_rmw_cffi_lookup(const char *name);
 
size_t nros_rmw_cffi_registered_names(const char **buf, size_t cap);
 
 
#if (defined(__GNUC__) || defined(__clang__)) && !defined(__ZEPHYR__) &&       \
    !defined(__NuttX__) && !defined(ESP_PLATFORM) && !defined(__VXWORKS__)
#define NROS_RMW_REGISTER_BACKEND(REGISTER_FN)                                 \
    __attribute__((constructor)) static void nros_rmw_ctor_##REGISTER_FN(      \
        void) {                                                                \
        (void) REGISTER_FN();                                                  \
    }
#else
/* Embedded / unsupported toolchain: board calls nros_rmw_<x>_register(). */
#define NROS_RMW_REGISTER_BACKEND(REGISTER_FN)
#endif
 
#ifdef __cplusplus
}
#endif
 
#endif /* NROS_RMW_VTABLE_H */