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 Subscriber::try_recv_raw_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", so this trait is not object safe.

Implementors