Function rcl_action_take_result_response

Function Documentation

rcl_ret_t rcl_action_take_result_response(const rcl_action_client_t *action_client, rmw_request_id_t *response_header, void *ros_result)

Take a ROS result message for a completed goal associated with a rcl_action_client_t.

Todo:

TODO(jacobperron) blocking of take?

Todo:

TODO(jacobperron) pre-, during-, and post-conditions for message ownership?

Todo:

TODO(jacobperron) is this thread-safe?

The caller is responsible for ensuring that the type of ros_result_response and the type associate with the client (via the type support) match. Passing a different type produces undefined behavior and cannot be checked by this function and therefore no deliberate error will occur.

The caller must provide a pointer to an allocated message for the ros_result_response. If the take is successful, this function will populate the fields of ros_result_response. The ROS message given by the ros_result_response void pointer is always owned by the calling code, but should remain constant during execution of this function. i.e. Before and after calling rcl_action_take_result_response() the ros_result_response message can change, but it cannot be changed during the call to rcl_action_take_result_response().

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

Attribute

Adherence

Allocates Memory

Maybe [1]

Thread-Safe

No

Uses Atomics

No

Lock-Free

Yes

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

Parameters:

  • action_client – [in] handle to the client that will take the result response

  • response_header – [out] pointer to the result response header

  • ros_result – [out] preallocated, zero-initialized, struct where the ROS result message is copied.

Returns:

RCL_RET_OK if the response was taken successfully, or

Returns:

RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or

Returns:

RCL_RET_ACTION_CLIENT_INVALID if the action client is invalid, or

Returns:

RCL_RET_BAD_ALLOC if allocating memory failed, or

Returns:

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

Returns:

RCL_RET_ERROR if an unspecified error occurs.