Function rmw_return_loaned_message_from_subscription

Function Documentation

rmw_ret_t rmw_return_loaned_message_from_subscription(const rmw_subscription_t *subscription, void *loaned_message)

Return a loaned ROS message previously taken from a subscription.

Tells the middleware that previously loaned ROS message is no longer needed by the caller. If this function fails early due to a logical error, such as an invalid argument, the loaned ROS message will be left unchanged. Otherwise, ownership of the ROS message will be given back to the middleware. It is up to the middleware what will be made of the returned ROS message. It is undefined behavior to use a loaned ROS message after returning it.

Attribute

Adherence

Allocates Memory

No

Thread-Safe

Yes

Uses Atomics

Maybe [1]

Lock-Free

Maybe [1]

[1] implementation defined, check implementation documentation.

Runtime behavior

To return a loaned ROS message is a synchronous operation. It is also non-blocking, but it is not guaranteed to be lock-free. Generally speaking, implementations may synchronize access to internal resources using locks but are not allowed to wait for events with no guaranteed time bound (barring the effects of starvation due to OS scheduling).

Thread-safety

Subscriptions are thread-safe objects, and so are all operations on them except for finalization. Therefore, it is safe to return loaned ROS messages to the same subscription concurrently. However, since ownership of the loaned ROS message is given back to middleware and this transfer is not synchronized, it is not safe to return the same loaned ROS message concurrently.

Parameters:

  • subscription – [in] Subscription the ROS message was taken and loaned from.

  • loaned_message – [in] Loaned type erased ROS message to be returned to the middleware.

Pre:

Given subscription must be a valid subscription, as returned by rmw_create_subscription().

Pre:

Given loaned_message must be a loaned ROS message, previously taken from subscription using rmw_take_loaned_message() or rmw_take_loaned_message_with_info().

Returns:

RMW_RET_OK if successful, or

Returns:

RMW_RET_INVALID_ARGUMENT if subscription is NULL, or

Returns:

RMW_RET_INVALID_ARGUMENT if loaned_message is NULL, or

Returns:

RMW_RET_INCORRECT_RMW_IMPLEMENTATION if the subscription implementation identifier does not match this implementation, or

Returns:

RMW_RET_UNSUPPORTED if the implementation does not support loaned ROS messages, or

Returns:

RMW_RET_ERROR if an unexpected error occurs.