Subscription API that explicitly takes messages instead of using a callback

[mxgrey]

Motivated by the use case of a community member, we can consider providing an API to take messages directly from a subscription instead of passing each message into a callback one at a time.

This may be useful for cases where a user would rather poll for new messages at a predefined rate, with no immediate action being needed when a message arrives.

I'd propose these two APIs for the sake of convenience and ergonomics without loss of generality (I'm very open to changing the names of structs and functions:

impl<Message> SubscriptionTaker<Message> {
    pub fn take_with(&self, &mut msg: Message) -> Result<(), _> { ... }

    pub fn take(&self) -> Result<Message, _> {
        let mut msg = Message::default();
        let r = self.take_with(&mut msg);
        r.map(|_| msg)
    }
}

impl<Message> LatestSubscriptionMessage<Message> {
    pub fn get(&mut self) -> &mut Message { ... }
}

The LatestMessage struct would be a light wrapper around SubscriptionTaker which is specialized for the case where you only need the most recent message. It lets the user define an initial message value and then each time you call .get() it will attempt to update the message. Whether or not there was an update, it will provide a borrow of the most recent message value. The same message instance will be recycled as new messages come in.

The more general SubscriptionTaker::take_with will allow users to specify a message instance to pass the new message data into, if any new data is available. If there is no new message data, this will return an Err.

Maintainers can feel free to assign this ticket to me.

[harrisonmg]

It would be nice to add into support for MessageInfo and loaned messages.

I modified the names a bit just to illustrate my idea (specifically I renamed take_with -> take_into to avoid overlap with take_with_info).

pub fn take_loaned(&self) -> Result<ReadOnlyLoanedMessage<Message>>, _> { ... }

pub fn take_with_info(&self) -> Result<(Message, MessageInfo), _> { ... }

pub fn take_into_with_info(&self, msg: &mut Message) -> Result<MessageInfo, _> { ... }

pub fn take_loaned_with_info(&self) -> Result<(ReadOnlyLoanedMessage<Message>, MessageInfo), _> { ... }

Would SubscriptionTaker be a wrapper around a Subscription? I'm curious if that is preferential to adding these methods to the Subscription struct. I suppose it might be better to prevent the usage of these methods when a Subscription has a callback.

Also, the impl of take in rclcpp notes that the message and message info out params might be updated despite returning false because an intra-process message was received and subsequently dropped. Could this cause an issue with LatestSubscriptionMessage if there is no way to expose that event in its API? I'm imagining an error mode where stale inter-process message data overwrites fresher intra-process data.