Function rcl_take

Function Documentation

rcl_ret_t rcl_take(const rcl_subscription_t *subscription, void *ros_message, rmw_message_info_t *message_info, rmw_subscription_allocation_t *allocation)

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

It is the job of the caller to ensure that the type of the ros_message argument and the type associated with the subscription, via the type support, match. Passing a different type to rcl_take produces undefined behavior and cannot be checked by this function and therefore no deliberate error will occur.

TODO(wjwwood) blocking of take? TODO(wjwwood) pre-, during-, and post-conditions for message ownership? TODO(wjwwood) is rcl_take thread-safe? TODO(wjwwood) Should there be an rcl_message_info_t?

The ros_message pointer should point to an already allocated ROS message struct of the correct type, into which the taken ROS message will be copied if one is available. If taken is false after calling, then the ROS message will be unmodified.

The taken boolean may be false even if a wait set reports that the subscription was ready to be taken from in some cases, e.g. when the state of the subscription changes it may cause the wait set to wake up but subsequent takes to fail to take anything.

If allocation is required when taking the message, e.g. if space needs to be allocated for a dynamically sized array in the target message, then the allocator given in the subscription options is used.

The rmw_message_info struct contains meta information about this particular message instance, like what the GUID of the publisher which published it originally or whether or not the message received from within the same process. The message_info argument should be an already allocated rmw_message_info_t structure. Passing NULL for message_info will result in the argument being ignored.

Attribute

Adherence

Allocates Memory

Maybe [1]

Thread-Safe

No

Uses Atomics

No

Lock-Free

Yes

[1] only if required when filling the message, avoided for fixed sizes

Parameters:

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

  • ros_message – [inout] type-erased ptr to a allocated ROS message

  • 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 message 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_ERROR if an unspecified error occurs.