BagOStuff.php

Go to the documentation of this file.

<?php
abstract class BagOStuff {
        private $debugMode = false;

        public function setDebug( $bool ) {
                $this->debugMode = $bool;
        }

        /* *** THE GUTS OF THE OPERATION *** */
        /* Override these with functional things in subclasses */

        abstract public function get( $key, &$casToken = null );

        abstract public function set( $key, $value, $exptime = 0 );

        abstract public function cas( $casToken, $key, $value, $exptime = 0 );

        abstract public function delete( $key, $time = 0 );

        public function merge( $key, closure $callback, $exptime = 0, $attempts = 10 ) {
                return $this->mergeViaCas( $key, $callback, $exptime, $attempts );
        }

        protected function mergeViaCas( $key, closure $callback, $exptime = 0, $attempts = 10 ) {
                do {
                        $casToken = null; // passed by reference
                        $currentValue = $this->get( $key, $casToken ); // get the old value
                        $value = $callback( $this, $key, $currentValue ); // derive the new value

                        if ( $value === false ) {
                                $success = true; // do nothing
                        } elseif ( $currentValue === false ) {
                                // Try to create the key, failing if it gets created in the meantime
                                $success = $this->add( $key, $value, $exptime );
                        } else {
                                // Try to update the key, failing if it gets changed in the meantime
                                $success = $this->cas( $casToken, $key, $value, $exptime );
                        }
                } while ( !$success && --$attempts );

                return $success;
        }

        protected function mergeViaLock( $key, closure $callback, $exptime = 0, $attempts = 10 ) {
                if ( !$this->lock( $key, 60 ) ) {
                        return false;
                }

                $currentValue = $this->get( $key ); // get the old value
                $value = $callback( $this, $key, $currentValue ); // derive the new value

                if ( $value === false ) {
                        $success = true; // do nothing
                } else {
                        $success = $this->set( $key, $value, $exptime ); // set the new value
                }

                if ( !$this->unlock( $key ) ) {
                        // this should never happen
                        trigger_error( "Could not release lock for key '$key'." );
                }

                return $success;
        }

        public function lock( $key, $timeout = 60 ) {
                $timestamp = microtime( true ); // starting UNIX timestamp
                if ( $this->add( "{$key}:lock", $timeout ) ) {
                        return true;
                }

                $uRTT = ceil( 1e6 * ( microtime( true ) - $timestamp ) ); // estimate RTT (us)
                $sleep = 2*$uRTT; // rough time to do get()+set()

                $locked = false; // lock acquired
                $attempts = 0; // failed attempts
                do {
                        if ( ++$attempts >= 3 && $sleep <= 1e6 ) {
                                // Exponentially back off after failed attempts to avoid network spam.
                                // About 2*$uRTT*(2^n-1) us of "sleep" happen for the next n attempts.
                                $sleep *= 2;
                        }
                        usleep( $sleep ); // back off
                        $locked = $this->add( "{$key}:lock", $timeout );
                } while( !$locked );

                return $locked;
        }

        public function unlock( $key ) {
                return $this->delete( "{$key}:lock" );
        }

        public function deleteObjectsExpiringBefore( $date, $progressCallback = false ) {
                // stub
                return false;
        }

        /* *** Emulated functions *** */

        public function getMulti( array $keys ) {
                $res = array();
                foreach ( $keys as $key ) {
                        $val = $this->get( $key );
                        if ( $val !== false ) {
                                $res[$key] = $val;
                        }
                }
                return $res;
        }

        public function add( $key, $value, $exptime = 0 ) {
                if ( $this->get( $key ) === false ) {
                        return $this->set( $key, $value, $exptime );
                }
                return false; // key already set
        }

        public function replace( $key, $value, $exptime = 0 ) {
                if ( $this->get( $key ) !== false ) {
                        return $this->set( $key, $value, $exptime );
                }
                return false; // key not already set
        }

        public function incr( $key, $value = 1 ) {
                if ( !$this->lock( $key ) ) {
                        return false;
                }
                $n = $this->get( $key );
                if ( $this->isInteger( $n ) ) { // key exists?
                        $n += intval( $value );
                        $this->set( $key, max( 0, $n ) ); // exptime?
                } else {
                        $n = false;
                }
                $this->unlock( $key );

                return $n;
        }

        public function decr( $key, $value = 1 ) {
                return $this->incr( $key, - $value );
        }

        public function debug( $text ) {
                if ( $this->debugMode ) {
                        $class = get_class( $this );
                        wfDebug( "$class debug: $text\n" );
                }
        }

        protected function convertExpiry( $exptime ) {
                if ( ( $exptime != 0 ) && ( $exptime < 86400 * 3650 /* 10 years */ ) ) {
                        return time() + $exptime;
                } else {
                        return $exptime;
                }
        }

        protected function convertToRelative( $exptime ) {
                if ( $exptime >= 86400 * 3650 /* 10 years */ ) {
                        $exptime -= time();
                        if ( $exptime <= 0 ) {
                                $exptime = 1;
                        }
                        return $exptime;
                } else {
                        return $exptime;
                }
        }

        protected function isInteger( $value ) {
                return ( is_int( $value ) || ctype_digit( $value ) );
        }
}