Function rcl_take_loaned_message

Function Documentation

rcl_ret_t rcl_take_loaned_message(const rcl_subscription_t *subscription, void **loaned_message, rmw_message_info_t *message_info, rmw_subscription_allocation_t *allocation)

Take a loaned message from a topic using a rcl subscription.

Depending on the middleware, incoming messages can be loaned to the user’s callback without further copying. The implicit contract here is that the middleware owns the memory allocated for this message. The user must not destroy the message, but rather has to return it with a call to

Attribute

Adherence

Allocates Memory

No

Thread-Safe

No

Uses Atomics

No

Lock-Free

Yes

See also

rcl_return_loaned_message to the middleware.

Parameters:

  • subscription – [in] the handle to the subscription from which to take

  • loaned_message – [inout] a pointer to the loaned messages.

  • message_info – [out] rmw struct which contains meta-data for the message.

  • allocation – [in] structure pointer used for memory preallocation (may be NULL)

Returns:

RCL_RET_OK if the loaned message sequence was taken, or

Returns:

RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or

Returns:

RCL_RET_SUBSCRIPTION_INVALID if the subscription is invalid, or

Returns:

RCL_RET_BAD_ALLOC if allocating memory failed, or

Returns:

RCL_RET_SUBSCRIPTION_TAKE_FAILED if take failed but no error occurred in the middleware, or

Returns:

RCL_RET_UNSUPPORTED if the middleware does not support that feature, or

Returns:

RCL_RET_ERROR if an unspecified error occurs.