4 * When you have many workers (threads/servers) giving service, and a
5 * cached item expensive to produce expires, you may get several workers
6 * doing the job at the same time.
7 * Given enough requests and the item expiring fast (non-cacheable,
8 * lots of edits...) that single work can end up unfairly using most (all)
9 * of the cpu of the pool. This is also known as 'Michael Jackson effect'.
10 * The PoolCounter provides semaphore semantics for restricting the number
11 * of workers that may be concurrently performing such single task.
14 abstract class PoolCounter
{
17 const LOCKED
= 1; /* Lock acquired */
18 const RELEASED
= 2; /* Lock released */
19 const DONE
= 3; /* Another one did the work for you */
21 const ERROR
= -1; /* Indeterminate error */
22 const NOT_LOCKED
= -2; /* Called release() with no lock held */
23 const QUEUE_FULL
= -3; /* There are already maxqueue workers on this lock */
24 const TIMEOUT
= -4; /* Timeout exceeded */
25 const LOCK_HELD
= -5; /* Cannot acquire another lock while you have one lock held */
28 * I want to do this task and I need to do it myself.
30 * @return Locked/Error
32 abstract function acquireForMe();
35 * I want to do this task, but if anyone else does it
36 * instead, it's also fine for me. I will read its cached data.
38 * @return Locked/Done/Error
40 abstract function acquireForAnyone();
43 * I have successfully finished my task.
44 * Lets another one grab the lock, and returns the workers
45 * waiting on acquireForAnyone()
47 * @return Released/NotLocked/Error
49 abstract function release();
52 * $key: All workers with the same key share the lock.
53 * $workers: It wouldn't be a good idea to have more than this number of
54 * workers doing the task simultaneously.
55 * $maxqueue: If this number of workers are already working/waiting,
56 * fail instead of wait.
57 * $timeout: Maximum time in seconds to wait for the lock.
59 protected $key, $workers, $maxqueue, $timeout;
62 * Create a Pool counter. This should only be called from the PoolWorks.
64 public static function factory( $type, $key ) {
65 global $wgPoolCounterConf;
66 if ( !isset( $wgPoolCounterConf[$type] ) ) {
67 return new PoolCounter_Stub
;
69 $conf = $wgPoolCounterConf[$type];
70 $class = $conf['class'];
72 return new $class( $conf, $type, $key );
75 protected function __construct( $conf, $type, $key ) {
77 $this->workers
= $conf['workers'];
78 $this->maxqueue
= $conf['maxqueue'];
79 $this->timeout
= $conf['timeout'];
83 class PoolCounter_Stub
extends PoolCounter
{
84 function acquireForMe() {
85 return PoolCounter
::LOCKED
;
88 function acquireForAnyone() {
89 return PoolCounter
::LOCKED
;
93 return PoolCounter
::RELEASED
;
96 public function __construct() {
97 /* No parameters needed */
102 * Handy class for dealing with PoolCounters using class members instead of callbacks.
104 abstract class PoolCounterWork
{
105 protected $cacheable = false; //Does this override getCachedWork() ?
108 * Actually perform the work, caching it if needed.
110 abstract function doWork();
113 * Retrieve the work from cache
114 * @return mixed work result or false
116 function getCachedWork() {
121 * A work not so good (eg. expired one) but better than an error
123 * @return mixed work result or false
125 function fallback() {
130 * Do something with the error, like showing it to the user.
132 function error( $status ) {
137 * Get the result of the work (whatever it is), or false.
139 function execute( $skipcache = false ) {
140 if ( $this->cacheable
&& !$skipcache ) {
141 $status = $this->poolCounter
->acquireForAnyone();
143 $status = $this->poolCounter
->acquireForMe();
147 switch ( is_int( $status ) ?
$status : PoolCounter
::ERROR
) {
148 case PoolCounter
::LOCKED
:
149 $result = $this->doWork();
150 $this->poolCounter
->release();
153 case PoolCounter
::DONE
:
154 $result = $this->getCachedWork();
155 if ( $result === false ) {
156 /* That someone else work didn't serve us.
157 * Acquire the lock for me
159 return $this->execute( true );
163 case PoolCounter
::QUEUE_FULL
:
164 case PoolCounter
::TIMEOUT
:
165 $result = $this->fallback();
167 if ( $result !== false ) {
172 case PoolCounter
::ERROR
:
174 return $this->error( $status );
178 function __construct( $type, $key ) {
179 $this->poolCounter
= PoolCounter
::factory( $type, $key );