LockManager.php

Go to the documentation of this file.

<?php
use Psr\Log\LoggerInterface;
use Psr\Log\NullLogger;
use Wikimedia\RequestTimeout\RequestTimeout;
use Wikimedia\WaitConditionLoop;
 
abstract class LockManager {
    protected $logger;
 
    protected $lockTypeMap = [
        self::LOCK_SH => self::LOCK_SH,
        self::LOCK_UW => self::LOCK_EX, // subclasses may use self::LOCK_SH
        self::LOCK_EX => self::LOCK_EX
    ];
 
    protected $locksHeld = [];
 
    protected $domain;
    protected $lockTTL;
 
    protected $session;
 
    public const LOCK_SH = 1; // shared lock (for reads)
    public const LOCK_UW = 2; // shared lock (for reads used to write elsewhere)
    public const LOCK_EX = 3; // exclusive lock (for writes)
 
    protected const MAX_LOCK_TTL = 2 * 3600; // 2 hours
 
    protected const CLI_LOCK_TTL = 3600; // 1 hour
 
    protected const MIN_LOCK_TTL = 5; // seconds
 
    protected const MIN_GUESSED_LOCK_TTL = 5 * 60; // 5 minutes
 
    public function __construct( array $config ) {
        $this->domain = $config['domain'] ?? 'global';
        if ( isset( $config['lockTTL'] ) ) {
            $this->lockTTL = max( self::MIN_LOCK_TTL, $config['lockTTL'] );
        } elseif ( PHP_SAPI === 'cli' || PHP_SAPI === 'phpdbg' ) {
            $this->lockTTL = self::CLI_LOCK_TTL;
        } else {
            $ttl = 2 * ceil( RequestTimeout::singleton()->getWallTimeLimit() );
            $this->lockTTL = ( $ttl === INF || $ttl < self::MIN_GUESSED_LOCK_TTL )
                ? self::MIN_GUESSED_LOCK_TTL : $ttl;
        }
 
        // Upper bound on how long to keep lock structures around. This is useful when setting
        // TTLs, as the "lockTTL" value may vary based on CLI mode and app server group. This is
        // a "safe" value that can be used to avoid clobbering other locks that use high TTLs.
        $this->lockTTL = min( $this->lockTTL, self::MAX_LOCK_TTL );
 
        $random = [];
        for ( $i = 1; $i <= 5; ++$i ) {
            $random[] = mt_rand( 0, 0xFFFFFFF );
        }
        $this->session = md5( implode( '-', $random ) );
 
        $this->logger = $config['logger'] ?? new NullLogger();
    }
 
    final public function lock( array $paths, $type = self::LOCK_EX, $timeout = 0 ) {
        return $this->lockByType( [ $type => $paths ], $timeout );
    }
 
    final public function lockByType( array $pathsByType, $timeout = 0 ) {
        $pathsByType = $this->normalizePathsByType( $pathsByType );
 
        $status = null;
        $loop = new WaitConditionLoop(
            function () use ( &$status, $pathsByType ) {
                $status = $this->doLockByType( $pathsByType );
 
                return $status->isOK() ?: WaitConditionLoop::CONDITION_CONTINUE;
            },
            $timeout
        );
        $loop->invoke();
 
        // @phan-suppress-next-line PhanTypeMismatchReturn WaitConditionLoop throws or status is set
        return $status;
    }
 
    final public function unlock( array $paths, $type = self::LOCK_EX ) {
        return $this->unlockByType( [ $type => $paths ] );
    }
 
    final public function unlockByType( array $pathsByType ) {
        $pathsByType = $this->normalizePathsByType( $pathsByType );
        $status = $this->doUnlockByType( $pathsByType );
 
        return $status;
    }
 
    final protected function sha1Base36Absolute( $path ) {
        return Wikimedia\base_convert( sha1( "{$this->domain}:{$path}" ), 16, 36, 31 );
    }
 
    final protected function normalizePathsByType( array $pathsByType ) {
        $res = [];
        foreach ( $pathsByType as $type => $paths ) {
            foreach ( $paths as $path ) {
                if ( (string)$path === '' ) {
                    throw new InvalidArgumentException( __METHOD__ . ": got empty path." );
                }
            }
            $res[$this->lockTypeMap[$type]] = array_unique( $paths );
        }
 
        return $res;
    }
 
    protected function doLockByType( array $pathsByType ) {
        $status = StatusValue::newGood();
        $lockedByType = []; // map of (type => paths)
        foreach ( $pathsByType as $type => $paths ) {
            $status->merge( $this->doLock( $paths, $type ) );
            if ( $status->isOK() ) {
                $lockedByType[$type] = $paths;
            } else {
                // Release the subset of locks that were acquired
                foreach ( $lockedByType as $lType => $lPaths ) {
                    $status->merge( $this->doUnlock( $lPaths, $lType ) );
                }
                break;
            }
        }
 
        return $status;
    }
 
    abstract protected function doLock( array $paths, $type );
 
    protected function doUnlockByType( array $pathsByType ) {
        $status = StatusValue::newGood();
        foreach ( $pathsByType as $type => $paths ) {
            $status->merge( $this->doUnlock( $paths, $type ) );
        }
 
        return $status;
    }
 
    abstract protected function doUnlock( array $paths, $type );
}