Code Coverage
 
Classes and Traits
Functions and Methods
Lines
Total
0.00% covered (danger)
0.00%
0 / 1
42.86% covered (danger)
42.86%
6 / 14
CRAP
59.89% covered (warning)
59.89%
109 / 182
DeferredUpdates
0.00% covered (danger)
0.00%
0 / 1
42.86% covered (danger)
42.86%
6 / 14
437.98
59.89% covered (warning)
59.89%
109 / 182
 addUpdate
100.00% covered (success)
100.00%
1 / 1
6
100.00% covered (success)
100.00%
13 / 13
 addCallableUpdate
100.00% covered (success)
100.00%
1 / 1
1
100.00% covered (success)
100.00%
2 / 2
 doUpdates
100.00% covered (success)
100.00%
1 / 1
9
100.00% covered (success)
100.00%
15 / 15
 push
100.00% covered (success)
100.00%
1 / 1
3
100.00% covered (success)
100.00%
10 / 10
 handleUpdateQueue
0.00% covered (danger)
0.00%
0 / 1
21.65
88.64% covered (warning)
88.64%
39 / 44
 run
0.00% covered (danger)
0.00%
0 / 1
42
0.00% covered (danger)
0.00%
0 / 30
 jobify
0.00% covered (danger)
0.00%
0 / 1
6
0.00% covered (danger)
0.00%
0 / 14
 attemptUpdate
0.00% covered (danger)
0.00%
0 / 1
7.10
87.50% covered (warning)
87.50%
14 / 16
 tryOpportunisticExecute
0.00% covered (danger)
0.00%
0 / 1
4.18
77.78% covered (warning)
77.78%
7 / 9
 enqueueUpdates
0.00% covered (danger)
0.00%
0 / 1
12
0.00% covered (danger)
0.00%
0 / 8
 pendingUpdatesCount
0.00% covered (danger)
0.00%
0 / 1
6
0.00% covered (danger)
0.00%
0 / 3
 getPendingUpdates
100.00% covered (success)
100.00%
1 / 1
5
100.00% covered (success)
100.00%
6 / 6
 clearPendingUpdates
100.00% covered (success)
100.00%
1 / 1
1
100.00% covered (success)
100.00%
3 / 3
 areDatabaseTransactionsActive
0.00% covered (danger)
0.00%
0 / 1
30
0.00% covered (danger)
0.00%
0 / 9
<?php
/**
 * Interface and manager for deferred updates.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 * http://www.gnu.org/copyleft/gpl.html
 *
 * @file
 */
use Liuggio\StatsdClient\Factory\StatsdDataFactoryInterface;
use MediaWiki\Logger\LoggerFactory;
use MediaWiki\MediaWikiServices;
use Psr\Log\LoggerInterface;
use Wikimedia\Rdbms\DBTransactionError;
use Wikimedia\Rdbms\IDatabase;
use Wikimedia\Rdbms\ILBFactory;
use Wikimedia\Rdbms\LBFactory;
use Wikimedia\Rdbms\LoadBalancer;
/**
 * 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 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 doUpdates().
 *
 * @since 1.19
 */
class DeferredUpdates {
    /**
     * @var DeferrableUpdate[] Updates to be deferred until just before HTTP response emission.
     *  Integer-keyed entries form a list of FIFO updates and a string-keyed entries form a map
     *  of (class => MergeableUpdate) for updates that absorb the work of any already pending
     *  updates of the same class.
     */
    private static $preSendUpdates = [];
    /**
     * @var DeferrableUpdate[] Updates to be deferred until just after HTTP response emission.
     *  Integer-keyed entries form a list of FIFO updates and a string-keyed entries form a map
     *  of (class => MergeableUpdate) for updates that absorb the work of any already pending
     *  updates of the same class.
     */
    private static $postSendUpdates = [];
    /**
     * @var array[] Execution stack of currently running updates
     * @phan-var array<array{stage:int,update:DeferrableUpdate,subqueue:DeferrableUpdate[]}>
     */
    private static $executionStack = [];
    public const ALL = 0; // all updates; in web requests, use only after flushing the output buffer
    public const PRESEND = 1; // for updates that should run before flushing output buffer
    public const POSTSEND = 2; // for updates that should run after flushing output buffer
    private const BIG_QUEUE_SIZE = 100;
    /**
     * Add an update to the deferred 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:
     *  - MergeableUpdate instances always go on the top-queue for the specified stage, with
     *    existing updates melding into the newly added instance at the end of the queue.
     *  - Non-MergeableUpdate instances with a "defer until" stage at/before the actual run
     *    stage of the innermost in-progress update go into the sub-queue of that in-progress
     *    update. They are executed right after the update finishes to maximize isolation.
     *  - Non-MergeableUpdate instances with a "defer until" stage after the actual run stage
     *    of the innermost in-progress update go into the normal top-queue for that stage.
     *
     * @param DeferrableUpdate $update Some object that implements doUpdate()
     * @param int $stage DeferredUpdates constant (PRESEND or POSTSEND) (since 1.27)
     */
    public static function addUpdate( DeferrableUpdate $update, $stage = self::POSTSEND ) {
        global $wgCommandLineMode;
        // Special handling for updates pushed while another update is in progress
        if ( self::$executionStack && !( $update instanceof MergeableUpdate ) ) {
            // Get the innermost in-progress update
            end( self::$executionStack );
            $topStackPos = key( self::$executionStack );
            if ( self::$executionStack[$topStackPos]['stage'] >= $stage ) {
                // Put this update into the sub-queue of that in-progress update
                self::push( self::$executionStack[$topStackPos]['subqueue'], $update );
                return;
            }
        }
        if ( $stage === self::PRESEND ) {
            self::push( self::$preSendUpdates, $update );
        } else {
            self::push( self::$postSendUpdates, $update );
        }
        // Try to run the updates now if in CLI mode and no transaction is active.
        // This covers scripts that don't/barely use the DB but make updates to other stores.
        if ( $wgCommandLineMode ) {
            self::tryOpportunisticExecute( 'run' );
        }
    }
    /**
     * Add a callable update. In a lot of cases, we just need a callback/closure,
     * defining a new DeferrableUpdate object is not necessary
     *
     * @see MWCallableUpdate::__construct()
     *
     * @param callable $callable
     * @param int $stage DeferredUpdates constant (PRESEND or POSTSEND) (since 1.27)
     * @param IDatabase|IDatabase[]|null $dbw Abort if this DB is rolled back [optional] (since 1.28)
     */
    public static function addCallableUpdate(
        $callable, $stage = self::POSTSEND, $dbw = null
    ) {
        self::addUpdate( new MWCallableUpdate( $callable, wfGetCaller(), $dbw ), $stage );
    }
    /**
     * Consume the list of deferred updates and execute them
     *
     * 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 an 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.
     *
     * If $stage is self::ALL then the queue of PRESEND updates will be resolved, followed
     * by the queue of POSTSEND updates.
     *
     * @param string $mode Use "enqueue" to use the job queue when possible [Default: "run"]
     * @param int $stage DeferredUpdates constant (PRESEND, POSTSEND, or ALL) (since 1.27)
     */
    public static function doUpdates( $mode = 'run', $stage = self::ALL ) {
        $stageEffective = ( $stage === self::ALL ) ? self::POSTSEND : $stage;
        // Special handling for when an in-progress update triggers this method
        if ( self::$executionStack ) {
            // Run the sub-queue updates for the innermost in-progress update
            end( self::$executionStack );
            $topStackPos = key( self::$executionStack );
            self::handleUpdateQueue(
                self::$executionStack[$topStackPos]['subqueue'],
                $mode,
                $stageEffective
            );
            return;
        }
        // For ALL mode, make sure that any PRESEND updates added along the way get run.
        // Normally, these use the subqueue, but that isn't true for MergeableUpdate items.
        do {
            if ( $stage === self::ALL || $stage === self::PRESEND ) {
                self::handleUpdateQueue( self::$preSendUpdates, $mode, $stageEffective );
            }
            if ( $stage === self::ALL || $stage == self::POSTSEND ) {
                self::handleUpdateQueue( self::$postSendUpdates, $mode, $stageEffective );
            }
        } while ( $stage === self::ALL && self::$preSendUpdates );
    }
    /**
     * @param DeferrableUpdate[] &$queue Combined FIFO update list and MergeableUpdate map
     * @param DeferrableUpdate $update
     */
    private static function push( array &$queue, DeferrableUpdate $update ) {
        if ( $update instanceof MergeableUpdate ) {
            $class = get_class( $update ); // fully-qualified class
            if ( isset( $queue[$class] ) ) {
                /** @var MergeableUpdate $existingUpdate */
                $existingUpdate = $queue[$class];
                '@phan-var MergeableUpdate $existingUpdate';
                $existingUpdate->merge( $update );
                // Move the update to the end to handle things like mergeable purge
                // updates that might depend on the prior updates in the queue running
                unset( $queue[$class] );
                $queue[$class] = $existingUpdate;
            } else {
                $queue[$class] = $update;
            }
        } else {
            $queue[] = $update;
        }
    }
    /**
     * Immediately run or enqueue a list of updates
     *
     * Updates that implement EnqueueableDataUpdate and fail to run will be enqueued
     *
     * @param DeferrableUpdate[] &$queue List of DeferrableUpdate objects
     * @param string $mode Either "run" or "enqueue" (to use the job queue when possible)
     * @param int $stage Class constant (PRESEND, POSTSEND) (since 1.28)
     * @throws ErrorPageError Happens on top-level calls
     * @throws Exception Happens on second-level calls
     */
    protected static function handleUpdateQueue( array &$queue, $mode, $stage ) {
        $services = MediaWikiServices::getInstance();
        $stats = $services->getStatsdDataFactory();
        $lbf = $services->getDBLoadBalancerFactory();
        $logger = LoggerFactory::getInstance( 'DeferredUpdates' );
        $httpMethod = $services->getMainConfig()->get( 'CommandLineMode' )
            ? 'cli'
            : strtolower( RequestContext::getMain()->getRequest()->getMethod() );
        /** @var ErrorPageError $guiEx */
        $guiEx = null;
        /** @var Throwable $exception */
        $exception = null;
        /** @var DeferrableUpdate[] $updates Snapshot of queue */
        $updates = $queue;
        // Keep doing rounds of updates until none get enqueued...
        while ( $updates ) {
            $queue = []; // clear the queue
            // Segregate the queue into one for DataUpdate and one for everything else
            $dataUpdateQueue = [];
            $genericUpdateQueue = [];
            foreach ( $updates as $update ) {
                if ( $update instanceof DataUpdate ) {
                    $dataUpdateQueue[] = $update;
                } else {
                    $genericUpdateQueue[] = $update;
                }
            }
            // Execute all DataUpdate queue followed by the DeferrableUpdate queue...
            foreach ( [ $dataUpdateQueue, $genericUpdateQueue ] as $updateQueue ) {
                foreach ( $updateQueue as $curUpdate ) {
                    // Enqueue the update into the job queue system instead if applicable
                    if ( $mode === 'enqueue' && $curUpdate instanceof EnqueueableDataUpdate ) {
                        self::jobify( $curUpdate, $lbf, $logger, $stats, $httpMethod );
                        continue;
                    }
                    // Otherwise, execute the update, followed by any sub-updates that it spawns
                    $stackEntry = [ 'stage' => $stage, 'update' => $curUpdate, 'subqueue' => [] ];
                    $stackKey = count( self::$executionStack );
                    self::$executionStack[$stackKey] =& $stackEntry;
                    try {
                        $e = self::run( $curUpdate, $lbf, $logger, $stats, $httpMethod );
                        $guiEx = $guiEx ?: ( $e instanceof ErrorPageError ? $e : null );
                        $exception = $exception ?: $e;
                        // Do the subqueue updates for $update until there are none
                        // @phan-suppress-next-line PhanImpossibleConditionInLoop
                        while ( $stackEntry['subqueue'] ) {
                            $duChild = reset( $stackEntry['subqueue'] );
                            $duChildKey = key( $stackEntry['subqueue'] );
                            unset( $stackEntry['subqueue'][$duChildKey] );
                            $e = self::run( $duChild, $lbf, $logger, $stats, $httpMethod );
                            $guiEx = $guiEx ?: ( $e instanceof ErrorPageError ? $e : null );
                            $exception = $exception ?: $e;
                        }
                    } finally {
                        // Make sure we always clean up the context.
                        // Losing updates while rewinding the stack is acceptable,
                        // losing updates that are added later is not.
                        unset( self::$executionStack[$stackKey] );
                    }
                }
            }
            $updates = $queue; // new snapshot of queue (check for new entries)
        }
        // VW-style hack to work around T190178, so we can make sure
        // PageMetaDataUpdater doesn't throw exceptions.
        if ( $exception && defined( 'MW_PHPUNIT_TEST' ) ) {
            throw $exception;
        }
        // Throw the first of any GUI errors as long as the context is HTTP pre-send. However,
        // callers should check permissions *before* enqueueing updates. If the main transaction
        // round actions succeed but some deferred updates fail due to permissions errors then
        // there is a risk that some secondary data was not properly updated.
        if ( $guiEx && $stage === self::PRESEND && !headers_sent() ) {
            throw $guiEx;
        }
    }
    /**
     * Run an update, and, if an error was thrown, catch/log it and fallback to the job queue
     *
     * @param DeferrableUpdate $update
     * @param LBFactory $lbFactory
     * @param LoggerInterface $logger
     * @param StatsdDataFactoryInterface $stats
     * @param string $httpMethod
     * @return Throwable|null
     */
    private static function run(
        DeferrableUpdate $update,
        LBFactory $lbFactory,
        LoggerInterface $logger,
        StatsdDataFactoryInterface $stats,
        $httpMethod
    ) : ?Throwable {
        $suffix = ( $update instanceof DeferrableCallback ) ? "_{$update->getOrigin()}" : '';
        $type = get_class( $update ) . $suffix;
        $stats->increment( "deferred_updates.$httpMethod.$type" );
        $updateId = spl_object_id( $update );
        $logger->debug( __METHOD__ . ": started $type #$updateId" );
        $e = null;
        try {
            self::attemptUpdate( $update, $lbFactory );
            return null;
        } catch ( Throwable $e ) {
        } finally {
            $logger->debug( __METHOD__ . ": ended $type #$updateId" );
        }
        MWExceptionHandler::logException( $e );
        $logger->error(
            "Deferred update '{deferred_type}' failed to run.",
            [
                'deferred_type' => $type,
                'exception' => $e,
            ]
        );
        $lbFactory->rollbackMasterChanges( __METHOD__ );
        // Try to push the update as a job so it can run later if possible
        if ( $update instanceof EnqueueableDataUpdate ) {
            $jobEx = null;
            try {
                $spec = $update->getAsJobSpecification();
                JobQueueGroup::singleton( $spec['domain'] )->push( $spec['job'] );
                return $e;
            } catch ( Throwable $jobEx ) {
            }
            MWExceptionHandler::logException( $jobEx );
            $logger->error(
                "Deferred update '{deferred_type}' failed to enqueue as a job.",
                [
                    'deferred_type' => $type,
                    'exception' => $jobEx,
                ]
            );
            $lbFactory->rollbackMasterChanges( __METHOD__ );
        }
        return $e;
    }
    /**
     * Push a update into the job queue system and catch/log any exceptions
     *
     * @param EnqueueableDataUpdate $update
     * @param LBFactory $lbFactory
     * @param LoggerInterface $logger
     * @param StatsdDataFactoryInterface $stats
     * @param string $httpMethod
     */
    private static function jobify(
        EnqueueableDataUpdate $update,
        LBFactory $lbFactory,
        LoggerInterface $logger,
        StatsdDataFactoryInterface $stats,
        $httpMethod
    ) {
        $type = get_class( $update );
        $stats->increment( "deferred_updates.$httpMethod.$type" );
        $jobEx = null;
        try {
            $spec = $update->getAsJobSpecification();
            JobQueueGroup::singleton( $spec['domain'] )->push( $spec['job'] );
            return;
        } catch ( Throwable $jobEx ) {
        }
        MWExceptionHandler::logException( $jobEx );
        $logger->error(
            "Deferred update '$type' failed to enqueue as a job.",
            [
                'deferred_type' => $type,
                'exception' => $jobEx,
            ]
        );
        $lbFactory->rollbackMasterChanges( __METHOD__ );
    }
    /**
     * 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.
     *
     * @param DeferrableUpdate $update
     * @param ILBFactory $lbFactory
     * @since 1.34
     */
    public static function attemptUpdate( DeferrableUpdate $update, ILBFactory $lbFactory ) {
        $ticket = $lbFactory->getEmptyTransactionTicket( __METHOD__ );
        if ( !$ticket || $lbFactory->hasTransactionRound() ) {
            throw new DBTransactionError( null, "A database transaction round is pending." );
        }
        if ( $update instanceof DataUpdate ) {
            $update->setTransactionTicket( $ticket );
        }
        // Designate $update::doUpdate() as the write round owner
        $fnameTrxOwner = ( $update instanceof DeferrableCallback )
            ? $update->getOrigin()
            : get_class( $update ) . '::doUpdate';
        // Determine whether the write round will be explicit or implicit
        $useExplicitTrxRound = !(
            $update instanceof TransactionRoundAwareUpdate &&
            $update->getTransactionRoundRequirement() == $update::TRX_ROUND_ABSENT
        );
        // Flush any pending changes left over from an implicit transaction round
        if ( $useExplicitTrxRound ) {
            $lbFactory->beginMasterChanges( $fnameTrxOwner ); // new explicit round
        } else {
            $lbFactory->commitMasterChanges( $fnameTrxOwner ); // new implicit round
        }
        // Run the update after any stale master view snapshots have been flushed
        $update->doUpdate();
        // Commit any pending changes from the explicit or implicit transaction round
        $lbFactory->commitMasterChanges( $fnameTrxOwner );
    }
    /**
     * 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
     * updates might be enqueued as jobs to be executed later.
     *
     * @param string $mode Use "enqueue" to use the job queue when possible
     * @return bool Whether updates were allowed to run
     * @since 1.28
     */
    public static function tryOpportunisticExecute( $mode = 'run' ) {
        // An update is already in progress
        if ( self::$executionStack ) {
            return false;
        }
        // Avoiding running updates without them having outer scope
        if ( !self::areDatabaseTransactionsActive() ) {
            self::doUpdates( $mode );
            return true;
        }
        if ( self::pendingUpdatesCount() >= self::BIG_QUEUE_SIZE ) {
            // If we cannot run the updates with outer transaction context, try to
            // at least enqueue all the updates that support queueing to job queue
            self::$preSendUpdates = self::enqueueUpdates( self::$preSendUpdates );
            self::$postSendUpdates = self::enqueueUpdates( self::$postSendUpdates );
        }
        return !self::pendingUpdatesCount();
    }
    /**
     * Enqueue a job for each EnqueueableDataUpdate item and return the other items
     *
     * @param DeferrableUpdate[] $updates A list of deferred update instances
     * @return DeferrableUpdate[] Remaining updates that do not support being queued
     */
    private static function enqueueUpdates( array $updates ) {
        $remaining = [];
        foreach ( $updates as $update ) {
            if ( $update instanceof EnqueueableDataUpdate ) {
                $spec = $update->getAsJobSpecification();
                $domain = $spec['domain'] ?? $spec['wiki'];
                JobQueueGroup::singleton( $domain )->push( $spec['job'] );
            } else {
                $remaining[] = $update;
            }
        }
        return $remaining;
    }
    /**
     * Get the number of currently enqueued updates in the top-queues
     *
     * Calling this while an update is in-progress produces undefined results
     *
     * @return int
     * @since 1.28
     */
    public static function pendingUpdatesCount() {
        if ( self::$executionStack ) {
            throw new LogicException( "Called during execution of a DeferrableUpdate" );
        }
        return count( self::$preSendUpdates ) + count( self::$postSendUpdates );
    }
    /**
     * Get the list of pending updates in the top-queues
     *
     * Calling this while an update is in-progress produces undefined results
     *
     * This method should only be used for unit tests
     *
     * @param int $stage DeferredUpdates constant (PRESEND, POSTSEND, or ALL)
     * @return DeferrableUpdate[]
     * @since 1.29
     */
    public static function getPendingUpdates( $stage = self::ALL ) {
        $updates = [];
        if ( $stage === self::ALL || $stage === self::PRESEND ) {
            $updates = array_merge( $updates, self::$preSendUpdates );
        }
        if ( $stage === self::ALL || $stage === self::POSTSEND ) {
            $updates = array_merge( $updates, self::$postSendUpdates );
        }
        return $updates;
    }
    /**
     * Clear all pending updates without performing them
     *
     * Calling this while an update is in-progress produces undefined results
     *
     * This method should only be used for unit tests
     */
    public static function clearPendingUpdates() {
        self::$preSendUpdates = [];
        self::$postSendUpdates = [];
    }
    /**
     * @return bool If a transaction round is active or connection is not ready for commit()
     */
    private static function areDatabaseTransactionsActive() {
        $lbFactory = MediaWikiServices::getInstance()->getDBLoadBalancerFactory();
        if ( $lbFactory->hasTransactionRound() || !$lbFactory->isReadyForRoundOperations() ) {
            return true;
        }
        $connsBusy = false;
        $lbFactory->forEachLB( function ( LoadBalancer $lb ) use ( &$connsBusy ) {
            $lb->forEachOpenMasterConnection( function ( IDatabase $conn ) use ( &$connsBusy ) {
                if ( $conn->writesOrCallbacksPending() || $conn->explicitTrxActive() ) {
                    $connsBusy = true;
                }
            } );
        } );
        return $connsBusy;
    }
}