Function rcl_take_request_with_info

Function Documentation

rcl_ret_t rcl_take_request_with_info(const rcl_service_t *service, rmw_service_info_t *request_header, void *ros_request)

Take a pending ROS request using a rcl service.

It is the job of the caller to ensure that the type of the ros_request argument and the type associate with the service, 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(jacquelinekay) blocking of take? TODO(jacquelinekay) pre-, during-, and post-conditions for message ownership? TODO(jacquelinekay) is rcl_take_request thread-safe? TODO(jacquelinekay) Should there be an rcl_request_id_t?

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

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

request_header is a pointer to pre-allocated a rmw struct containing meta-information about the request (e.g. the sequence number).

Attribute

Adherence

Allocates Memory

Maybe [1]

Thread-Safe

No

Uses Atomics

No

Lock-Free

Yes

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

Parameters:

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

  • request_header – [inout] ptr to the struct holding metadata about the request

  • ros_request – [inout] type-erased ptr to an allocated ROS request message

Returns:

RCL_RET_OK if the request was taken, or

Returns:

RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or

Returns:

RCL_RET_SERVICE_INVALID if the service is invalid, or

Returns:

RCL_RET_BAD_ALLOC if allocating memory failed, or

Returns:

RCL_RET_SERVICE_TAKE_FAILED if take failed but no error occurred in the middleware, or

Returns:

RCL_RET_ERROR if an unspecified error occurs.