GravityKit\GravityMigrate\Background\SchedulerGateway
Every product ships its own Strauss-prefixed copy of Foundation, and only the newest
(the "winning" copy, resolved through the global \GravityKitFoundation class) provides the
scheduler API this plugin drives background jobs through. The winning copy is not
necessarily this plugin's own, so nothing outside this class may call
GravityKitFoundation::scheduler(), new NextRunRules(), new TaskException(), or
type-hint JobInstance against a vendored namespace. Everything this class hands back is
duck-typed and untyped for the same reason.
Since: %ver%
Source: src/Background/SchedulerGateway.php:25
Details
- Kind:
class - Namespace:
GravityKit\GravityMigrate\Background
Methods
| Method | Description |
|---|---|
get_instance() | Returns the singleton instance. |
reset_instance() | Resets the singleton. Test seam only -- production code never needs a fresh instance |
is_available() | Whether a usable Foundation scheduler is currently resolvable. |
can_dispatch() | Whether the resolved scheduler can dispatch jobs asynchronously right now. |
scheduler() | Returns the winning Foundation scheduler instance, untyped. |
checkpoint() | Delegates to the winning scheduler's checkpoint(), requesting the current task rerun |
checkpoint_with_data() | Delegates to the winning scheduler's checkpoint_with_data(), requesting a rerun with |
complete_with_data() | Finishes the current task while writing final shared job data: checkpoints with empty |
should_continue() | Whether there is still time left in the current task's cooperative time budget. |
is_job_active() | Whether a job instance is pending, running, or paused. Paused counts as active: a paused |
job_is_live_fresh() | Whether a job instance is pending, running, or paused, read fresh from the database. |
get_job() | Returns a job instance by id, or null when it cannot be found or read. |
active_job_ids() | The instance ids of every live job of a given name -- pending, running, or paused. |
get_job_error() | Best-effort error message for a failed job's action, read from its activity log. |
has_memory_headroom() | Whether the current task execution still has memory headroom to run another step. |
has_headroom_for() | The memory decision itself, over plain numbers. |
has_pending_task_action() | Whether an unrun task action for this job is sitting in the Action Scheduler queue. |
dispatch_queue() | Fires the scheduler's own async loopback request so the Action Scheduler queue runner |
Method Reference
get_instance()
public static function get_instance(): self
Returns the singleton instance.
Returns
self
Since: %ver%
Source: src/Background/SchedulerGateway.php:127
reset_instance()
public static function reset_instance(): void
Resets the singleton. Test seam only -- production code never needs a fresh instance
mid-request.
Returns
void
Since: %ver%
Source: src/Background/SchedulerGateway.php:143
is_available()
public function is_available(): bool
Whether a usable Foundation scheduler is currently resolvable.
True only when the global GravityKitFoundation class exists, calling its scheduler()
accessor does not throw, the result is an object, and that object exposes every method in
\self::REQUIRED_SCHEDULER_METHODS(). False for a winning Foundation copy too old to
register a scheduler component, and false when Action Scheduler itself failed to load
(Foundation only registers the component when ActionScheduler_DBStore exists).
Returns
bool
Since: %ver%
Source: src/Background/SchedulerGateway.php:160
can_dispatch()
public function can_dispatch(): bool
Whether the resolved scheduler can dispatch jobs asynchronously right now.
Returns
bool— False whenever {@see self::is_available()} is false.
Since: %ver%
Source: src/Background/SchedulerGateway.php:171
scheduler()
public function scheduler()
Returns the winning Foundation scheduler instance, untyped.
Returns
mixed
Throws
Exception— When no usable scheduler is currently resolvable.
Since: %ver%
Source: src/Background/SchedulerGateway.php:194
checkpoint()
public function checkpoint( array $next_args )
Delegates to the winning scheduler's checkpoint(), requesting the current task rerun
with $next_args merged into its existing args.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$next_args | array | Keys to merge for the next execution. |
Returns
mixed— ANextRunRules-shaped object from the winning Foundation copy, untyped.
Since: %ver%
Source: src/Background/SchedulerGateway.php:214
checkpoint_with_data()
public function checkpoint_with_data( array $next_args, array $job_data )
Delegates to the winning scheduler's checkpoint_with_data(), requesting a rerun with
both updated task args and updated shared job data.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$next_args | array | Keys to merge into task args for the next execution. | |
$job_data | array | Keys to merge into shared job data. |
Returns
mixed— ANextRunRules-shaped object from the winning Foundation copy, untyped.
Since: %ver%
Source: src/Background/SchedulerGateway.php:229
complete_with_data()
public function complete_with_data( array $job_data )
Finishes the current task while writing final shared job data: checkpoints with empty
next-task args and the given job data, then flips the result to not rerun.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$job_data | array | Final shared job data (e.g. a completion summary). |
Returns
mixed— ANextRunRules-shaped object from the winning Foundation copy, untyped.
Since: %ver%
Source: src/Background/SchedulerGateway.php:243
should_continue()
public function should_continue( array $args, int $margin=self::SHOULD_CONTINUE_DEFAULT_MARGIN ): bool
Whether there is still time left in the current task's cooperative time budget.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$args | array | Task args (the deadline lives in $args['_meta']['deadline']). | |
$margin | int | self::SHOULD_CONTINUE_DEFAULT_MARGIN | Seconds before the deadline to stop. |
Returns
bool— True when unavailable, matching the winning scheduler's own "no deadline set -> keep going" default, so a caller degrades to "just keep looping" rather than stalling.
Since: %ver%
Source: src/Background/SchedulerGateway.php:265
is_job_active()
public function is_job_active( int $job_id ): bool
Whether a job instance is pending, running, or paused. Paused counts as active: a paused
import's temp tables are still live, so nothing should reclaim what it's holding.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$job_id | int | Job instance id. |
Returns
bool
Since: %ver%
Source: src/Background/SchedulerGateway.php:289
job_is_live_fresh()
public function job_is_live_fresh( int $job_id ): bool
Whether a job instance is pending, running, or paused, read fresh from the database.
\self::is_job_active() answers the same question through the scheduler's manager,
which caches each instance -- status included -- for the life of the request. A driver
asking about its OWN job mid-run needs the answer another process may have just changed
(a cancel marks the instance canceled before its cleanup hook deletes the state
option), so this reads the Action Scheduler row directly, with no cache in front of it.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$job_id | int | Job instance id. |
Returns
bool— False when the instance is terminal, missing, or unreadable.
Since: %ver%
Source: src/Background/SchedulerGateway.php:318
get_job()
public function get_job( int $job_id )
Returns a job instance by id, or null when it cannot be found or read.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$job_id | int | Job instance id. |
Returns
mixed— AJobInstance-shaped object from the winning Foundation copy, or null.
Since: %ver%
Source: src/Background/SchedulerGateway.php:352
active_job_ids()
public function active_job_ids( string $job_name ): array
The instance ids of every live job of a given name -- pending, running, or paused.
The only way to find a job whose id was never written down anywhere. Import and export each record theirs in a state option, so a page that was not there when the run started can ask about them by id. A background external-import batch keeps everything in its own job data and records nothing outside it, so a reloaded page has no id to ask about a platform migration that is still running.
Paused counts as live for the same reason it does in \self::is_job_active(): a paused
job resumes, so a page that ignored one would tell the operator their migration had stopped.
This is a candidate list, not a verdict: every reader re-reads the instance it names and checks the status itself, so a history reader that over-reports cannot widen what a caller acts on.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$job_name | string | Job name (hook name). |
Returns
int[]— Newest first, so a caller wanting one job gets the most recent. Empty when the scheduler is unavailable or its history cannot be read.
Since: %ver%
Source: src/Background/SchedulerGateway.php:389
get_job_error()
public function get_job_error( string $job_name, int $job_id ): string
Best-effort error message for a failed job's action, read from its activity log.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$job_name | string | Job name (hook name). | |
$job_id | int | Job instance id. |
Returns
string— The error message, or '' when unavailable or none is recorded.
Since: %ver%
Source: src/Background/SchedulerGateway.php:448
has_memory_headroom()
public function has_memory_headroom( array $args=[] ): bool
Whether the current task execution still has memory headroom to run another step.
True when the memory limit is unlimited or unreadable.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$args | array | [] |
Returns
bool
Since: %ver%
Source: src/Background/SchedulerGateway.php:485
has_headroom_for()
public static function has_headroom_for( int $usage, int $limit_bytes, int $baseline ): bool
The memory decision itself, over plain numbers.
A worker that STARTED above the fraction is not stopped where it stands: it would checkpoint after every single item and make no progress, turning a three-slice batch into one async action per form. What is budgeted in that case is growth -- half of whatever space was left above the point the execution began. A run that started with room and grew into the fraction is stopped as before.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$usage | int | Bytes in use now. | |
$limit_bytes | int | The PHP memory limit in bytes. 0 or negative means no limit. | |
$baseline | int | Bytes in use when this task execution began, 0 if unknown. |
Returns
bool
Since: %ver%
Source: src/Background/SchedulerGateway.php:520
has_pending_task_action()
public function has_pending_task_action( int $job_id, string $job_name ): bool
Whether an unrun task action for this job is sitting in the Action Scheduler queue.
A pending task action is normally claimed within a second of being scheduled; one that a
status poll can still observe means the queue has no runner coming -- the dispatch that
should have started it was dropped (e.g. it landed while another batch held the runner
lock) and, on a site without a working WP-Cron, nothing ever retries. The hook and group
names mirror how Foundation enqueues task actions
(\GravityKit\Foundation\Scheduler\Handlers\TaskExecutor::schedule_task()): the
\GravityKit\Foundation\Scheduler\Handlers\TaskExecutor::HOOK() hook with
[ $job_id, $job_name ] args in the
\GravityKit\Foundation\Scheduler\Store\DbStore::TASK_GROUP_ID() group. Written as
strings, per the cross-namespace rule; as_next_scheduled_action() itself is a global,
unprefixed Action Scheduler function.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$job_id | int | Job instance id. | |
$job_name | string | Job name (hook name). |
Returns
bool
Since: %ver%
Source: src/Background/SchedulerGateway.php:556
dispatch_queue()
public function dispatch_queue(): void
Fires the scheduler's own async loopback request so the Action Scheduler queue runner
starts processing pending actions now.
Safe to call while a runner is already active: Action Scheduler's claim and lock machinery serializes concurrent runners, so a redundant kick is a no-op.
Returns
void
Since: %ver%
Source: src/Background/SchedulerGateway.php:581