Struct Publisher

pub struct Publisher<T>
where
    T: Message,
{ /* private fields */ }

Struct for sending messages of type T.

Multiple publishers can be created for the same topic, in different nodes or the same node.

The underlying RMW will decide on the concrete delivery mechanism (network stack, shared memory, or intraprocess).

Sending messages does not require calling spin on the publisher’s node.

Implementations

impl<T> Publisher<T>

where T: Message,

pub fn new( rcl_node_mtx: Arc<Mutex<rcl_node_t>>, topic: &str, qos: QoSProfile, ) -> Result<Self, RclrsError>

where T: Message,

Creates a new Publisher.

Node and namespace changes are always applied before topic remapping.

pub fn topic_name(&self) -> String

Returns the topic name of the publisher.

This returns the topic name after remapping, so it is not necessarily the topic name which was used when creating the publisher.

pub fn publish<'a, M: MessageCow<'a, T>>( &self, message: M, ) -> Result<(), RclrsError>

Publishes a message.

The MessageCow trait is implemented by any Message as well as any reference to a Message.

The reason for allowing owned messages is that publishing owned messages can be more efficient in the case of idiomatic messages¹.

Hence, when a message will not be needed anymore after publishing, pass it by value. When a message will be needed again after publishing, pass it by reference, instead of cloning and passing by value.

Calling publish() is a potentially blocking call, see this issue for details.

---

1. See the Message trait for an explanation of “idiomatic”. ↩

impl<T> Publisher<T>

where T: RmwMessage,

pub fn borrow_loaned_message(&self) -> Result<LoanedMessage<'_, T>, RclrsError>

Obtains a writable handle to a message owned by the middleware.

This lets the middleware control how and where to allocate memory for the message. The purpose of this is typically to achieve zero-copy communication between publishers and subscriptions on the same machine: the message is placed directly in a shared memory region, and a reference to the same memory is returned by Subscription::take_loaned_message(). No copying or serialization/deserialization takes place, which is much more efficient, especially as the message size grows.

Conditions for zero-copy communication

1. A middleware with support for shared memory is used, e.g. CycloneDDS with iceoryx
2. Shared memory transport is enabled in the middleware configuration
3. Publishers and subscriptions are on the same machine
4. The message is a “plain old data” type containing no variable-size members, whether bounded or unbounded
5. The publisher’s QOS settings are compatible with zero-copy, e.g. the default QOS
6. Publisher::borrow_loaned_message() is used and the subscription uses a callback taking a ReadOnlyLoanedMessage

This function is only implemented for RmwMessages since the “idiomatic” message type does not have a typesupport library.

Trait Implementations

impl<T> Drop for Publisher<T>

where T: Message,

fn drop(&mut self)

Executes the destructor for this type.

impl<T> Send for Publisher<T>

where T: Message,

impl<T> Sync for Publisher<T>

where T: Message,