DeferredUpdates.php

Go to the documentation of this file.

<?php
use Liuggio\StatsdClient\Factory\StatsdDataFactoryInterface;
use MediaWiki\Logger\LoggerFactory;
use Psr\Log\LoggerInterface;
use Wikimedia\Rdbms\IDatabase;
use MediaWiki\MediaWikiServices;
use Wikimedia\Rdbms\LBFactory;
use Wikimedia\Rdbms\ILBFactory;
use Wikimedia\Rdbms\LoadBalancer;
use Wikimedia\Rdbms\DBTransactionError;
 
class DeferredUpdates {
    private static $preSendUpdates = [];
    private static $postSendUpdates = [];
 
    const ALL = 0; // all updates; in web requests, use only after flushing the output buffer
    const PRESEND = 1; // for updates that should run before flushing output buffer
    const POSTSEND = 2; // for updates that should run after flushing output buffer
 
    const BIG_QUEUE_SIZE = 100;
 
    private static $executeContext;
 
    public static function addUpdate( DeferrableUpdate $update, $stage = self::POSTSEND ) {
        global $wgCommandLineMode;
 
        if (
            self::$executeContext &&
            self::$executeContext['stage'] >= $stage &&
            !( $update instanceof MergeableUpdate )
        ) {
            // This is a sub-DeferredUpdate; run it right after its parent update.
            // Also, while post-send updates are running, push any "pre-send" jobs to the
            // active post-send queue to make sure they get run this round (or at all).
            self::$executeContext['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' );
        }
    }
 
    public static function addCallableUpdate(
        $callable, $stage = self::POSTSEND, $dbw = null
    ) {
        self::addUpdate( new MWCallableUpdate( $callable, wfGetCaller(), $dbw ), $stage );
    }
 
    public static function doUpdates( $mode = 'run', $stage = self::ALL ) {
        $stageEffective = ( $stage === self::ALL ) ? self::POSTSEND : $stage;
        // 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 );
    }
 
    private static function push( array &$queue, DeferrableUpdate $update ) {
        if ( $update instanceof MergeableUpdate ) {
            $class = get_class( $update ); // fully-qualified class
            if ( isset( $queue[$class] ) ) {
                $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;
        }
    }
 
    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() );
 
        $guiEx = null;
        $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 $du ) {
                    // Enqueue the task into the job queue system instead if applicable
                    if ( $mode === 'enqueue' && $du instanceof EnqueueableDataUpdate ) {
                        self::jobify( $du, $lbf, $logger, $stats, $httpMethod );
                        continue;
                    }
                    // Otherwise, execute the task and any subtasks that it spawns
                    self::$executeContext = [ 'stage' => $stage, 'subqueue' => [] ];
                    try {
                        $e = self::run( $du, $lbf, $logger, $stats, $httpMethod );
                        $guiEx = $guiEx ?: ( $e instanceof ErrorPageError ? $e : null );
                        // Do the subqueue updates for $update until there are none
                        while ( self::$executeContext['subqueue'] ) {
                            $duChild = reset( self::$executeContext['subqueue'] );
                            $firstKey = key( self::$executeContext['subqueue'] );
                            unset( self::$executeContext['subqueue'][$firstKey] );
 
                            $e = self::run( $duChild, $lbf, $logger, $stats, $httpMethod );
                            $guiEx = $guiEx ?: ( $e instanceof ErrorPageError ? $e : null );
                        }
                    } 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.
                        self::$executeContext = null;
                    }
                }
            }
 
            $updates = $queue; // new snapshot of queue (check for new entries)
        }
 
        // 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;
        }
    }
 
    private static function run(
        DeferrableUpdate $update,
        LBFactory $lbFactory,
        LoggerInterface $logger,
        StatsdDataFactoryInterface $stats,
        $httpMethod
    ) {
        $name = get_class( $update );
        $suffix = ( $update instanceof DeferrableCallback ) ? "_{$update->getOrigin()}" : '';
        $stats->increment( "deferred_updates.$httpMethod.{$name}{$suffix}" );
 
        $e = null;
        try {
            self::attemptUpdate( $update, $lbFactory );
        } catch ( Exception $e ) {
        } catch ( Throwable $e ) {
        }
 
        if ( $e ) {
            $logger->error(
                "Deferred update {type} failed: {message}",
                [
                    'type' => $name . $suffix,
                    'message' => $e->getMessage(),
                    'trace' => $e->getTraceAsString()
                ]
            );
            $lbFactory->rollbackMasterChanges( __METHOD__ );
            // VW-style hack to work around T190178, so we can make sure
            // PageMetaDataUpdater doesn't throw exceptions.
            if ( defined( 'MW_PHPUNIT_TEST' ) ) {
                throw $e;
            }
        }
 
        return $e;
    }
 
    private static function jobify(
        EnqueueableDataUpdate $update,
        LBFactory $lbFactory,
        LoggerInterface $logger,
        StatsdDataFactoryInterface $stats,
        $httpMethod
    ) {
        $stats->increment( "deferred_updates.$httpMethod." . get_class( $update ) );
 
        $e = null;
        try {
            $spec = $update->getAsJobSpecification();
            JobQueueGroup::singleton( $spec['domain'] ?? $spec['wiki'] )->push( $spec['job'] );
        } catch ( Exception $e ) {
        } catch ( Throwable $e ) {
        }
 
        if ( $e ) {
            $logger->error(
                "Job insertion of deferred update {type} failed: {message}",
                [
                    'type' => get_class( $update ),
                    'message' => $e->getMessage(),
                    'trace' => $e->getTraceAsString()
                ]
            );
            $lbFactory->rollbackMasterChanges( __METHOD__ );
        }
    }
 
    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 );
    }
 
    public static function tryOpportunisticExecute( $mode = 'run' ) {
        // execute() loop is already running
        if ( self::$executeContext ) {
            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();
    }
 
    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;
    }
 
    public static function pendingUpdatesCount() {
        return count( self::$preSendUpdates ) + count( self::$postSendUpdates );
    }
 
    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;
    }
 
    public static function clearPendingUpdates() {
        self::$preSendUpdates = [];
        self::$postSendUpdates = [];
    }
 
    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;
    }
}