[Documentation] [TitleIndex] [WordIndex




This page is not targeted for people that are 'just getting started' with using actionlib. Instead, it describes the underlying mechanisms through which action clients & servers interact with one another.

If you only want to use the SimpleActionClient or SimpleActionServer, it is not necessary to understand the concepts on this page. However, understanding these concepts provides insight that is useful for debugging client/server interactions or for implementing alternate client/server policies, if the simple client & server aren't descriptive enough.

High Level Client/Server Interaction

Server Description

Server State Machine

Note that this state machine tracks an individual goal, and not the ActionServer itself. Thus, there is a state machine for each goal in the system.

Server Transitions

Server States

Concurrency Issues

Client Description

Client State Machine

Client Transitions

Action Interface & Transport Layer

Data Association and Goal IDs

The Messages

goal topic: Sending Goals

cancel topic: Cancelling Goals

status topic: Server goal state updates

feedback topic: Asynchronous goal information

result topic: Goal information upon completion


Simple Action Client

Client State Ambiguities

Multiple Goal Policy

Threading Model (C++)

Simple Action Server

Many action servers follow a similar pattern where only one goal can be active at a time and each new goal preempts the previous one. The simple action server is a wrapper around the action server designed to enforce this simple policy for processing goals.


Upon reception of a new goal from an action client, the simple action server moves that goal into its pending slot. If a goal already occupies the pending slot, the simple action server sets that goal to canceled and replaces it with the goal that came in over the wire.


Once a new goal is received by the simple action server and is moved into the pending slot, the user of the simple action server is notified that a new goal is available. This notification occurs in one of two ways as described in the Notificaton of Goals section below. Upon receiving notification, the user can accept the goal which causes the goal in the pending slot to move to the current goal slot, and allows the user to modify the state machine associated with the newly accepted goal.

Notification of Goals

There are two ways a user can receive notification that a new goal has been received by the simple action server:

Threading Model (C++)

Upon construction of the simple action server, the user decides whether or not to spin up an extra thread to allow for taking long running actions in a goal callback.

2024-07-13 12:37