DeferredUpdatesScope.php

Go to the documentation of this file.

<?php
class DeferredUpdatesScope {
    private $parentScope;
    private $activeUpdate;
    private $activeStage;
    private $queueByStage;
 
    private function __construct(
        $activeStage,
        ?DeferrableUpdate $update,
        ?DeferredUpdatesScope $parentScope
    ) {
        $this->activeStage = $activeStage;
        $this->activeUpdate = $update;
        $this->parentScope = $parentScope;
        $this->queueByStage = array_fill_keys( DeferredUpdates::STAGES, [] );
    }
 
    public static function newRootScope() {
        return new self( null, null, null );
    }
 
    public static function newChildScope(
        $activeStage,
        DeferrableUpdate $update,
        DeferredUpdatesScope $parentScope
    ) {
        return new self( $activeStage, $update, $parentScope );
    }
 
    public function getActiveUpdate() {
        return $this->activeUpdate;
    }
 
    public function addUpdate( DeferrableUpdate $update, $stage ) {
        // Handle the case where the specified stage must have already passed
        $stageEffective = max( $stage, $this->activeStage );
 
        $queue =& $this->queueByStage[$stageEffective];
 
        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;
        }
    }
 
    public function pendingUpdatesCount() {
        return array_sum( array_map( 'count', $this->queueByStage ) );
    }
 
    public function getPendingUpdates( $stage ) {
        $matchingQueues = [];
        foreach ( $this->queueByStage as $queueStage => $queue ) {
            if ( $stage === DeferredUpdates::ALL || $stage === $queueStage ) {
                $matchingQueues[] = $queue;
            }
        }
 
        return array_merge( ...$matchingQueues );
    }
 
    public function clearPendingUpdates() {
        $this->queueByStage = array_fill_keys( array_keys( $this->queueByStage ), [] );
    }
 
    public function consumeMatchingUpdates( $stage, $class, callable $callback ) {
        // T268840: defensively claim the pending updates in case of recursion
        $claimedUpdates = [];
        foreach ( $this->queueByStage as $queueStage => $queue ) {
            if ( $stage === DeferredUpdates::ALL || $stage === $queueStage ) {
                foreach ( $queue as $k => $update ) {
                    if ( $update instanceof $class ) {
                        $claimedUpdates[] = $update;
                        unset( $this->queueByStage[$queueStage][$k] );
                    }
                }
            }
        }
        // Execute the callback for each update
        foreach ( $claimedUpdates as $update ) {
            $callback( $update );
        }
    }
 
    public function processUpdates( $stage, callable $callback ) {
        if ( $stage === DeferredUpdates::ALL ) {
            // Do everything, all the way to the last "defer until" stage
            $activeStage = DeferredUpdates::STAGES[count( DeferredUpdates::STAGES ) - 1];
        } else {
            // Handle the case where the specified stage must have already passed
            $activeStage = max( $stage, $this->activeStage );
        }
 
        do {
            $processed = $this->upmergeUnreadyUpdates( $activeStage );
            foreach ( range( DeferredUpdates::STAGES[0], $activeStage ) as $queueStage ) {
                $processed += $this->processStageQueue( $queueStage, $activeStage, $callback );
            }
        } while ( $processed > 0 );
    }
 
    private function upmergeUnreadyUpdates( $activeStage ) {
        $reassigned = 0;
 
        if ( !$this->parentScope ) {
            return $reassigned;
        }
 
        foreach ( $this->queueByStage as $queueStage => $queue ) {
            foreach ( $queue as $k => $update ) {
                if ( $update instanceof MergeableUpdate || $queueStage > $activeStage ) {
                    unset( $this->queueByStage[$queueStage][$k] );
                    $this->parentScope->addUpdate( $update, $queueStage );
                    ++$reassigned;
                }
            }
        }
 
        return $reassigned;
    }
 
    private function processStageQueue( $stage, $activeStage, callable $callback ) {
        $processed = 0;
 
        // Defensively claim the pending updates in case of recursion
        $claimedUpdates = $this->queueByStage[$stage];
        $this->queueByStage[$stage] = [];
 
        // Keep doing rounds of updates until none get enqueued...
        while ( $claimedUpdates ) {
            // Segregate the updates into one for DataUpdate and one for everything else.
            // This is done for historical reasons; DataUpdate used to have its own static
            // method for running DataUpdate instances and was called first in DeferredUpdates.
            // Before that, page updater code directly ran that static method.
            // @TODO: remove this logic given the existence of RefreshSecondaryDataUpdate
            $claimedDataUpdates = [];
            $claimedGenericUpdates = [];
            foreach ( $claimedUpdates as $claimedUpdate ) {
                if ( $claimedUpdate instanceof DataUpdate ) {
                    $claimedDataUpdates[] = $claimedUpdate;
                } else {
                    $claimedGenericUpdates[] = $claimedUpdate;
                }
                ++$processed;
            }
 
            // Execute the DataUpdate queue followed by the DeferrableUpdate queue...
            foreach ( $claimedDataUpdates as $claimedDataUpdate ) {
                $callback( $claimedDataUpdate, $activeStage );
            }
            foreach ( $claimedGenericUpdates as $claimedGenericUpdate ) {
                $callback( $claimedGenericUpdate, $activeStage );
            }
 
            // Check for new entries;  defensively claim the pending updates in case of recursion
            $claimedUpdates = $this->queueByStage[$stage];
            $this->queueByStage[$stage] = [];
        }
 
        return $processed;
    }
}