Represents a claim on a set of action IDs. Claims are used by the queue runner and data stores to lock a batch of pending actions for processing, preventing other processes from running them simultaneously.

Source: classes/ActionScheduler_ActionClaim.php

Properties

private string $id = ''

The claim identifier. In the DB store this corresponds to the claim_id primary key in the actionscheduler_claims table.

private int[] $action_ids = array()

List of action IDs included in the claim.

Constructor

__construct( string $id, array $action_ids )

Creates a claim instance.

• $id — Claim ID.
• $action_ids — Array of action IDs included in the claim.

Methods

public function get_id()

Returns the claim ID.

public function get_actions()

Returns the array of claimed action IDs.

Claim Workflow (DB Store)

ActionScheduler_Store::stake_claim() is implemented by the DB store to claim a batch of actions:

1. Generate claim ID

   • ActionScheduler_DBStore::generate_claim_id() inserts a row into the actionscheduler_claims table and returns the new ID.

2. Select and claim actions

   • ActionScheduler_DBStore::claim_actions() selects pending actions (status = pending) with claim_id = 0 and scheduled_date_gmt <= now.
   • Optional filters include hooks and group.
   • Actions are ordered by priority ASC, attempts ASC, scheduled_date_gmt ASC, action_id ASC (filterable via action_scheduler_claim_actions_order_by).
   • The DB store uses SELECT ... FOR UPDATE and, when supported, SKIP LOCKED to avoid deadlocks.
   • The matched rows are updated to set claim_id and update attempt timestamps.

3. Resolve claimed IDs

   • ActionScheduler_DBStore::find_actions_by_claim_id() fetches the list of action IDs in the claim, validating each scheduled date against the original cut-off time.

4. Return a claim object

   • stake_claim() returns an ActionScheduler_ActionClaim containing the claim ID and action IDs.

Releasing Claims

ActionScheduler_Store::release_claim() removes the claim and makes pending actions available for re-claiming.

In the DB store:

• Pending actions within the claim are located by ID and updated to claim_id = 0.
• The claim row is deleted from the actionscheduler_claims table.
• If fewer rows are updated than expected, a RuntimeException is thrown.

Related Store APIs

These store methods coordinate with claims and are used by queue runners and other internal components:

• ActionScheduler_Store::stake_claim()
• ActionScheduler_Store::get_claim_count()
• ActionScheduler_Store::release_claim()
• ActionScheduler_Store::unclaim_action()

Usage Notes

Claims are used to manage concurrency. ActionScheduler_Abstract_QueueRunner::has_maximum_concurrent_batches() consults ActionScheduler_Store::get_claim_count() to determine whether additional batches should be started. This ensures only a limited number of concurrent processors are running at once.