Go to the source code of this file.
◆ rcl_action_goal_handle_t
Goal handle for an action.
◆ rcl_action_get_zero_initialized_goal_handle()
◆ rcl_action_goal_handle_init()
Initialize a rcl_action_goal_handle_t.
After calling this function on a rcl_action_goal_handle_t, it can be used to update the goals state with rcl_action_update_goal_state(). It can also be used to query the state of the goal with rcl_action_goal_handle_get_message() and rcl_action_goal_handle_is_active(). Goal information can be accessed with rcl_action_goal_handle_get_message() and rcl_action_goal_handle_get_info().
Goal handles are typically initialized and finalized by action servers. I.e. The allocator should be provided by the action server. Goal handles are created with rcl_action_accept_new_goal() and destroyed with rcl_action_clear_expired_goals() or rcl_action_server_fini().
Attribute | Adherence |
Allocates Memory | Yes |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
- Parameters
-
[out] | goal_handle | preallocated, zero-initialized, goal handle structure to be initialized |
[in] | goal_info | information about the goal to be copied to the goal handle |
[in] | allocator | a valid allocator used to initialized the goal handle |
- Returns
RCL_RET_OK
if goal_handle was initialized successfully, or
-
RCL_RET_INVALID_ARGUMENT
if the allocator is invalid, or
-
RCL_RET_ACTION_GOAL_HANDLE_INVALID
if the goal handle is invalid, or
-
RCL_RET_ALREADY_INIT
if the goal handle has already been initialized, or
-
RCL_RET_BAD_ALLOC
if allocating memory failed
◆ rcl_action_goal_handle_fini()
Finalize a rcl_action_goal_handle_t.
After calling, rcl_action_goal_handle_t will no longer be valid and rcl_action_server_t will no longer track the goal associated with the goal handle.
After calling, calls to rcl_action_publish_feedback(), rcl_action_publish_status(), rcl_action_update_goal_state(), rcl_action_goal_handle_get_status(), rcl_action_goal_handle_is_active(), rcl_action_goal_handle_get_message(), and rcl_action_goal_handle_get_info() will fail when using this goal handle.
However, the given action server is still valid.
Attribute | Adherence |
Allocates Memory | Yes |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
- Parameters
-
[in,out] | goal_handle | struct to be deinitialized |
- Returns
RCL_RET_OK
if the goal handle was deinitialized successfully, or
-
RCL_RET_ACTION_GOAL_HANDLE_INVALID
if the goal handle is invalid, or
◆ rcl_action_update_goal_state()
Update a goal state with a rcl_action_goal_handle_t and an event.
This is a non-blocking call.
Attribute | Adherence |
Allocates Memory | No |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
- Parameters
-
[in,out] | goal_handle | struct containing goal state to transition |
[in] | goal_event | the event used to transition the goal state |
- Returns
RCL_RET_OK
if the goal state was updated successfully, or
-
RCL_RET_ACTION_GOAL_EVENT_INVALID
if the goal event is invalid, or
-
RCL_RET_ACTION_GOAL_HANDLE_INVALID
if the goal handle is invalid, or
◆ rcl_action_goal_handle_get_info()
Get the ID of a goal using a rcl_action_goal_handle_t.
This is a non-blocking call.
Attribute | Adherence |
Allocates Memory | No |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
- Parameters
-
[in] | goal_handle | struct containing the goal and meta |
[out] | goal_info | a preallocated struct where the goal info is copied |
- Returns
RCL_RET_OK
if the goal ID was accessed successfully, or
-
RCL_RET_ACTION_GOAL_HANDLE_INVALID
if the goal handle is invalid, or
-
RCL_RET_INVALID_ARGUMENT
if the goal_info argument is invalid
◆ rcl_action_goal_handle_get_status()
Get the status of a goal.
This is a non-blocking call.
Attribute | Adherence |
Allocates Memory | No |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
- Parameters
-
[in] | goal_handle | struct containing the goal and metadata |
[out] | status | a preallocated struct where the goal status is copied |
- Returns
RCL_RET_OK
if the goal ID was accessed successfully, or
-
RCL_RET_ACTION_GOAL_HANDLE_INVALID
if the goal handle is invalid, or
-
RCL_RET_INVALID_ARGUMENT
if the status argument is invalid
◆ rcl_action_goal_handle_is_active()
Check if a goal is active using a rcl_action_goal_handle_t.
This is a non-blocking call.
Attribute | Adherence |
Allocates Memory | No |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
- Parameters
-
[in] | goal_handle | struct containing the goal and metadata |
- Returns
true
if the goal is in one of the following states: ACCEPTED, EXECUTING, or CANCELING, or
-
false
if the goal handle pointer is invalid, or
-
false
otherwise
◆ rcl_action_goal_handle_is_cancelable()
Check if a goal can be transitioned to CANCELING in its current state.
This is a non-blocking call.
Attribute | Adherence |
Allocates Memory | No |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
- Parameters
-
[in] | goal_handle | struct containing the goal and metadata |
- Returns
true
if the goal can be transitioned to CANCELING from its current state, or
-
false
if the goal handle pointer is invalid, or
-
false
otherwise
◆ rcl_action_goal_handle_is_valid()
Check if a rcl_action_goal_handle_t is valid.
This is a non-blocking call.
A goal handle is invalid if:
Attribute | Adherence |
Allocates Memory | No |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
- Parameters
-
[in] | goal_handle | struct to evaluate as valid or not |
- Returns
true
if the goal handle is valid, or
-
false
if the goal handle pointer is null, or
-
false
otherwise