rcl_action  master
C API providing common functionality for ROS actions.
Classes | Typedefs | Functions
goal_handle.h File Reference
#include "rcl_action/goal_state_machine.h"
#include "rcl_action/types.h"
#include "rcl_action/visibility_control.h"
#include "rcl/allocator.h"
Include dependency graph for goal_handle.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  rcl_action_goal_handle_t
 Goal handle for an action. More...
 

Typedefs

typedef struct rcl_action_goal_handle_t rcl_action_goal_handle_t
 Goal handle for an action. More...
 

Functions

RCL_ACTION_PUBLIC rcl_action_goal_handle_t rcl_action_get_zero_initialized_goal_handle (void)
 Return a rcl_action_goal_handle_t struct with members set to NULL. More...
 
RCL_ACTION_PUBLIC rcl_ret_t rcl_action_goal_handle_init (rcl_action_goal_handle_t *goal_handle, const rcl_action_goal_info_t *goal_info, rcl_allocator_t allocator)
 Initialize a rcl_action_goal_handle_t. More...
 
RCL_ACTION_PUBLIC rcl_ret_t rcl_action_goal_handle_fini (rcl_action_goal_handle_t *goal_handle)
 Finalize a rcl_action_goal_handle_t. More...
 
RCL_ACTION_PUBLIC rcl_ret_t rcl_action_update_goal_state (rcl_action_goal_handle_t *goal_handle, const rcl_action_goal_event_t goal_event)
 Update a goal state with a rcl_action_goal_handle_t and an event. More...
 
RCL_ACTION_PUBLIC rcl_ret_t rcl_action_goal_handle_get_info (const rcl_action_goal_handle_t *goal_handle, rcl_action_goal_info_t *goal_info)
 Get the ID of a goal using a rcl_action_goal_handle_t. More...
 
RCL_ACTION_PUBLIC rcl_ret_t rcl_action_goal_handle_get_status (const rcl_action_goal_handle_t *goal_handle, rcl_action_goal_state_t *status)
 Get the status of a goal. More...
 
RCL_ACTION_PUBLIC bool rcl_action_goal_handle_is_active (const rcl_action_goal_handle_t *goal_handle)
 Check if a goal is active using a rcl_action_goal_handle_t. More...
 
RCL_ACTION_PUBLIC bool rcl_action_goal_handle_is_cancelable (const rcl_action_goal_handle_t *goal_handle)
 Check if a goal can be transitioned to CANCELING in its current state. More...
 
RCL_ACTION_PUBLIC bool rcl_action_goal_handle_is_valid (const rcl_action_goal_handle_t *goal_handle)
 Check if a rcl_action_goal_handle_t is valid. More...
 

Typedef Documentation

◆ rcl_action_goal_handle_t

Goal handle for an action.

Function Documentation

◆ rcl_action_get_zero_initialized_goal_handle()

RCL_ACTION_PUBLIC rcl_action_goal_handle_t rcl_action_get_zero_initialized_goal_handle ( void  )

Return a rcl_action_goal_handle_t struct with members set to NULL.

Should be called to get a null rcl_action_goal_handle_t before passing to rcl_action_goal_handle_init().

◆ rcl_action_goal_handle_init()

RCL_ACTION_PUBLIC rcl_ret_t rcl_action_goal_handle_init ( rcl_action_goal_handle_t goal_handle,
const rcl_action_goal_info_t goal_info,
rcl_allocator_t  allocator 
)

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_handlepreallocated, zero-initialized, goal handle structure to be initialized
[in]goal_infoinformation about the goal to be copied to the goal handle
[in]allocatora 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()

RCL_ACTION_PUBLIC rcl_ret_t rcl_action_goal_handle_fini ( rcl_action_goal_handle_t goal_handle)

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_handlestruct 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()

RCL_ACTION_PUBLIC rcl_ret_t rcl_action_update_goal_state ( rcl_action_goal_handle_t goal_handle,
const rcl_action_goal_event_t  goal_event 
)

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_handlestruct containing goal state to transition
[in]goal_eventthe 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()

RCL_ACTION_PUBLIC rcl_ret_t rcl_action_goal_handle_get_info ( const rcl_action_goal_handle_t goal_handle,
rcl_action_goal_info_t goal_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_handlestruct containing the goal and meta
[out]goal_infoa 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()

RCL_ACTION_PUBLIC rcl_ret_t rcl_action_goal_handle_get_status ( const rcl_action_goal_handle_t goal_handle,
rcl_action_goal_state_t 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_handlestruct containing the goal and metadata
[out]statusa 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()

RCL_ACTION_PUBLIC bool rcl_action_goal_handle_is_active ( const rcl_action_goal_handle_t goal_handle)

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_handlestruct 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()

RCL_ACTION_PUBLIC bool rcl_action_goal_handle_is_cancelable ( const rcl_action_goal_handle_t goal_handle)

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_handlestruct 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()

RCL_ACTION_PUBLIC bool rcl_action_goal_handle_is_valid ( const rcl_action_goal_handle_t goal_handle)

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_handlestruct 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