This document summarizes how Action Scheduler represents actions in code and how those actions move through states during their lifecycle. It is based on the Action classes in classes/actions/ and the status constants in classes/abstracts/ActionScheduler_Store.php.

Action States (Status Constants)

Action status is stored by the active data store and represented by constants on ActionScheduler_Store:

• ActionScheduler_Store::STATUS_PENDING (pending)
• ActionScheduler_Store::STATUS_RUNNING (in-progress)
• ActionScheduler_Store::STATUS_COMPLETE (complete)
• ActionScheduler_Store::STATUS_FAILED (failed)
• ActionScheduler_Store::STATUS_CANCELED (canceled)

Class Mapping by Status

When a stored action is loaded, the factory selects which Action class to instantiate based on the stored status (see ActionScheduler_ActionFactory::get_stored_action()):

• pending → ActionScheduler_Action
• canceled → ActionScheduler_CanceledAction
• any other status (complete/failed/running) → ActionScheduler_FinishedAction

This mapping is filterable via action_scheduler_stored_action_class and action_scheduler_stored_action_instance, but the default behavior above is what the core data stores depend on.

Lifecycle Summary

1) Creation and Storage

Actions are created with a hook, args, schedule, group, and priority (see ActionScheduler_Action).

• If no schedule is provided, the constructor uses a ActionScheduler_NullSchedule, which represents “run as soon as possible.”
• When stored, data stores typically use ActionScheduler_Action::is_finished() to decide the initial status. For example, the DB store records finished actions as complete and others as pending.

2) Pending → Running

When an action is picked up for execution by the queue runner:

1. The action is fetched from the store.
2. The store records execution start (e.g., log_execution()), which updates status to in-progress and increments attempts.

3) Running → Complete / Failed

The queue runner executes the action’s hook (ActionScheduler_Action::execute()), then transitions the action to a terminal state:

• Success → complete via mark_complete().
• Failure (exception/error) → failed via mark_failure().

4) Canceling

Cancellation prevents a pending action from running. Data stores implement cancel_action() and set the status to canceled. Canceled actions are represented by ActionScheduler_CanceledAction and behave like finished actions (no execution and is_finished() returns true).

5) Null Actions (Missing / Invalid Records)

If an action cannot be fetched (e.g., missing or invalid DB record), stores return an ActionScheduler_NullAction. This object intentionally performs no execution and uses a ActionScheduler_NullSchedule.

Claims and Locking

To avoid multiple processes running the same actions, the store can claim a batch using ActionScheduler_Store::stake_claim(), which returns an ActionScheduler_ActionClaim containing:

• A claim ID (unique identifier for a batch)
• A list of action IDs claimed

Claimed actions are then processed by the queue runner. Once processing is done, the claim is released (release_claim()), and actions can be re-claimed if they remain pending.

See actions/claim.md for details on the claim object and how the DB store implements the locking behavior.