Function rcl_action_expire_goals

Function Documentation

rcl_ret_t rcl_action_expire_goals(const rcl_action_server_t *action_server, rcl_action_goal_info_t *expired_goals, size_t expired_goals_capacity, size_t *num_expired)

Expires goals associated with an action server.

A goal is ‘expired’ if it has been in a terminal state (has a result) for longer than some duration. The timeout duration is set as part of the action server options.

If a negative timeout value if provided, then goal results never expire (kept forever). If a timeout of zero is set, then goal results are discarded immediately (ie. goal results are discarded whenever this function is called).

Expired goals are removed from the internal array of goal handles. rcl_action_server_goal_exists() will return false for any goals that have expired.

expired_goals, expired_goals_capacity and num_expired are optional arguments. If set to (NULL, 0u, NULL) then they are not used. To use them allocate an array with size equal to the maximum number of goals that you want to expire. Pass the number of goals the array can hold in as expired_goals_capacity. This function will set num_expired to the number of goals that were expired.

Attention

If one or more goals are expired then a previously returned goal handle array from rcl_action_server_get_goal_handles() becomes invalid.

Attribute

Adherence

Allocates Memory

Maybe[1]

Thread-Safe

No

Uses Atomics

No

Lock-Free

Yes

[1] if one or more goals expires, then the internal goal handle array may be resized or deallocated

Parameters:

  • action_server – [in] handle to the action server from which expired goals will be cleared.

  • expired_goals – [inout] the identifiers of goals that expired, or set to NULL if unused

  • expired_goals_capacity – [inout] the allocated size of expired_goals, or 0 if unused

  • num_expired – [out] the number of expired goals, or set to NULL if unused

Returns:

RCL_RET_OK if the response was sent successfully, or

Returns:

RCL_RET_ACTION_SERVER_INVALID if the action server is invalid, or

Returns:

RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or

Returns:

RCL_RET_BAD_ALLOC if allocating memory failed, or

Returns:

RCL_RET_ERROR if an unspecified error occurs.