Function rcl_take_sequence

Function Documentation

rcl_ret_t rcl_take_sequence(const rcl_subscription_t *subscription, size_t count, rmw_message_sequence_t *message_sequence, rmw_message_info_sequence_t *message_info_sequence, rmw_subscription_allocation_t *allocation)

Take a sequence of messages from a topic using a rcl subscription.

In contrast to rcl_take(), this function can take multiple messages at the same time. It is the job of the caller to ensure that the type of the message_sequence argument and the type associated with the subscription, via the type support, match.

The message_sequence pointer should point to an already allocated sequence of ROS messages of the correct type, into which the taken ROS messages will be copied if messages are available. The message_sequence size member will be set to the number of messages correctly taken.

The rmw_message_info_sequence struct contains meta information about the corresponding message instance index. The message_info_sequence argument should be an already allocated rmw_message_info_sequence_t structure.

Attribute

Adherence

Allocates Memory

Maybe [1]

Thread-Safe

No

Uses Atomics

No

Lock-Free

Yes

[1] only if storage in the serialized_message is insufficient

Parameters:

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

  • count – [in] number of messages to attempt to take.

  • message_sequence – [inout] pointer to a (pre-allocated) message sequence.

  • message_info_sequence – [inout] pointer to a (pre-allocated) message info sequence.

  • allocation – [in] structure pointer used for memory preallocation (may be NULL)

Returns:

RCL_RET_OK if one or more messages 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.