Trait Publisher 

pub trait Publisher {
    type Error;

    // Required methods
    fn publish_raw(&self, data: &[u8]) -> Result<(), Self::Error>;
    fn buffer_error(&self) -> Self::Error;
    fn serialization_error(&self) -> Self::Error;

    // Provided methods
    fn publish_raw_with_attachment(
        &self,
        data: &[u8],
        _attachment: &[u8],
    ) -> Result<(), Self::Error> { ... }
    unsafe fn publish_streamed(
        &self,
        size_cb: unsafe extern "C" fn(out_total_len: *mut usize, user_ctx: *mut c_void),
        chunk_cb: unsafe extern "C" fn(out_buf: *mut u8, cap: usize, out_written: *mut usize, user_ctx: *mut c_void),
        user_ctx: *mut c_void,
    ) -> Result<(), Self::Error>
       where Self::Error: From<TransportError> { ... }
    fn publish<M: RosMessage>(
        &self,
        msg: &M,
        buf: &mut [u8],
    ) -> Result<(), Self::Error> { ... }
    fn supports_event(&self, _kind: EventKind) -> bool { ... }
    unsafe fn register_event_callback(
        &mut self,
        _kind: EventKind,
        _deadline_ms: u32,
        _cb: EventCallback,
        _user_ctx: *mut c_void,
    ) -> Result<(), Self::Error> { ... }
    fn unsupported_event_error(&self) -> Self::Error { ... }
    fn assert_liveliness(&self) -> Result<(), Self::Error> { ... }
}

Publisher trait for sending messages.

Threading

&self on publish_raw — implementors must allow concurrent publishes from multiple threads. Internal locking (or lock-free queues) is the backend’s responsibility.

Buffer ownership

data in publish_raw is borrowed for the duration of the call. The backend must either send it inline or copy into its own buffer before returning — the slice is invalid after the call.

Blocking

publish_raw is expected to be non-blocking on best-effort QoS and bounded-blocking on reliable QoS (waiting for outbound queue space). Backends should not block waiting for ack from a matched subscriber.

Required Associated Types

type Error

Error type for publish operations

Required Methods

fn publish_raw(&self, data: &[u8]) -> Result<(), Self::Error>

Publish a CDR-serialised message.

Returns once the message has been handed to the transport (queued or fired-and-forgotten depending on QoS). Does not wait for delivery.

fn buffer_error(&self) -> Self::Error

Return a buffer-too-small error (implementation specific)

fn serialization_error(&self) -> Self::Error

Return a serialization error (implementation specific)

Provided Methods

fn publish_raw_with_attachment( &self, data: &[u8], _attachment: &[u8], ) -> Result<(), Self::Error>

Phase 128.F.4 — publish with an opaque attachment block.

attachment rides alongside the payload at the wire layer. Receivers can read it back via Subscription::take_serialized_with_attachment.

Primary use case: cross-RMW bridges stamp a bridge_origin tag (the source backend’s RMW name) so a paired return bridge can deterministically drop echoed frames.

Default body delegates to publish_raw and discards the attachment — backends that do not natively carry attachments (XRCE today, DDS without a user-data hook) see no change. Backends with native attachment support (zenoh-pico’s z_publisher_put_options::attachment, Cyclone DDS user-data) override to write the bytes onto the wire.

unsafe fn publish_streamed( &self, size_cb: unsafe extern "C" fn(out_total_len: *mut usize, user_ctx: *mut c_void), chunk_cb: unsafe extern "C" fn(out_buf: *mut u8, cap: usize, out_written: *mut usize, user_ctx: *mut c_void), user_ctx: *mut c_void, ) -> Result<(), Self::Error>

where Self::Error: From<TransportError>,

Phase 124.E.1 — streamed publish.

size_cb reports the total payload length once; chunk_cb fills the slot in chunks. Saves the per-publisher staging buffer when the message is large enough to dominate the device’s .bss.

Default body — the staging-buffer fallback (124.E.2). Asks size_cb for the total length, fills a stack-allocated [u8; NROS_MAX_STREAM_CHUNK] via chunk_cb, then forwards to publish_raw. Returns Err(BufferTooSmall) if the total exceeds the stack cap so the caller can drop back to a regular publish_raw with a heap-sized buffer.

Concrete backends opt in by overriding to stream straight into the network buffer (zenoh: write into the zenoh-pico outbound buffer; XRCE: micro-CDR streaming APIs).

Safety

The caller must ensure user_ctx is valid for every invocation of size_cb and chunk_cb during this call, and that both callbacks obey their out-pointer contracts.

size_cb and chunk_cb may be called from the same thread that called publish_streamed. Backends MUST NOT defer the calls past the function return; the caller’s user_ctx pointer is only guaranteed valid for the duration of the call.

fn publish<M: RosMessage>( &self, msg: &M, buf: &mut [u8], ) -> Result<(), Self::Error>

Publish a typed message (serializes automatically)

fn supports_event(&self, _kind: EventKind) -> bool

Phase 108 — true if the backend can generate this event for this publisher. Default returns false; backends override per supported event kind.

Only EventKind::LivelinessLost and EventKind::OfferedDeadlineMissed are publisher-side events; other kinds always return false here.

unsafe fn register_event_callback( &mut self, _kind: EventKind, _deadline_ms: u32, _cb: EventCallback, _user_ctx: *mut c_void, ) -> Result<(), Self::Error>

Phase 108 — register a callback fired when the named status event occurs. deadline_ms applies to EventKind::OfferedDeadlineMissed only; ignored otherwise. Default impl returns the backend’s “unsupported”-shaped error.

Safety

cb and user_ctx must remain valid for the entity’s lifetime. Caller (typically nros-node’s typed wrapper) is responsible for keeping the closure / context arena alive.

fn unsupported_event_error(&self) -> Self::Error

Phase 108 — backend’s error variant for “this event kind is not supported.” Default impl reuses serialization_error() since most backends share an Unsupported variant; backends override if they have a distinct Unsupported mapping.

fn assert_liveliness(&self) -> Result<(), Self::Error>

Phase 109 — assert this publisher’s liveliness manually. Required for publishers configured with QoSLivelinessPolicy::ManualByTopic. No-op for other liveliness kinds. Default impl returns Ok(()) (no-op); backends override when they implement manual liveliness.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors