Struct Subscription

pub struct Subscription<T>
where
    T: Message,
{
    pub callback: Mutex<AnySubscriptionCallback<T>>,
    /* private fields */
}

Struct for receiving messages of type T.

There can be multiple subscriptions for the same topic, in different nodes or the same node.

Receiving messages requires the node’s executor to spin.

When a subscription is created, it may take some time to get “matched” with a corresponding publisher.

The only available way to instantiate subscriptions is via Node::create_subscription(), this is to ensure that Nodes can track all the subscriptions that have been created.

Fields

callback: Mutex<AnySubscriptionCallback<T>>

The callback function that runs when a message was received.

Implementations

impl<T> Subscription<T>

where T: Message,

pub fn topic_name(&self) -> String

Returns the topic name of the subscription.

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

pub fn take(&self) -> Result<(T, MessageInfo), RclrsError>

Fetches a new message.

When there is no new message, this will return a SubscriptionTakeFailed.

pub fn take_boxed(&self) -> Result<(Box<T>, MessageInfo), RclrsError>

This is a version of take() that returns a boxed message.

This can be more efficient for messages containing large arrays.

pub fn take_loaned( &self, ) -> Result<(ReadOnlyLoanedMessage<'_, T>, MessageInfo), RclrsError>

Obtains a read-only handle to a message owned by the middleware.

When there is no new message, this will return a SubscriptionTakeFailed.

This is the counterpart to Publisher::borrow_loaned_message(). See its documentation for more information.

Trait Implementations

impl<T> SubscriptionBase for Subscription<T>

where T: Message,

fn handle(&self) -> &SubscriptionHandle

Internal function to get a reference to the rcl handle.

fn execute(&self) -> Result<(), RclrsError>

Tries to take a new message and run the callback with it.