BagOStuff.php

Go to the documentation of this file.

<?php
abstract class BagOStuff {
    private $debugMode = false;
 
    protected $lastError = self::ERR_NONE;
 
    const ERR_NONE        = 0; // no error
    const ERR_NO_RESPONSE = 1; // no response
    const ERR_UNREACHABLE = 2; // can't connect
    const ERR_UNEXPECTED  = 3; // response gave some error
 
    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, 6 ) ) {
            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 = 6 ) {
        $this->clearLastError();
        $timestamp = microtime( true ); // starting UNIX timestamp
        if ( $this->add( "{$key}:lock", 1, $timeout ) ) {
            return true;
        } elseif ( $this->getLastError() ) {
            return false;
        }
 
        $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
            $this->clearLastError();
            $locked = $this->add( "{$key}:lock", 1, $timeout );
            if ( $this->getLastError() ) {
                return false;
            }
        } 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 ) {
        wfDeprecated( __METHOD__, '1.23' );
        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 getLastError() {
        return $this->lastError;
    }
 
    public function clearLastError() {
        $this->lastError = self::ERR_NONE;
    }
 
    protected function setLastError( $err ) {
        $this->lastError = $err;
    }
 
    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 ) );
    }
}