Tier-1 status events: liveliness changes, deadline misses, message loss. More...

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

Include dependency graph for rmw_event.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	rmw_count_status_t
union	rmw_event_payload_t
struct	rmw_incompatible_type_status_t
struct	rmw_liveliness_changed_status_t
struct	rmw_matched_status_t

Typedefs
typedef void(*	rmw_event_callback_t) (const void *user_data, size_t number_of_events)
typedef void(*	rmw_status_event_callback_t) (rmw_event_type_t kind, const rmw_event_payload_t payload, void user_context)

Enumerations

enum rmw_event_type_t {
NROS_RMW_EVENT_LIVELINESS_CHANGED = 0 , NROS_RMW_EVENT_REQUESTED_DEADLINE_MISSED = 1 , NROS_RMW_EVENT_MESSAGE_LOST = 2 , NROS_RMW_EVENT_LIVELINESS_LOST = 3 ,
NROS_RMW_EVENT_OFFERED_DEADLINE_MISSED = 4 , NROS_RMW_EVENT_PUBLICATION_MATCHED = 5 , NROS_RMW_EVENT_SUBSCRIPTION_MATCHED = 6 , NROS_RMW_EVENT_PUBLISHER_INCOMPATIBLE_TYPE = 7 ,
NROS_RMW_EVENT_SUBSCRIPTION_INCOMPATIBLE_TYPE = 8
}

Detailed Description

Tier-1 status events: liveliness changes, deadline misses, message loss.

The status-event surface for the nros RMW C vtable. Backends advertise per-event support; applications register a callback per (entity, event kind) pair.

Dispatch model. Callback-on-entity. Backends fire registered callbacks from inside drive_io when the event is detected — same thread, same priority, same constraints as message callbacks. No waitset, no take-event polling. See book/src/communicate/qos-status-events.md and book/src/extending/rmw-vs-upstream.md Section 8 for the design.

Matched and incompatible-type events (issue 1972). Iron/Jazzy's RMW_EVENT_{PUBLICATION,SUBSCRIPTION}_MATCHED and RMW_EVENT_{PUBLISHER,SUBSCRIPTION}_INCOMPATIBLE_TYPE are values 5..8, APPENDED. Upstream inserted them in the middle of its enum; ours was never value-compatible with upstream's (ours numbers LIVELINESS_LOST 3, upstream numbers it 6), so appending keeps every existing value and every compiled backend's switch arms. They travel through the same *_event_init / *_take_event slots as the Tier-1 kinds — no new slot.

Upstream's QOS_INCOMPATIBLE is still surfaced synchronously at create-time as NROS_RMW_RET_INCOMPATIBLE_QOS rather than as a runtime event.

Typedef Documentation

◆ rmw_event_callback_t

typedef void(* rmw_event_callback_t) (const void *user_data, size_t number_of_events)

Upstream rmw_event_callback_t — the callback the set_on_new_* slots install. Distinct from rmw_status_event_callback_t above, which is the DDS STATUS-event callback; upstream binds this name to this shape and we now match it.

◆ rmw_status_event_callback_t

typedef void(* rmw_status_event_callback_t) (rmw_event_type_t kind, const rmw_event_payload_t *payload, void *user_context)

User callback invoked when an event fires.

Parameters

kind	Identifies which member of `payload` is valid.
payload	Pointer is valid for the duration of this call only — copy fields if needed beyond return.
user_context	Opaque pointer registered with the callback.

Threading. Invoked on whatever context the BACKEND delivers on, which is not uniform and is not drive_io. This paragraph claimed "invoked from inside `drive_io` on the executor thread" until 2026-08-25; no backend did that, and the claim was load-bearing — it was the stated reason rmw_take_event could be declined (issue 0780). zenoh fires from take and has_data; a DDS backend's listeners fire on its own worker thread.

So: must not block, and must assume it may be running concurrently with the executor. A backend with no safe context to deliver from should leave *_event_init NULL and implement *_take_event instead, which hands the caller the deferral upstream gets from its wait set.

Enumeration Type Documentation

◆ rmw_event_type_t

enum rmw_event_type_t

Status event kinds. Stable integer values; new kinds extend the enum at the END, never in the middle.

Enumerator
NROS_RMW_EVENT_LIVELINESS_CHANGED	Subscriber: a tracked publisher's liveliness state changed.
NROS_RMW_EVENT_REQUESTED_DEADLINE_MISSED	Subscriber: an expected sample didn't arrive within the configured deadline.
NROS_RMW_EVENT_MESSAGE_LOST	Subscriber: backend dropped a sample (overflow / etc.).
NROS_RMW_EVENT_LIVELINESS_LOST	Publisher: this publisher missed its own liveliness assertion.
NROS_RMW_EVENT_OFFERED_DEADLINE_MISSED	Publisher: this publisher promised X Hz, fell behind.
NROS_RMW_EVENT_PUBLICATION_MATCHED	Publisher: the set of subscriptions matched to it changed (one appeared or left). Payload: matched. Upstream RMW_EVENT_PUBLICATION_MATCHED (Iron+), issue 1972.
NROS_RMW_EVENT_SUBSCRIPTION_MATCHED	Subscription: the set of publishers matched to it changed. Payload: matched. Upstream RMW_EVENT_SUBSCRIPTION_MATCHED.
NROS_RMW_EVENT_PUBLISHER_INCOMPATIBLE_TYPE	Publisher: an endpoint on the same topic was seen with a DIFFERENT type. Payload: incompatible_type. Upstream RMW_EVENT_PUBLISHER_INCOMPATIBLE_TYPE.
NROS_RMW_EVENT_SUBSCRIPTION_INCOMPATIBLE_TYPE	Subscription: an endpoint on the same topic was seen with a DIFFERENT type. Payload: incompatible_type. Upstream RMW_EVENT_SUBSCRIPTION_INCOMPATIBLE_TYPE.

Data Structures