When you have many workers (threads/servers) giving service, and a cached item expensive to produce expires, you may get several workers doing the job at the same time. More...

Inheritance diagram for PoolCounter:

[legend]

Collaboration diagram for PoolCounter:

[legend]

Public Member Functions
	acquireForAnyone ()
	I want to do this task, but if anyone else does it instead, it's also fine for me. More...

	acquireForMe ()
	I want to do this task and I need to do it myself. More...

	getKey ()

	release ()
	I have successfully finished my task. More...

Static Public Member Functions
static	factory ($type, $key)
	Create a Pool counter. More...

Public Attributes
const	DONE = 3

const	ERROR = -1

const	LOCK_HELD = -5

const	LOCKED = 1

const	NOT_LOCKED = -2

const	QUEUE_FULL = -3

const	RELEASED = 2

const	TIMEOUT = -4

Protected Member Functions
	__construct ($conf, $type, $key)

	hashKeyIntoSlots ($type, $key, $slots)
	Given a key (any string) and the number of lots, returns a slot key (a prefix with a suffix integer from the [0..($slots-1)] range). More...

	onAcquire ()
	Update any lock tracking information when the lock is acquired. More...

	onRelease ()
	Update any lock tracking information when the lock is released. More...

	precheckAcquire ()
	Checks that the lock request is sane. More...

Protected Attributes
string	$key
	All workers with the same key share the lock. More...

int	$maxqueue
	If this number of workers are already working/waiting, fail instead of wait. More...

int	$slots = 0
	Maximum number of workers working on this task type, regardless of key. More...

float	$timeout
	Maximum time in seconds to wait for the lock. More...

int	$workers
	Maximum number of workers working on tasks with the same key simultaneously. More...

Private Attributes
bool	$isMightWaitKey
	Whether the key is a "might wait" key. More...

Static Private Attributes
static bool	$acquiredMightWaitKey = 0
	Whether this process holds a "might wait" lock key. More...

Detailed Description

When you have many workers (threads/servers) giving service, and a cached item expensive to produce expires, you may get several workers doing the job at the same time.

Given enough requests and the item expiring fast (non-cacheable, lots of edits...) that single work can end up unfairly using most (all) of the cpu of the pool. This is also known as 'Michael Jackson effect' since this effect triggered on the english wikipedia on the day Michael Jackson died, the biographical article got hit with several edits per minutes and hundreds of read hits.

The PoolCounter provides semaphore semantics for restricting the number of workers that may be concurrently performing such single task. Only one key can be locked by any PoolCounter instance of a process, except for keys that start with "nowait:". However, only 0 timeouts (non-blocking requests) can be used with "nowait:" keys.

By default PoolCounter_Stub is used, which provides no locking. You can get a useful one in the PoolCounter extension.

Definition at line 45 of file PoolCounter.php.

Constructor & Destructor Documentation

PoolCounter::__construct	(	$conf,
		$type,
		$key
	)

protected

Parameters

array	$conf
string	$type	The class of actions to limit concurrency for (task type)
string	$key

Definition at line 87 of file PoolCounter.php.

References $key, $type, hashKeyIntoSlots(), and key.

Member Function Documentation

PoolCounter::acquireForAnyone ( )

abstract

I want to do this task, but if anyone else does it instead, it's also fine for me.

I will read its cached data.

Returns: Status Value is one of Locked/Done/Error

PoolCounter::acquireForMe ( )

abstract

I want to do this task and I need to do it myself.

Returns: Status Value is one of Locked/Error

static PoolCounter::factory	(	$type,
		$key
	)

static

Create a Pool counter.

This should only be called from the PoolWorks.

Parameters

string	$type	The class of actions to limit concurrency for (task type)
string	$key

Returns: PoolCounter

Definition at line 111 of file PoolCounter.php.

References $type, and global.

Referenced by PoolCounterWork\__construct().

PoolCounter::getKey ( )

Returns: string

Definition at line 125 of file PoolCounter.php.

References $key.

PoolCounter::hashKeyIntoSlots	(	$type,
		$key,
		$slots
	)

protected

Given a key (any string) and the number of lots, returns a slot key (a prefix with a suffix integer from the [0..($slots-1)] range).

This is used for a global limit on the number of instances of a given type that can acquire a lock. The hashing is deterministic so that PoolCounter::$workers is always an upper limit of how many instances with the same key can acquire a lock.

Parameters

string	$type	The class of actions to limit concurrency for (task type)
string	$key	PoolCounter instance key (any string)
int	$slots	The number of slots (max allowed value is 65536)