MediaWiki  master
DeferredUpdates Class Reference

Class for managing the deferred updates. More...

Collaboration diagram for DeferredUpdates:

Static Public Member Functions

static addCallableUpdate ( $callable, $stage=self::POSTSEND, $dbw=null)
 Add a callable update. More...
 
static addUpdate (DeferrableUpdate $update, $stage=self::POSTSEND)
 Add an update to the deferred list to be run later by execute() More...
 
static attemptUpdate (DeferrableUpdate $update, ILBFactory $lbFactory)
 Attempt to run an update with the appropriate transaction round state it expects. More...
 
static clearPendingUpdates ()
 Clear all pending updates without performing them. More...
 
static doUpdates ( $mode='run', $stage=self::ALL)
 Do any deferred updates and clear the list. More...
 
static getPendingUpdates ( $stage=self::ALL)
 
static pendingUpdatesCount ()
 
static tryOpportunisticExecute ( $mode='run')
 Run all deferred updates immediately if there are no DB writes active. More...
 

Public Attributes

const ALL = 0
 
const BIG_QUEUE_SIZE = 100
 
const POSTSEND = 2
 
const PRESEND = 1
 

Static Protected Member Functions

static handleUpdateQueue (array &$queue, $mode, $stage)
 Immediately run or enqueue a list of updates. More...
 

Static Private Member Functions

static areDatabaseTransactionsActive ()
 
static enqueueUpdates (array $updates)
 Enqueue a job for each EnqueueableDataUpdate item and return the other items. More...
 
static jobify (EnqueueableDataUpdate $update, LBFactory $lbFactory, LoggerInterface $logger, StatsdDataFactoryInterface $stats, $httpMethod)
 Push a task into the job queue system and catch/log any exceptions. More...
 
static push (array &$queue, DeferrableUpdate $update)
 
static run (DeferrableUpdate $update, LBFactory $lbFactory, LoggerInterface $logger, StatsdDataFactoryInterface $stats, $httpMethod)
 Run a task and catch/log any exceptions. More...
 

Static Private Attributes

static array null $executeContext
 Information about the current execute() call or null if not running. More...
 
static DeferrableUpdate [] $postSendUpdates = []
 Updates to be deferred until after request end. More...
 
static DeferrableUpdate [] $preSendUpdates = []
 Updates to be deferred until before request end. More...
 

Detailed Description

Class for managing the deferred updates.

In web request mode, deferred updates can be run at the end of the request, either before or after the HTTP response has been sent. In either case, they run after the DB commit step. If an update runs after the response is sent, it will not block clients. If sent before, it will run synchronously. These two modes are defined via PRESEND and POSTSEND constants, the latter being the default for addUpdate() and addCallableUpdate().

Updates that work through this system will be more likely to complete by the time the client makes their next request after this one than with the JobQueue system.

In CLI mode, deferred updates will run:

  • a) During DeferredUpdates::addUpdate if no LBFactory DB handles have writes pending
  • b) On commit of an LBFactory DB handle if no other such handles have writes pending
  • c) During an LBFactory::waitForReplication call if no LBFactory DBs have writes pending
  • d) When the queue is large and an LBFactory DB handle commits (EnqueueableDataUpdate only)
  • e) At the completion of Maintenance::execute()
See also
Maintenance::setLBFactoryTriggers

When updates are deferred, they go into one two FIFO "top-queues" (one for pre-send and one for post-send). Updates enqueued during doUpdate() of a "top" update go into the "sub-queue" for that update. After that method finishes, the sub-queue is run until drained. This continues for each top-queue job until the entire top queue is drained. This happens for the pre-send top-queue, and later on, the post-send top-queue, in execute().

Since
1.19

Definition at line 61 of file DeferredUpdates.php.

Member Function Documentation

◆ addCallableUpdate()

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

Add a callable update.

In a lot of cases, we just need a callback/closure, defining a new DeferrableUpdate object is not necessary

See also
MWCallableUpdate::__construct()
Parameters
callable$callable
int$stageDeferredUpdates constant (PRESEND or POSTSEND) (since 1.27)
IDatabase|IDatabase[]|null$dbw Abort if this DB is rolled back optional

Definition at line 123 of file DeferredUpdates.php.

References wfGetCaller().

Referenced by MediaWiki\Auth\AuthManager\autoCreateUser(), MediaWiki\Auth\LocalPasswordPrimaryAuthenticationProvider\beginPrimaryAuthentication(), SpecialEditWatchlist\cleanupWatchlist(), User\clearNotification(), FileBackendMultiWrite\doDirectoryOp(), LinksDeletionUpdate\doIncrementalUpdate(), FileBackendMultiWrite\doOperationsInternal(), FileBackendMultiWrite\doQuickOperationsInternal(), MediaWiki\Storage\DerivedPageDataUpdater\doUpdates(), WikiPage\doViewUpdates(), EditPage\edit(), RollbackAction\enableTransactionalTimelimit(), ApiRollback\execute(), MovePageForm\execute(), MediaWiki\Logger\Monolog\BufferHandler\handle(), Category\initialize(), WikiPage\insertRedirect(), LocalFile\maybeUpgradeRow(), ResourceLoader\measureResponseTime(), RecentChange\notifyEdit(), RecentChange\notifyNew(), WikiPage\onArticleEdit(), ManualLogEntry\publish(), WikiPage\purgeInterwikiCheckKey(), MediaWiki\Session\SessionBackend\save(), SpecialSearch\saveNamespaces(), MediaWiki\Storage\PageUpdater\saveRevision(), Pingback\schedulePingback(), RevDelList\setVisibility(), DeferredUpdatesTest\testAddCallableUpdate(), DeferredUpdatesTest\testDoUpdatesCLI(), DeferredUpdatesTest\testDoUpdatesWeb(), MediaWikiTest\testPostSendJobDoesNotSetCookie(), DeferredUpdatesTest\testPresendAddOnPostsendRun(), CdnCacheUpdateTest\testPurgeMergeWeb(), DeferredUpdatesTest\testRunUpdateTransactionScope(), DeferredUpdatesTest\testTryOpportunisticExecute(), MediaWiki\Block\BlockManager\trackBlockWithCookie(), WikiPage\updateCategoryCounts(), WatchedItemStore\updateNotificationTimestamp(), and EditPage\updateWatchlist().

◆ addUpdate()

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

Add an update to the deferred list to be run later by execute()

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

Parameters
DeferrableUpdate$updateSome object that implements doUpdate()
int$stageDeferredUpdates constant (PRESEND or POSTSEND) (since 1.27)

Definition at line 84 of file DeferredUpdates.php.

References $wgCommandLineMode.

Referenced by MediaWiki\Auth\AuthManager\autoCreateUser(), MediaWiki\Auth\AuthManager\continueAccountCreation(), LocalFile\delete(), LocalFile\deleteOld(), MediaWiki\Storage\PageUpdater\doCreate(), WikiPage\doDeleteUpdates(), MediaWiki\Storage\PageUpdater\doModify(), RevDelFileList\doPostCommitUpdates(), WikiFilePage\doPurge(), WikiPage\doPurge(), MediaWiki\Storage\DerivedPageDataUpdater\doSecondaryDataUpdates(), LinksUpdate\doUpdate(), MediaWiki\Storage\DerivedPageDataUpdater\doUpdates(), SpecialRunJobs\execute(), LocalFileRestoreBatch\execute(), ChangesListSpecialPage\execute(), WikiImporter\finishImportPage(), User\incEditCount(), Title\invalidateCache(), PurgeJobUtils\invalidatePages(), LinksUpdate\invalidateProperties(), JobQueueGroup\lazyPush(), NamespaceDupes\mergePage(), LocalFile\move(), MovePage\moveUnsafe(), WikiPage\onArticleCreate(), WikiPage\onArticleDelete(), WikiPage\onArticleEdit(), LocalFile\purgeCache(), File\purgeEverything(), MediaWiki\Block\DatabaseBlock\purgeExpired(), Title\purgeExpiredRestrictions(), LocalFile\purgeOldThumbnails(), Title\purgeSquid(), LocalFile\purgeThumbnails(), LocalFile\recordUpload2(), MessageCache\replace(), DeferredUpdatesTest\testAddAndRun(), DeferredUpdatesTest\testAddMergeable(), SiteStatsUpdateTest\testDoUpdate(), DeferredUpdatesTest\testGetPendingUpdates(), CdnCacheUpdateTest\testPurgeMergeWeb(), DeferredUpdatesTest\testRunOuterScopeUpdate(), Title\touchLinks(), and PageArchive\undeleteRevisions().

◆ areDatabaseTransactionsActive()

static DeferredUpdates::areDatabaseTransactionsActive ( )
staticprivate
Returns
bool If a transaction round is active or connection is not ready for commit()

Definition at line 470 of file DeferredUpdates.php.

References Wikimedia\Rdbms\IDatabase\explicitTrxActive(), Wikimedia\Rdbms\LoadBalancer\forEachOpenMasterConnection(), use, and Wikimedia\Rdbms\IDatabase\writesOrCallbacksPending().

◆ attemptUpdate()

static DeferredUpdates::attemptUpdate ( DeferrableUpdate  $update,
ILBFactory  $lbFactory 
)
static

Attempt to run an update with the appropriate transaction round state it expects.

DeferredUpdate classes that wrap the execution of bundles of other DeferredUpdate instances can use this method to run the updates. Any such wrapper class should always use TRX_ROUND_ABSENT itself.

Parameters
DeferrableUpdate$update
ILBFactory$lbFactory
Since
1.34

Definition at line 354 of file DeferredUpdates.php.

References Wikimedia\Rdbms\ILBFactory\beginMasterChanges(), Wikimedia\Rdbms\ILBFactory\commitMasterChanges(), DeferrableUpdate\doUpdate(), Wikimedia\Rdbms\ILBFactory\getEmptyTransactionTicket(), and null.

Referenced by MediaWiki\Storage\DerivedPageDataUpdater\doSecondaryDataUpdates().

◆ clearPendingUpdates()

static DeferredUpdates::clearPendingUpdates ( )
static

Clear all pending updates without performing them.

Generally, you don't want or need to call this. Unit tests need it though.

Definition at line 462 of file DeferredUpdates.php.

Referenced by MediaWikiIntegrationTestCase\resetNonServiceCaches(), UploadFromUrlTestSuite\setUp(), DeferredUpdatesTest\testGetPendingUpdates(), and CdnCacheUpdateTest\testPurgeMergeWeb().

◆ doUpdates()

static DeferredUpdates::doUpdates (   $mode = 'run',
  $stage = self::ALL 
)
static

◆ enqueueUpdates()

static DeferredUpdates::enqueueUpdates ( array  $updates)
staticprivate

Enqueue a job for each EnqueueableDataUpdate item and return the other items.

Parameters
DeferrableUpdate[]$updates A list of deferred update instances
Returns
DeferrableUpdate[] Remaining updates that do not support being queued

Definition at line 418 of file DeferredUpdates.php.

References as, and JobQueueGroup\singleton().

◆ getPendingUpdates()

static DeferredUpdates::getPendingUpdates (   $stage = self::ALL)
static
Parameters
int$stageDeferredUpdates constant (PRESEND, POSTSEND, or ALL)
Returns
DeferrableUpdate[]
Since
1.29

Definition at line 447 of file DeferredUpdates.php.

Referenced by DeferredUpdatesTest\testGetPendingUpdates().

◆ handleUpdateQueue()

static DeferredUpdates::handleUpdateQueue ( array &  $queue,
  $mode,
  $stage 
)
staticprotected

Immediately run or enqueue a list of updates.

Parameters
DeferrableUpdate[]&$queue List of DeferrableUpdate objects
string$modeEither "run" or "enqueue" (to use the job queue when possible)
int$stageClass constant (PRESEND, POSTSEND) (since 1.28)
Exceptions
ErrorPageErrorHappens on top-level calls
ExceptionHappens on second-level calls

Definition at line 185 of file DeferredUpdates.php.

References $e, $queue, $services, as, RequestContext\getMain(), key, and null.

◆ jobify()

static DeferredUpdates::jobify ( EnqueueableDataUpdate  $update,
LBFactory  $lbFactory,
LoggerInterface  $logger,
StatsdDataFactoryInterface  $stats,
  $httpMethod 
)
staticprivate

Push a task into the job queue system and catch/log any exceptions.

Parameters
EnqueueableDataUpdate$update
LBFactory$lbFactory
LoggerInterface$logger
StatsdDataFactoryInterface$stats
string$httpMethod

Definition at line 313 of file DeferredUpdates.php.

References $e, EnqueueableDataUpdate\getAsJobSpecification(), null, Wikimedia\Rdbms\LBFactory\rollbackMasterChanges(), and JobQueueGroup\singleton().

◆ pendingUpdatesCount()

◆ push()

static DeferredUpdates::push ( array &  $queue,
DeferrableUpdate  $update 
)
staticprivate
Parameters
DeferrableUpdate[]$queue
DeferrableUpdate$update

Definition at line 157 of file DeferredUpdates.php.

◆ run()

static DeferredUpdates::run ( DeferrableUpdate  $update,
LBFactory  $lbFactory,
LoggerInterface  $logger,
StatsdDataFactoryInterface  $stats,
  $httpMethod 
)
staticprivate

Run a task and catch/log any exceptions.

Parameters
DeferrableUpdate$update
LBFactory$lbFactory
LoggerInterface$logger
StatsdDataFactoryInterface$stats
string$httpMethod
Returns
Exception|Throwable|null

Definition at line 266 of file DeferredUpdates.php.

References $e, $name, null, and Wikimedia\Rdbms\LBFactory\rollbackMasterChanges().

◆ tryOpportunisticExecute()

static DeferredUpdates::tryOpportunisticExecute (   $mode = 'run')
static

Run all deferred updates immediately if there are no DB writes active.

If there are many deferred updates pending, $mode is 'run', and there are still busy LBFactory database handles, then any EnqueueableDataUpdate tasks might be enqueued as jobs to be executed later.

Parameters
string$modeUse "enqueue" to use the job queue when possible
Returns
bool Whether updates were allowed to run
Since
1.28

Definition at line 390 of file DeferredUpdates.php.

Referenced by Maintenance\setLBFactoryTriggers(), and DeferredUpdatesTest\testTryOpportunisticExecute().

Member Data Documentation

◆ $executeContext

array null DeferredUpdates::$executeContext
staticprivate

Information about the current execute() call or null if not running.

Definition at line 74 of file DeferredUpdates.php.

◆ $postSendUpdates

DeferrableUpdate [] DeferredUpdates::$postSendUpdates = []
staticprivate

Updates to be deferred until after request end.

Definition at line 65 of file DeferredUpdates.php.

◆ $preSendUpdates

DeferrableUpdate [] DeferredUpdates::$preSendUpdates = []
staticprivate

Updates to be deferred until before request end.

Definition at line 63 of file DeferredUpdates.php.

◆ ALL

const DeferredUpdates::ALL = 0

Definition at line 67 of file DeferredUpdates.php.

Referenced by DeferredUpdatesTest\testGetPendingUpdates().

◆ BIG_QUEUE_SIZE

const DeferredUpdates::BIG_QUEUE_SIZE = 100

Definition at line 71 of file DeferredUpdates.php.

◆ POSTSEND

◆ PRESEND


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