DeferredUpdates.php

Go to the documentation of this file.

<?php
use MediaWiki\MediaWikiServices;

class DeferredUpdates {
    private static $preSendUpdates = [];
    private static $postSendUpdates = [];
    private static $immediateMode = false;

    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;

        // This is a sub-DeferredUpdate, run it right after its parent update
        if ( self::$executeContext && self::$executeContext['stage'] >= $stage ) {
            self::$executeContext['subqueue'][] = $update;
            return;
        }

        if ( $stage === self::PRESEND ) {
            self::push( self::$preSendUpdates, $update );
        } else {
            self::push( self::$postSendUpdates, $update );
        }

        if ( self::$immediateMode ) {
            // No more explicit doUpdates() calls will happen, so run this now
            self::doUpdates( 'run' );
            return;
        }

        // 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, IDatabase $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;

        if ( $stage === self::ALL || $stage === self::PRESEND ) {
            self::execute( self::$preSendUpdates, $mode, $stageEffective );
        }

        if ( $stage === self::ALL || $stage == self::POSTSEND ) {
            self::execute( self::$postSendUpdates, $mode, $stageEffective );
        }
    }

    public static function setImmediateMode( $value ) {
        self::$immediateMode = (bool)$value;
    }

    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];
                $existingUpdate->merge( $update );
            } else {
                $queue[$class] = $update;
            }
        } else {
            $queue[] = $update;
        }
    }

    protected static function execute( array &$queue, $mode, $stage ) {
        $services = MediaWikiServices::getInstance();
        $stats = $services->getStatsdDataFactory();
        $lbFactory = $services->getDBLoadBalancerFactory();
        $method = RequestContext::getMain()->getRequest()->getMethod();

        $ticket = $lbFactory->getEmptyTransactionTicket( __METHOD__ );

        $reportableError = null;
        $updates = $queue;

        // Keep doing rounds of updates until none get enqueued...
        while ( $updates ) {
            $queue = []; // clear the queue

            if ( $mode === 'enqueue' ) {
                try {
                    // Push enqueuable updates to the job queue and get the rest
                    $updates = self::enqueueUpdates( $updates );
                } catch ( Exception $e ) {
                    // Let other updates have a chance to run if this failed
                    MWExceptionHandler::rollbackMasterChangesAndLog( $e );
                }
            }

            // Order will be DataUpdate followed by generic DeferrableUpdate tasks
            $updatesByType = [ 'data' => [], 'generic' => [] ];
            foreach ( $updates as $du ) {
                if ( $du instanceof DataUpdate ) {
                    $du->setTransactionTicket( $ticket );
                    $updatesByType['data'][] = $du;
                } else {
                    $updatesByType['generic'][] = $du;
                }

                $name = ( $du instanceof DeferrableCallback )
                    ? get_class( $du ) . '-' . $du->getOrigin()
                    : get_class( $du );
                $stats->increment( 'deferred_updates.' . $method . '.' . $name );
            }

            // Execute all remaining tasks...
            foreach ( $updatesByType as $updatesForType ) {
                foreach ( $updatesForType as $update ) {
                    self::$executeContext = [
                        'update' => $update,
                        'stage' => $stage,
                        'subqueue' => []
                    ];
                    $guiError = self::runUpdate( $update, $lbFactory, $stage );
                    $reportableError = $reportableError ?: $guiError;
                    // Do the subqueue updates for $update until there are none
                    while ( self::$executeContext['subqueue'] ) {
                        $subUpdate = reset( self::$executeContext['subqueue'] );
                        $firstKey = key( self::$executeContext['subqueue'] );
                        unset( self::$executeContext['subqueue'][$firstKey] );

                        if ( $subUpdate instanceof DataUpdate ) {
                            $subUpdate->setTransactionTicket( $ticket );
                        }

                        $guiError = self::runUpdate( $subUpdate, $lbFactory, $stage );
                        $reportableError = $reportableError ?: $guiError;
                    }
                    self::$executeContext = null;
                }
            }

            $updates = $queue; // new snapshot of queue (check for new entries)
        }

        if ( $reportableError ) {
            throw $reportableError; // throw the first of any GUI errors
        }
    }

    private static function runUpdate( DeferrableUpdate $update, LBFactory $lbFactory, $stage ) {
        $guiError = null;
        try {
            $fnameTrxOwner = get_class( $update ) . '::doUpdate';
            $lbFactory->beginMasterChanges( $fnameTrxOwner );
            $update->doUpdate();
            $lbFactory->commitMasterChanges( $fnameTrxOwner );
        } catch ( Exception $e ) {
            // Reporting GUI exceptions does not work post-send
            if ( $e instanceof ErrorPageError && $stage === self::PRESEND ) {
                $guiError = $e;
            }
            MWExceptionHandler::rollbackMasterChangesAndLog( $e );
        }

        return $guiError;
    }

    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::getBusyDbConnections() ) {
            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();
                JobQueueGroup::singleton( $spec['wiki'] )->push( $spec['job'] );
            } else {
                $remaining[] = $update;
            }
        }

        return $remaining;
    }

    public static function pendingUpdatesCount() {
        return count( self::$preSendUpdates ) + count( self::$postSendUpdates );
    }

    public static function clearPendingUpdates() {
        self::$preSendUpdates = [];
        self::$postSendUpdates = [];
    }

    private static function getBusyDbConnections() {
        $connsBusy = [];

        $lbFactory = MediaWikiServices::getInstance()->getDBLoadBalancerFactory();
        $lbFactory->forEachLB( function ( LoadBalancer $lb ) use ( &$connsBusy ) {
            $lb->forEachOpenMasterConnection( function ( IDatabase $conn ) use ( &$connsBusy ) {
                if ( $conn->writesOrCallbacksPending() || $conn->explicitTrxActive() ) {
                    $connsBusy[] = $conn;
                }
            } );
        } );

        return $connsBusy;
    }
}