PoolCounterWork.php

Go to the documentation of this file.

<?php
namespace MediaWiki\PoolCounter;
 
use LogicException;
use MediaWiki\MediaWikiServices;
use MediaWiki\Status\Status;
 
abstract class PoolCounterWork {
    protected $type = 'generic';
    protected $cacheable = false; // does this override getCachedWork() ?
    private $poolCounter;
 
    public function __construct( string $type, string $key, ?PoolCounter $poolCounter = null ) {
        $this->type = $type;
        // MW >= 1.35
        $this->poolCounter = $poolCounter ??
            MediaWikiServices::getInstance()->getPoolCounterFactory()->create( $type, $key );
    }
 
    abstract public function doWork();
 
    public function getCachedWork() {
        return false;
    }
 
    public function fallback( $fast ) {
        return false;
    }
 
    public function error( $status ) {
        return false;
    }
 
    protected function isFastStaleEnabled() {
        return $this->poolCounter->isFastStaleEnabled();
    }
 
    public function logError( $status ) {
        $key = $this->poolCounter->getKey();
 
        $this->poolCounter->getLogger()->info(
            "Pool key '$key' ({$this->type}): " .
            $status->getMessage()->inLanguage( 'en' )->useDatabase( false )->text()
        );
    }
 
    public function execute( $skipcache = false ) {
        if ( !$this->cacheable || $skipcache ) {
            $status = $this->poolCounter->acquireForMe();
            $skipcache = true;
        } else {
            if ( $this->isFastStaleEnabled() ) {
                // In fast stale mode, check for existing locks by acquiring lock with 0 timeout
                $status = $this->poolCounter->acquireForAnyone( 0 );
                if ( $status->isOK() && $status->value === PoolCounter::TIMEOUT ) {
                    // Lock acquisition would block: try fallback
                    $staleResult = $this->fallback( true );
                    if ( $staleResult !== false ) {
                        return $staleResult;
                    }
                    // No fallback available, so wait for the lock
                    $status = $this->poolCounter->acquireForAnyone();
                } // else behave as if $status were returned in slow mode
            } else {
                $status = $this->poolCounter->acquireForAnyone();
            }
        }
 
        if ( !$status->isOK() ) {
            // Respond gracefully to complete server breakage: just log it and do the work
            $this->logError( $status );
            return $this->doWork();
        }
 
        switch ( $status->value ) {
            case PoolCounter::LOCK_HELD:
                // Better to ignore nesting pool counter limits than to fail.
                // Assume that the outer pool limiting is reasonable enough.
                /* no break */
            case PoolCounter::LOCKED:
                try {
                    return $this->doWork();
                } finally {
                    $this->poolCounter->release();
                }
            // no fall-through, because try returns or throws
            case PoolCounter::DONE:
                $result = $this->getCachedWork();
                if ( $result === false ) {
                    if ( $skipcache ) {
                        // We shouldn't get here, because we called acquireForMe().
                        // which should not return DONE. If we do get here, this
                        // indicates a faulty test mock. Report the issue instead
                        // of calling $this->execute( true ) in endless recursion.
                        throw new LogicException(
                            'Got PoolCounter::DONE from acquireForMe() and ' .
                            'getCachedWork() returned nothing'
                        );
                    }
 
                    /* That someone else work didn't serve us.
                     * Acquire the lock for me
                     */
                    return $this->execute( true );
                }
                return $result;
 
            case PoolCounter::QUEUE_FULL:
            case PoolCounter::TIMEOUT:
                $result = $this->fallback( false );
 
                if ( $result !== false ) {
                    return $result;
                }
            /* no break */
 
            /* These two cases should never be hit... */
            case PoolCounter::ERROR:
            default:
                $errors = [
                    PoolCounter::QUEUE_FULL => 'pool-queuefull',
                    PoolCounter::TIMEOUT => 'pool-timeout',
                ];
 
                $status = Status::newFatal( $errors[$status->value] ?? 'pool-errorunknown' );
                $this->logError( $status );
                return $this->error( $status );
        }
    }
}
 
class_alias( PoolCounterWork::class, 'PoolCounterWork' );