Function rmw_take_loaned_message_with_info

• Defined in File rmw.h

Function Documentation

rmw_ret_t rmw_take_loaned_message_with_info(const rmw_subscription_t *subscription, void **loaned_message, bool *taken, rmw_message_info_t *message_info, rmw_subscription_allocation_t *allocation)

Take a loaned message and with its additional message information.

Same as rmw_take_loaned_message(), except it also takes ROS message metadata.

Attribute	Adherence
Allocates Memory	Maybe
Thread-Safe	Yes
Uses Atomics	Maybe [1]
Lock-Free	Maybe [1]

[1] implementation defined, check implementation documentation.

Runtime behavior

To take a loaned ROS message with its metadata is a synchronous operation. It is also non-blocking, to the extent it will not wait for new ROS messages to arrive nor for internal memory loaning pools, if any, to be replenished, 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).

Memory allocation

It is implementation defined whether memory will be allocated on take or not. For instance, implementations that deserialize ROS messages received over the wire may need to perform additional memory allocations when dealing with unbounded (dynamically-sized) fields. A subscription allocation, if provided, may or may not be used. Check the implementation documentation to learn about memory allocation guarantees when taking loaned ROS messages with and without subscription allocations.

Thread-safety

Subscriptions are thread-safe objects, and so are all operations on them except for finalization. Therefore, it is safe to take from the same subscription concurrently. However, when taking loaned ROS messages with metadata:

• Access to given primitive data-type arguments is not synchronized. It is not safe to read or write taken nor loaned_message while rmw_take_loaned_message_with_info() uses them.

• Access to the given ROS message metadata is not synchronized. It is not safe to read or write message_info while rmw_take_loaned_message_with_info() uses it.

• Access to the given subscription allocation is not synchronized, unless specifically stated otherwise by the implementation. Thus, it is generally not safe to read or write allocation while rmw_take_loaned_message_with_info() uses it. Check the implementation documentation to learn about subscription allocations’ thread-safety.

Parameters:

• subscription – [in] Subscription to take ROS message from.

• loaned_message – [inout] Pointer to type erased ROS message taken and loaned by the middleware.

• taken – [out] Boolean flag indicating if a ROS message was taken or not.

• message_info – [out] Taken ROS message metadata.

• allocation – [in] Pre-allocated memory to use. May be NULL.

Pre:

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

Pre:

If not NULL, given allocation must be a valid subscription allocation initialized with rmw_subscription_allocation_init() with a message type support that matches the one registered with subscription on creation.

Post:

Given loaned_message will remain unchanged, or point to a valid message if this function was successful and taken is true.

Post:

Given message_info will remain valid message metadata. It will be left unchanged if this function fails early due to a logical error, such as an invalid argument, or in an unknown yet valid state if it fails due to a runtime error. It will also be left unchanged if this function succeeds but taken is false.

Returns:

RMW_RET_OK if successful, or

Returns:

RMW_RET_BAD_ALLOC if memory allocation fails, 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_INVALID_ARGUMENT if *loaned_message is not NULL to prevent leaks, or

Returns:

RMW_RET_INVALID_ARGUMENT if taken is NULL, or

Returns:

RMW_RET_INVALID_ARGUMENT if message_info 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.