pub struct ActionServerHandle<A: RosAction> { /* private fields */ }Expand description
Handle to an action server registered in the executor’s arena.
Returned by Executor::register_action_server(). Provides methods
to interact with the server (publish feedback, complete goals) while the
executor automatically handles goal acceptance, cancel requests, and
result serving during spin_once().
Implementations§
Source§impl<A: RosAction> ActionServerHandle<A>
impl<A: RosAction> ActionServerHandle<A>
Sourcepub fn handle_id(&self) -> HandleId
pub fn handle_id(&self) -> HandleId
Get the HandleId for this action server.
Used with Trigger::One or HandleSet for trigger configuration.
Sourcepub fn publish_feedback(
&self,
executor: &mut Executor<'_>,
goal_id: &GoalId,
feedback: &A::Feedback,
) -> Result<(), NodeError>
pub fn publish_feedback( &self, executor: &mut Executor<'_>, goal_id: &GoalId, feedback: &A::Feedback, ) -> Result<(), NodeError>
Publish feedback for an active goal.
Serialises the feedback message and sends it to all clients monitoring this goal. Returns an error if the handle slot has been removed from the executor.
Sourcepub fn succeed(
&self,
executor: &mut Executor<'_>,
goal_id: &GoalId,
result: A::Result,
) -> Result<(), NodeError>
pub fn succeed( &self, executor: &mut Executor<'_>, goal_id: &GoalId, result: A::Result, ) -> Result<(), NodeError>
Complete a goal with a terminal status and result payload.
The goal is moved from the active set to the completed-results
slab. Clients waiting on a result will receive the response.
status should be one of Succeeded, Aborted, or Canceled.
§Errors
NodeError::BufferTooSmall when the handle slot has been removed from
the executor, or when the serialized result exceeds the server’s
RESULT_BUF and so cannot be retained for a later get_result (issue
0796 — this used to return () and swallow both).
Terminate goal_id as SUCCEEDED — phase-379 W5.
The three terminal verbs (succeed / abort / canceled) name the
ACTION SPEC’s terminal states, which is also what rclcpp_action’s
ServerGoalHandle spells them: succeed(result), abort(result),
canceled(result) — and, since phase-417 W4.b, what C
(rclc_action_canceled) and C++ (ActionServer<A>::canceled) spell
them too. They take the goal ID rather than hanging off a
handle because a goal here lives in a fixed-capacity arena and is named
by its UUID — see the divergence row for why neither client library’s
ownership model is available without an allocator.
complete_goal remains the general form for a status computed at
runtime.
Sourcepub fn abort(
&self,
executor: &mut Executor<'_>,
goal_id: &GoalId,
result: A::Result,
) -> Result<(), NodeError>
pub fn abort( &self, executor: &mut Executor<'_>, goal_id: &GoalId, result: A::Result, ) -> Result<(), NodeError>
Terminate goal_id as ABORTED. See Self::succeed.
Sourcepub fn canceled(
&self,
executor: &mut Executor<'_>,
goal_id: &GoalId,
result: A::Result,
) -> Result<(), NodeError>
pub fn canceled( &self, executor: &mut Executor<'_>, goal_id: &GoalId, result: A::Result, ) -> Result<(), NodeError>
Terminate goal_id as CANCELED. See Self::succeed.
phase-417 W4.b — this was cancel, and the argument for that spelling
lived on the cancel alias phase-482 W6 retired. It loses to the
drop-in claim: C spells it
rclc_action_canceled, rclcpp_action spells it
ServerGoalHandle::canceled, and Rust was the only one of the three
disagreeing — over a naming preference with no platform reason behind
it (RFC-0089: a rename is cheap, a surface our own languages disagree
about is not).
pub fn complete_goal( &self, executor: &mut Executor<'_>, goal_id: &GoalId, status: GoalStatus, result: A::Result, ) -> Result<(), NodeError>
Sourcepub fn set_goal_status(
&self,
executor: &mut Executor<'_>,
goal_id: &GoalId,
status: GoalStatus,
)
pub fn set_goal_status( &self, executor: &mut Executor<'_>, goal_id: &GoalId, status: GoalStatus, )
Update a goal’s status without completing it.
Use this to transition a goal to Executing or Canceling
while it is still active. To finish a goal, use complete_goal.
Sourcepub fn active_goal_count(&self, executor: &Executor<'_>) -> usize
pub fn active_goal_count(&self, executor: &Executor<'_>) -> usize
Get the number of currently active goals.
Returns 0 if the action server handle has been removed from the executor.
Sourcepub fn goal_exists(&self, executor: &Executor<'_>, goal_id: &GoalId) -> bool
pub fn goal_exists(&self, executor: &Executor<'_>, goal_id: &GoalId) -> bool
Is goal_id a goal this server still knows about? — phase-417 W4.b.
rcl’s rcl_action_server_goal_exists, and the Rust half of the ledger
row c:action_server_goal_exists. TRUE while the goal is active AND
while its completed result is still retained, which is a strictly wider
window than goal_status reports — see
ActionServerCore::goal_exists.
Returns false if the handle slot has been removed from the executor,
which is the same answer a caller wants there: nothing on this server
knows the goal any more.
Sourcepub fn expire_goals(&self, executor: &mut Executor<'_>) -> usize
pub fn expire_goals(&self, executor: &mut Executor<'_>) -> usize
Eagerly reclaim every completed result whose get_result reply has
already been sent — phase-417 W4.b, ledger row c:action_expire_goals.
Returns the number of entries reclaimed. rcl’s rcl_action_expire_goals
is the same capability under a CLOCK: it reclaims goals whose
result_timeout has elapsed and reports which. Ours has no clock — the
no_std core takes no time source (RFC-0036) — so the trigger is the
caller, and reclamation is otherwise on demand inside complete_goal.
Calling this is OPTIONAL; a server that never does still runs forever.
Sourcepub fn for_each_active_goal(
&self,
executor: &Executor<'_>,
f: impl FnMut(&ActiveGoal<A>),
)
pub fn for_each_active_goal( &self, executor: &Executor<'_>, f: impl FnMut(&ActiveGoal<A>), )
Iterate over all currently active goals.
Calls f for each goal that has been accepted but not yet
completed. Useful for monitoring progress or canceling stale goals.