includes/deferred/DeferredUpdates.php

   1 <?php
   2 /**
   3  * Interface and manager for deferred updates.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  */
  22
  23 /**
  24  * Interface that deferrable updates should implement. Basically required so we
  25  * can validate input on DeferredUpdates::addUpdate()
  26  *
  27  * @since 1.19
  28  */
  29 interface DeferrableUpdate {
  30         /**
  31          * Perform the actual work
  32          */
  33         function doUpdate();
  34 }
  35
  36 /**
  37  * Class for managing the deferred updates
  38  *
  39  * Deferred updates can be run at the end of the request,
  40  * after the HTTP response has been sent. In CLI mode, updates
  41  * are only deferred until there is no local master DB transaction.
  42  * When updates are deferred, they go into a simple FIFO queue.
  43  *
  44  * @since 1.19
  45  */
  46 class DeferredUpdates {
  47         /** @var DeferrableUpdate[] Updates to be deferred until the end of the request */
  48         private static $updates = array();
  49         /** @var bool Defer updates fully even in CLI mode */
  50         private static $forceDeferral = false;
  51
  52         /**
  53          * Add an update to the deferred list
  54          * @param DeferrableUpdate $update Some object that implements doUpdate()
  55          */
  56         public static function addUpdate( DeferrableUpdate $update ) {
  57                 global $wgCommandLineMode;
  58
  59                 array_push( self::$updates, $update );
  60                 if ( self::$forceDeferral ) {
  61                         return;
  62                 }
  63
  64                 // CLI scripts may forget to periodically flush these updates,
  65                 // so try to handle that rather than OOMing and losing them.
  66                 // Try to run the updates as soon as there is no local transaction.
  67                 static $waitingOnTrx = false; // de-duplicate callback
  68                 if ( $wgCommandLineMode && !$waitingOnTrx ) {
  69                         $lb = wfGetLB();
  70                         $dbw = $lb->getAnyOpenConnection( $lb->getWriterIndex() );
  71                         // Do the update as soon as there is no transaction
  72                         if ( $dbw && $dbw->trxLevel() ) {
  73                                 $waitingOnTrx = true;
  74                                 $dbw->onTransactionIdle( function() use ( &$waitingOnTrx ) {
  75                                         DeferredUpdates::doUpdates();
  76                                         $waitingOnTrx = false;
  77                                 } );
  78                         } else {
  79                                 self::doUpdates();
  80                         }
  81                 }
  82         }
  83
  84         /**
  85          * Add a callable update.  In a lot of cases, we just need a callback/closure,
  86          * defining a new DeferrableUpdate object is not necessary
  87          * @see MWCallableUpdate::__construct()
  88          * @param callable $callable
  89          */
  90         public static function addCallableUpdate( $callable ) {
  91                 self::addUpdate( new MWCallableUpdate( $callable ) );
  92         }
  93
  94         /**
  95          * Do any deferred updates and clear the list
  96          *
  97          * @param string $mode Use "enqueue" to use the job queue when possible [Default: run]
  98          *   prevent lock contention
  99          * @param string $oldMode Unused
 100          */
 101         public static function doUpdates( $mode = 'run', $oldMode = '' ) {
 102                 // B/C for ( $commit, $mode ) args
 103                 $mode = $oldMode ?: $mode;
 104                 if ( $mode === 'commit' ) {
 105                         $mode = 'run';
 106                 }
 107
 108                 $updates = self::$updates;
 109
 110                 while ( count( $updates ) ) {
 111                         self::clearPendingUpdates();
 112                         /** @var DataUpdate[] $dataUpdates */
 113                         $dataUpdates = array();
 114                         /** @var DeferrableUpdate[] $otherUpdates */
 115                         $otherUpdates = array();
 116                         foreach ( $updates as $update ) {
 117                                 if ( $update instanceof DataUpdate ) {
 118                                         $dataUpdates[] = $update;
 119                                 } else {
 120                                         $otherUpdates[] = $update;
 121                                 }
 122                         }
 123
 124                         // Delegate DataUpdate execution to the DataUpdate class
 125                         DataUpdate::runUpdates( $dataUpdates, $mode );
 126                         // Execute the non-DataUpdate tasks
 127                         foreach ( $otherUpdates as $update ) {
 128                                 try {
 129                                         $update->doUpdate();
 130                                         wfGetLBFactory()->commitMasterChanges();
 131                                 } catch ( Exception $e ) {
 132                                         // We don't want exceptions thrown during deferred updates to
 133                                         // be reported to the user since the output is already sent.
 134                                         // Instead we just log them.
 135                                         if ( !$e instanceof ErrorPageError ) {
 136                                                 MWExceptionHandler::logException( $e );
 137                                         }
 138                                 }
 139                         }
 140
 141                         $updates = self::$updates;
 142                 }
 143         }
 144
 145         /**
 146          * Clear all pending updates without performing them. Generally, you don't
 147          * want or need to call this. Unit tests need it though.
 148          */
 149         public static function clearPendingUpdates() {
 150                 self::$updates = array();
 151         }
 152
 153         /**
 154          * @note This method is intended for testing purposes
 155          * @param bool $value Whether to *always* defer updates, even in CLI mode
 156          * @since 1.27
 157          */
 158         public static function forceDeferral( $value ) {
 159                 self::$forceDeferral = $value;
 160         }
 161 }