Function rmw_take_serialized_message_with_info

Function Documentation

rmw_ret_t rmw_take_serialized_message_with_info(const rmw_subscription_t *subscription, rmw_serialized_message_t *serialized_message, bool *taken, rmw_message_info_t *message_info, rmw_subscription_allocation_t *allocation)

Take an incoming ROS message as a byte stream with its metadata.

Same as rmw_take_serialized_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 ROS message a byte stream 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, 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 may have to perform additional memory allocations when dealing with ROS messages that contain unbounded (dynamically-sized) fields i.e. these implementations may have to resize the given byte stream. A subscription allocation, if provided, may or may not be used. Check the implementation documentation to learn about memory allocation guarantees when taking serialized ROS messages with and without subscription allocations.

For ROS messages that only contain bounded (fixed-size) fields, callers can query their size using rmw_get_serialized_message_size() and resize serialized_message using rmw_serialized_message_resize() accordingly to prevent byte stream resizing on take. Nonetheless, byte stream resizing is not guaranteed to be the sole memory operation.

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 serialized ROS messages with metadata:

  • Access to the given byte stream for serialized ROS messages is not synchronized. It is not safe to read or write serialized_message while rmw_take_serialized_message_with_info() uses it.

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

  • Access to given primitive data-type arguments is not synchronized. It is not safe to read or write taken while rmw_take_serialized_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_serialized_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.

  • serialized_message – [out] Byte stream to write to.

  • 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 serialized_message must be a valid serialized message, initialized by rmw_serialized_message_init().

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 serialized_message will remain a valid serialized message, and message_info, valid message metadata. Both 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 serialized_message is NULL, 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_ERROR if an unexpected error occurs.