includes/db/ChronologyProtector.php

   1 <?php
   2 /**
   3  * Generator of database load balancing objects.
   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  * @ingroup Database
  22  */
  23
  24 /**
  25  * Class for ensuring a consistent ordering of events as seen by the user, despite replication.
  26  * Kind of like Hawking's [[Chronology Protection Agency]].
  27  */
  28 class ChronologyProtector {
  29         /** @var BagOStuff */
  30         protected $store;
  31
  32         /** @var string Storage key name */
  33         protected $key;
  34         /** @var array Map of (ip: <IP>, agent: <user-agent>) */
  35         protected $client;
  36         /** @var bool Whether to no-op all method calls */
  37         protected $enabled = true;
  38         /** @var bool Whether to check and wait on positions */
  39         protected $wait = true;
  40
  41         /** @var bool Whether the client data was loaded */
  42         protected $initialized = false;
  43         /** @var DBMasterPos[] Map of (DB master name => position) */
  44         protected $startupPositions = array();
  45         /** @var DBMasterPos[] Map of (DB master name => position) */
  46         protected $shutdownPositions = array();
  47
  48         /**
  49          * @param BagOStuff $store
  50          * @param array $client Map of (ip: <IP>, agent: <user-agent>)
  51          * @since 1.27
  52          */
  53         public function __construct( BagOStuff $store, array $client ) {
  54                 $this->store = $store;
  55                 $this->client = $client;
  56                 $this->key = $store->makeGlobalKey(
  57                         'ChronologyProtector',
  58                         md5( $client['ip'] . "\n" . $client['agent'] )
  59                 );
  60         }
  61
  62         /**
  63          * @param bool $enabled Whether to no-op all method calls
  64          * @since 1.27
  65          */
  66         public function setEnabled( $enabled ) {
  67                 $this->enabled = $enabled;
  68         }
  69
  70         /**
  71          * @param bool $enabled Whether to check and wait on positions
  72          * @since 1.27
  73          */
  74         public function setWaitEnabled( $enabled ) {
  75                 $this->wait = $enabled;
  76         }
  77
  78         /**
  79          * Initialise a LoadBalancer to give it appropriate chronology protection.
  80          *
  81          * If the stash has a previous master position recorded, this will try to
  82          * make sure that the next query to a slave of that master will see changes up
  83          * to that position by delaying execution. The delay may timeout and allow stale
  84          * data if no non-lagged slaves are available.
  85          *
  86          * @param LoadBalancer $lb
  87          * @return void
  88          */
  89         public function initLB( LoadBalancer $lb ) {
  90                 if ( !$this->enabled || $lb->getServerCount() <= 1 ) {
  91                         return; // non-replicated setup or disabled
  92                 }
  93
  94                 $this->initPositions();
  95
  96                 $masterName = $lb->getServerName( $lb->getWriterIndex() );
  97                 if ( !empty( $this->startupPositions[$masterName] ) ) {
  98                         $info = $lb->parentInfo();
  99                         $pos = $this->startupPositions[$masterName];
 100                         wfDebugLog( 'replication', __METHOD__ .
 101                                 ": LB '" . $info['id'] . "' waiting for master pos $pos\n" );
 102                         $lb->waitFor( $pos );
 103                 }
 104         }
 105
 106         /**
 107          * Notify the ChronologyProtector that the LoadBalancer is about to shut
 108          * down. Saves replication positions.
 109          *
 110          * @param LoadBalancer $lb
 111          * @return void
 112          */
 113         public function shutdownLB( LoadBalancer $lb ) {
 114                 if ( !$this->enabled || $lb->getServerCount() <= 1 ) {
 115                         return; // non-replicated setup or disabled
 116                 }
 117
 118                 $info = $lb->parentInfo();
 119                 $masterName = $lb->getServerName( $lb->getWriterIndex() );
 120
 121                 // Only save the position if writes have been done on the connection
 122                 $db = $lb->getAnyOpenConnection( $lb->getWriterIndex() );
 123                 if ( !$db || !$db->doneWrites() ) {
 124                         wfDebugLog( 'replication', __METHOD__ . ": LB {$info['id']}, no writes done\n" );
 125
 126                         return; // nothing to do
 127                 }
 128
 129                 $pos = $db->getMasterPos();
 130                 wfDebugLog( 'replication', __METHOD__ . ": LB {$info['id']} has master pos $pos\n" );
 131                 $this->shutdownPositions[$masterName] = $pos;
 132         }
 133
 134         /**
 135          * Notify the ChronologyProtector that the LBFactory is done calling shutdownLB() for now.
 136          * May commit chronology data to persistent storage.
 137          *
 138          * @return array Empty on success; returns the (db name => position) map on failure
 139          */
 140         public function shutdown() {
 141                 if ( !$this->enabled || !count( $this->shutdownPositions ) ) {
 142                         return true; // nothing to save
 143                 }
 144
 145                 wfDebugLog( 'replication',
 146                         __METHOD__ . ": saving master pos for " .
 147                         implode( ', ', array_keys( $this->shutdownPositions ) ) . "\n"
 148                 );
 149
 150                 $shutdownPositions = $this->shutdownPositions;
 151                 $ok = $this->store->merge(
 152                         $this->key,
 153                         function ( $store, $key, $curValue ) use ( $shutdownPositions ) {
 154                                 /** @var $curPositions DBMasterPos[] */
 155                                 if ( $curValue === false ) {
 156                                         $curPositions = $shutdownPositions;
 157                                 } else {
 158                                         $curPositions = $curValue['positions'];
 159                                         // Use the newest positions for each DB master
 160                                         foreach ( $shutdownPositions as $db => $pos ) {
 161                                                 if ( !isset( $curPositions[$db] )
 162                                                         || $pos->asOfTime() > $curPositions[$db]->asOfTime()
 163                                                 ) {
 164                                                         $curPositions[$db] = $pos;
 165                                                 }
 166                                         }
 167                                 }
 168
 169                                 return array( 'positions' => $curPositions );
 170                         },
 171                         BagOStuff::TTL_MINUTE,
 172                         10,
 173                         BagOStuff::WRITE_SYNC // visible in all datacenters
 174                 );
 175
 176                 if ( !$ok ) {
 177                         // Raced out too many times or stash is down
 178                         wfDebugLog( 'replication',
 179                                 __METHOD__ . ": failed to save master pos for " .
 180                                 implode( ', ', array_keys( $this->shutdownPositions ) ) . "\n"
 181                         );
 182
 183                         return $this->shutdownPositions;
 184                 }
 185
 186                 return array();
 187         }
 188
 189         /**
 190          * Load in previous master positions for the client
 191          */
 192         protected function initPositions() {
 193                 if ( $this->initialized ) {
 194                         return;
 195                 }
 196
 197                 $this->initialized = true;
 198                 if ( $this->wait ) {
 199                         $data = $this->store->get( $this->key );
 200                         $this->startupPositions = $data ? $data['positions'] : array();
 201
 202                         wfDebugLog( 'replication', __METHOD__ . ": key is {$this->key} (read)\n" );
 203                 } else {
 204                         $this->startupPositions = array();
 205
 206                         wfDebugLog( 'replication', __METHOD__ . ": key is {$this->key} (unread)\n" );
 207                 }
 208         }
 209 }