Function rmw_take_serialized_message

Function Documentation

rmw_ret_t rmw_take_serialized_message(const rmw_subscription_t *subscription, rmw_serialized_message_t *serialized_message, bool *taken, rmw_subscription_allocation_t *allocation)

Take an incoming ROS message as a byte stream.

Take a ROS message already received by the given subscription, removing it from internal queues. This function will succeed even if no ROS message was received, but taken will be false. Unlike rmw_take(), the ROS message is taken in its serialized form, as a byte stream. If needed, this byte stream can then be deserialized into a ROS message with rmw_deserialize().

Attribute

Adherence

Allocates Memory

Maybe

Thread-Safe

Yes

Uses Atomics

Maybe [1]

Lock-Free

Maybe [1]

Remark

The same ROS message, serialized or not, cannot be taken twice. Callers do not have to deal with duplicates.

[1] implementation defined, check implementation documentation.

Runtime behavior

To take a ROS message a byte stream 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:

  • 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() 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() 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() 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.

  • 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:

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. 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 serialized_message is NULL, or

Returns:

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