Function rmw_take

Function Documentation

rmw_ret_t rmw_take(const rmw_subscription_t *subscription, void *ros_message, bool *taken, rmw_subscription_allocation_t *allocation)

Take an incoming ROS message.

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.

Attribute

Adherence

Allocates Memory

Maybe

Thread-Safe

Yes

Uses Atomics

Maybe [1]

Lock-Free

Maybe [1]

Remark

The same ROS message 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 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 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 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 regular ROS messages:

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

  • Access to given primitive data-type arguments is not synchronized. It is not safe to read or write taken while rmw_take() 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() uses it. Check the implementation documentation to learn about subscription allocations’ thread-safety.

Parameters:

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

  • ros_message – [out] Type erased ROS message to write to.

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

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

Pre:

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

Pre:

Given ros_message must be a valid message, whose type matches the message type support registered with the subscription on creation.

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 the subscription on creation.

Post:

Given ros_message will remain a valid 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 ros_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.