Defer callable updates to run later in the PHP process. More...

Static Public Member Functions
static	addCallableUpdate ( $callable, $stage=self::POSTSEND, $dbw=null)
	Add an update to the pending update queue that invokes the specified callback when run.

static	addUpdate (DeferrableUpdate $update, $stage=self::POSTSEND)
	Add an update to the pending update queue for execution at the appropriate time.

static	attemptUpdate (DeferrableUpdate $update)
	Attempt to run an update with the appropriate transaction round state if needed.

static	clearPendingUpdates ()
	Cancel all pending updates for the current execution context.

static	doUpdates ( $stage=self::ALL)
	Consume and execute all pending updates.

static	getPendingUpdates ( $stage=self::ALL)
	Get a list of the pending updates for the current execution context.

static	getRecursiveExecutionStackDepth ()
	Get the number of in-progress calls to DeferredUpdates::doUpdates()

static	pendingUpdatesCount ()
	Get the number of pending updates for the current execution context.

static	preventOpportunisticUpdates ()
	Prevent opportunistic updates until the returned ScopedCallback is consumed.

static	setScopeStack (DeferredUpdatesScopeStack $scopeStack)

static	tryOpportunisticExecute ()
	Consume and execute pending updates now if possible, instead of waiting.

Detailed Description

Defer callable updates to run later in the PHP process.

This is a performance feature that enables MediaWiki to produce faster web responses. It allows you to postpone non-blocking work (e.g. work that does not change the web response) to after the HTTP response has been sent to the client (i.e. web browser).

Once the response is finalized and sent to the browser, the webserver process stays for a little while longer (detached from the web request) to run your POSTSEND tasks.

There is also a PRESEND option, which runs your task right before the finalized response is sent to the browser. This is for critical tasks that does need to block the response, but where you'd like to benefit from other DeferredUpdates features. Such as:

MergeableUpdate: batch updates from different components without coupling or awareness of each other.
Automatic cancellation: pass a IDatabase object (for any wiki or database) to DeferredUpdates::addCallableUpdate or AtomicSectionUpdate.
Reducing lock contention: if the response is likely to take several seconds (e.g. uploading a large file to FileBackend, or saving an edit to a large article) much of that work may overlap with a database transaction that is staying open for the entire duration. By moving contentious writes out to a PRESEND update, these get their own transaction (after the main one is committed), which give up some atomicity for improved throughput.

Expectation and comparison to job queue

When scheduling a POSTSEND via the DeferredUpdates system you can generally expect it to complete well before the client makes their next request. Updates runs directly after the web response is sent, from the same process on the same server. This unlike the JobQueue, where jobs may need to wait in line for some minutes or hours.

If your update fails, this failure is not known to the client and gets no retry. For updates that need re-tries for system consistency or data integrity, it is recommended to implement it as a job instead and use JobQueueGroup::lazyPush. This has the caveat of being delayed by default, the same as any other job.

A hybrid solution is available via the EnqueueableDataUpdate interface. By implementing this interface, you can queue your update via the DeferredUpdates first, and if it fails, the system will automatically catch this and queue it as a job instead.

How it works during web requests

Your request route is executed (e.g. Action or SpecialPage class, or API).
Output is finalized and main database transaction is committed.
PRESEND updates run via DeferredUpdates::doUpdates.
The web response is sent to the browser.
POSTSEND updates run via DeferredUpdates::doUpdates.

See also: MediaWiki::preOutputCommit; MediaWiki::restInPeace

How it works for Maintenance scripts

In CLI mode, no distinction is made between PRESEND and POSTSEND deferred updates, and the queue is periodically executed throughout the process.

See also: DeferredUpdates::tryOpportunisticExecute

How it works internally

Each update is added via DeferredUpdates::addUpdate and stored in either the PRESEND or POSTSEND queue. If an update gets queued while another update is already running, then we store in a "sub"-queue associated with the current update. This allows nested updates to be completed before other updates, which improves ordering for process caching.

Since: 1.19

Definition at line 99 of file DeferredUpdates.php.

Member Function Documentation

◆ addCallableUpdate()

static MediaWiki\Deferred\DeferredUpdates::addCallableUpdate	(	$callable,
		$stage = self::POSTSEND,
		$dbw = null )

static

Add an update to the pending update queue that invokes the specified callback when run.

Parameters

callable	$callable
int	$stage	One of (DeferredUpdates::PRESEND, DeferredUpdates::POSTSEND)
IDatabase \| IDatabase[] \| null	$dbw	Cancel the update if a DB transaction is rolled back [optional]

Since: 1.27 Added $stage parameter; 1.28 Added the $dbw parameter

Definition at line 175 of file DeferredUpdates.php.

References wfGetCaller().

Referenced by MediaWiki\Deferred\LinksUpdate\LinksDeletionUpdate\doIncrementalUpdate().

◆ addUpdate()

static MediaWiki\Deferred\DeferredUpdates::addUpdate	(	DeferrableUpdate	$update,
			$stage = self::POSTSEND )

static

Add an update to the pending update queue for execution at the appropriate time.

In CLI mode, callback magic will also be used to run updates when safe

If an update is already in progress, then what happens to this update is as follows:

If it has a "defer until" stage at/before the actual run stage of the innermost in-progress update, then it will go into the sub-queue of that in-progress update. As soon as that update completes, MergeableUpdate instances in its sub-queue will be merged into the top-queues and the non-MergeableUpdate instances will be executed. This is done to better isolate updates from the failures of other updates and reduce the chance of race conditions caused by updates not fully seeing the intended changes of previously enqueued and executed updates.
If it has a "defer until" stage later than the actual run stage of the innermost in-progress update, then it will go into the normal top-queue for that stage.

Parameters

DeferrableUpdate	$update	Some object that implements doUpdate()
int	$stage	One of (DeferredUpdates::PRESEND, DeferredUpdates::POSTSEND)

Since: 1.28 Added the $stage parameter

Definition at line 160 of file DeferredUpdates.php.

Referenced by MediaWiki\Deferred\LinksUpdate\LinksUpdate\doUpdate().

◆ attemptUpdate()

static MediaWiki\Deferred\DeferredUpdates::attemptUpdate ( DeferrableUpdate $update )

static

Attempt to run an update with the appropriate transaction round state if needed.

It is allowed for a DeferredUpdate to directly execute one or more other DeferredUpdate instances without queueing them by calling this method. In that case, the outer update must use TransactionRoundAwareUpdate::TRX_ROUND_ABSENT, e.g. by extending TransactionRoundDefiningUpdate, so that this method can give each update its own transaction round.

Parameters

DeferrableUpdate $update

Since: 1.34

Definition at line 483 of file DeferredUpdates.php.

References MediaWiki\Deferred\DeferrableUpdate\doUpdate().

◆ clearPendingUpdates()

static MediaWiki\Deferred\DeferredUpdates::clearPendingUpdates ( )

static

Cancel all pending updates for the current execution context.

If an update is in progress, then this operates on the sub-queues of the innermost in-progress update. Otherwise, it acts on the top-queues.

Access: internal: This method should only be used for unit tests

Definition at line 457 of file DeferredUpdates.php.

◆ doUpdates()

static MediaWiki\Deferred\DeferredUpdates::doUpdates ( $stage = self::ALL )

static

Consume and execute all pending updates.

Note that it is rarely the case that this method should be called outside of a few select entry points. For simplicity, that kind of recursion is discouraged. Recursion cannot happen if an explicit transaction round is active, which limits usage to updates with TRX_ROUND_ABSENT that do not leave open any transactions round of their own during the call to this method.

In the less-common case of this being called within an in-progress DeferrableUpdate, this will not see any top-queue updates (since they were consumed and are being run inside an outer execution loop). In that case, it will instead operate on the sub-queue of the innermost in-progress update on the stack.

Access: internal: For use by MediaWiki, Maintenance, JobRunner, JobExecutor

Parameters

int $stage Which updates to process. One of (DeferredUpdates::PRESEND, DeferredUpdates::POSTSEND, DeferredUpdates::ALL)

Definition at line 255 of file DeferredUpdates.php.

References run().

◆ getPendingUpdates()

static MediaWiki\Deferred\DeferredUpdates::getPendingUpdates ( $stage = self::ALL )

static

Get a list of the pending updates for the current execution context.

If an update is in progress, then this operates on the sub-queues of the innermost in-progress update. Otherwise, it acts on the top-queues.

Parameters

int $stage Look for updates with this "defer until" stage. One of (DeferredUpdates::PRESEND, DeferredUpdates::POSTSEND, DeferredUpdates::ALL)

Returns: DeferrableUpdate[]

Access: internal: This method should only be used for unit tests

Since: 1.29

Definition at line 445 of file DeferredUpdates.php.

◆ getRecursiveExecutionStackDepth()

static MediaWiki\Deferred\DeferredUpdates::getRecursiveExecutionStackDepth ( )

static

Get the number of in-progress calls to DeferredUpdates::doUpdates()

Returns: int

Access: internal: This method should only be used for unit tests

Definition at line 467 of file DeferredUpdates.php.

◆ pendingUpdatesCount()

static MediaWiki\Deferred\DeferredUpdates::pendingUpdatesCount ( )

static

Get the number of pending updates for the current execution context.

If an update is in progress, then this operates on the sub-queues of the innermost in-progress update. Otherwise, it acts on the top-queues.

Returns: int

Since: 1.28

Definition at line 429 of file DeferredUpdates.php.

◆ preventOpportunisticUpdates()

static MediaWiki\Deferred\DeferredUpdates::preventOpportunisticUpdates ( )

static

Prevent opportunistic updates until the returned ScopedCallback is consumed.

Returns: ScopedCallback

Definition at line 413 of file DeferredUpdates.php.

◆ setScopeStack()

static MediaWiki\Deferred\DeferredUpdates::setScopeStack ( DeferredUpdatesScopeStack $scopeStack )

static

Parameters

DeferredUpdatesScopeStack $scopeStack

Access: internal: Only for use in tests.

Definition at line 133 of file DeferredUpdates.php.

◆ tryOpportunisticExecute()

static MediaWiki\Deferred\DeferredUpdates::tryOpportunisticExecute ( )

static

Consume and execute pending updates now if possible, instead of waiting.

In web requests, updates are always deferred until the end of the request.

In CLI mode, updates run earlier and more often. This is important for long-running Maintenance scripts that would otherwise grow an excessively large queue, which increases memory use, and risks losing all updates if the script ends early or crashes.

The folllowing conditions are required for updates to run early in CLI mode:

No update is already in progress (ensure linear flow, recursion guard).
LBFactory indicates that we don't have any "busy" database connections, i.e. there are no pending writes or otherwise active and uncommitted transactions, except if the transaction is empty and merely used for primary DB read queries, in which case the transaction (and its repeatable-read snapshot) can be safely flushed.

How this works:

When a maintenance script commits a change or waits for replication, such as via. IConnectionProvider::commitAndWaitForReplication, then ILBFactory calls tryOpportunisticExecute(). This is injected via MWLBFactory::applyGlobalState.
For maintenance scripts that don't do much with the database, we also call tryOpportunisticExecute() after every addUpdate() call.
Upon the completion of Maintenance::execute() via Maintenance::shutdown(), any remaining updates are run.

Note that this method runs both PRESEND and POSTSEND updates and thus should not be called during web requests. It is only intended for long-running Maintenance scripts.

Access: internal: For use by Maintenance

Since: 1.28

Returns: bool Whether updates were allowed to run

Definition at line 358 of file DeferredUpdates.php.

The documentation for this class was generated from the following file:

includes/deferred/DeferredUpdates.php

Static Public Member Functions

Detailed Description

Expectation and comparison to job queue

How it works during web requests

How it works for Maintenance scripts

How it works internally

Member Function Documentation

◆ addCallableUpdate()

◆ addUpdate()

◆ attemptUpdate()

◆ clearPendingUpdates()

◆ doUpdates()

◆ getPendingUpdates()

◆ getRecursiveExecutionStackDepth()

◆ pendingUpdatesCount()

◆ preventOpportunisticUpdates()

◆ setScopeStack()

◆ tryOpportunisticExecute()