MediaWiki master
MediaWiki\Deferred\DeferredUpdates Class Reference

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

  1. Your request route is executed (e.g. Action or SpecialPage class, or API).
  2. Output is finalized and main database transaction is committed.
  3. PRESEND updates run via DeferredUpdates::doUpdates.
  4. The web response is sent to the browser.
  5. 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$stageOne of (DeferredUpdates::PRESEND, DeferredUpdates::POSTSEND)
IDatabase | IDatabase[] | null$dbwCancel 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$updateSome object that implements doUpdate()
int$stageOne 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$stageWhich 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$stageLook 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: