MediaWiki  REL1_23
BagOStuff.php
Go to the documentation of this file.
00001 <?php
00043 abstract class BagOStuff {
00044     private $debugMode = false;
00045 
00046     protected $lastError = self::ERR_NONE;
00047 
00049     const ERR_NONE        = 0; // no error
00050     const ERR_NO_RESPONSE = 1; // no response
00051     const ERR_UNREACHABLE = 2; // can't connect
00052     const ERR_UNEXPECTED  = 3; // response gave some error
00053 
00057     public function setDebug( $bool ) {
00058         $this->debugMode = $bool;
00059     }
00060 
00061     /* *** THE GUTS OF THE OPERATION *** */
00062     /* Override these with functional things in subclasses */
00063 
00070     abstract public function get( $key, &$casToken = null );
00071 
00079     abstract public function set( $key, $value, $exptime = 0 );
00080 
00089     abstract public function cas( $casToken, $key, $value, $exptime = 0 );
00090 
00097     abstract public function delete( $key, $time = 0 );
00098 
00110     public function merge( $key, closure $callback, $exptime = 0, $attempts = 10 ) {
00111         return $this->mergeViaCas( $key, $callback, $exptime, $attempts );
00112     }
00113 
00123     protected function mergeViaCas( $key, closure $callback, $exptime = 0, $attempts = 10 ) {
00124         do {
00125             $casToken = null; // passed by reference
00126             $currentValue = $this->get( $key, $casToken ); // get the old value
00127             $value = $callback( $this, $key, $currentValue ); // derive the new value
00128 
00129             if ( $value === false ) {
00130                 $success = true; // do nothing
00131             } elseif ( $currentValue === false ) {
00132                 // Try to create the key, failing if it gets created in the meantime
00133                 $success = $this->add( $key, $value, $exptime );
00134             } else {
00135                 // Try to update the key, failing if it gets changed in the meantime
00136                 $success = $this->cas( $casToken, $key, $value, $exptime );
00137             }
00138         } while ( !$success && --$attempts );
00139 
00140         return $success;
00141     }
00142 
00152     protected function mergeViaLock( $key, closure $callback, $exptime = 0, $attempts = 10 ) {
00153         if ( !$this->lock( $key, 6 ) ) {
00154             return false;
00155         }
00156 
00157         $currentValue = $this->get( $key ); // get the old value
00158         $value = $callback( $this, $key, $currentValue ); // derive the new value
00159 
00160         if ( $value === false ) {
00161             $success = true; // do nothing
00162         } else {
00163             $success = $this->set( $key, $value, $exptime ); // set the new value
00164         }
00165 
00166         if ( !$this->unlock( $key ) ) {
00167             // this should never happen
00168             trigger_error( "Could not release lock for key '$key'." );
00169         }
00170 
00171         return $success;
00172     }
00173 
00179     public function lock( $key, $timeout = 6 ) {
00180         $this->clearLastError();
00181         $timestamp = microtime( true ); // starting UNIX timestamp
00182         if ( $this->add( "{$key}:lock", 1, $timeout ) ) {
00183             return true;
00184         } elseif ( $this->getLastError() ) {
00185             return false;
00186         }
00187 
00188         $uRTT = ceil( 1e6 * ( microtime( true ) - $timestamp ) ); // estimate RTT (us)
00189         $sleep = 2 * $uRTT; // rough time to do get()+set()
00190 
00191         $locked = false; // lock acquired
00192         $attempts = 0; // failed attempts
00193         do {
00194             if ( ++$attempts >= 3 && $sleep <= 1e6 ) {
00195                 // Exponentially back off after failed attempts to avoid network spam.
00196                 // About 2*$uRTT*(2^n-1) us of "sleep" happen for the next n attempts.
00197                 $sleep *= 2;
00198             }
00199             usleep( $sleep ); // back off
00200             $this->clearLastError();
00201             $locked = $this->add( "{$key}:lock", 1, $timeout );
00202             if ( $this->getLastError() ) {
00203                 return false;
00204             }
00205         } while ( !$locked );
00206 
00207         return $locked;
00208     }
00209 
00214     public function unlock( $key ) {
00215         return $this->delete( "{$key}:lock" );
00216     }
00217 
00227     public function deleteObjectsExpiringBefore( $date, $progressCallback = false ) {
00228         // stub
00229         return false;
00230     }
00231 
00232     /* *** Emulated functions *** */
00233 
00239     public function getMulti( array $keys ) {
00240         $res = array();
00241         foreach ( $keys as $key ) {
00242             $val = $this->get( $key );
00243             if ( $val !== false ) {
00244                 $res[$key] = $val;
00245             }
00246         }
00247         return $res;
00248     }
00249 
00256     public function add( $key, $value, $exptime = 0 ) {
00257         if ( $this->get( $key ) === false ) {
00258             return $this->set( $key, $value, $exptime );
00259         }
00260         return false; // key already set
00261     }
00262 
00270     public function replace( $key, $value, $exptime = 0 ) {
00271         wfDeprecated( __METHOD__, '1.23' );
00272         if ( $this->get( $key ) !== false ) {
00273             return $this->set( $key, $value, $exptime );
00274         }
00275         return false; // key not already set
00276     }
00277 
00284     public function incr( $key, $value = 1 ) {
00285         if ( !$this->lock( $key ) ) {
00286             return false;
00287         }
00288         $n = $this->get( $key );
00289         if ( $this->isInteger( $n ) ) { // key exists?
00290             $n += intval( $value );
00291             $this->set( $key, max( 0, $n ) ); // exptime?
00292         } else {
00293             $n = false;
00294         }
00295         $this->unlock( $key );
00296 
00297         return $n;
00298     }
00299 
00306     public function decr( $key, $value = 1 ) {
00307         return $this->incr( $key, - $value );
00308     }
00309 
00315     public function getLastError() {
00316         return $this->lastError;
00317     }
00318 
00323     public function clearLastError() {
00324         $this->lastError = self::ERR_NONE;
00325     }
00326 
00332     protected function setLastError( $err ) {
00333         $this->lastError = $err;
00334     }
00335 
00339     public function debug( $text ) {
00340         if ( $this->debugMode ) {
00341             $class = get_class( $this );
00342             wfDebug( "$class debug: $text\n" );
00343         }
00344     }
00345 
00351     protected function convertExpiry( $exptime ) {
00352         if ( ( $exptime != 0 ) && ( $exptime < 86400 * 3650 /* 10 years */ ) ) {
00353             return time() + $exptime;
00354         } else {
00355             return $exptime;
00356         }
00357     }
00358 
00366     protected function convertToRelative( $exptime ) {
00367         if ( $exptime >= 86400 * 3650 /* 10 years */ ) {
00368             $exptime -= time();
00369             if ( $exptime <= 0 ) {
00370                 $exptime = 1;
00371             }
00372             return $exptime;
00373         } else {
00374             return $exptime;
00375         }
00376     }
00377 
00384     protected function isInteger( $value ) {
00385         return ( is_int( $value ) || ctype_digit( $value ) );
00386     }
00387 }