README

Excimer is an extension for PHP which provides flexible userspace timers.

This library provides a global request timeout concept, ideally using Excimer, but with a fallback to set_time_limit() if Excimer is not available.

Typical usage:

use Wikimedia\RequestTimeout\RequestTimeout;

RequestTimeout::singleton()->setWallTimeLimit( 20 );

This sets a timer for 20 seconds of wall clock time. When it expires, a TimeoutException will be thrown.

It is possible to query the amount of time remaining:

if ( RequestTimeout::singleton()->getWallTimeRemaining() > 5 ) {
	do_slow_thing();
} else {
	do_fast_thing();
}

This works in the fallback mode.

The library provides a critical section concept. If a critical section is active, timeouts will be queued, rather than immediately thrown. The timeout exception will be thrown once no critical section is open.

$csp = RequestTimeout::singleton()->createCriticalSectionProvider( 5 );
$csp->enter( __METHOD__ );
try {
	do_something();
} finally {
	$csp->exit( __METHOD__ );
}

It is important to always exit a critical section. If the code in the critical section can throw an error, try/finally can be used to ensure that the critical section is exited. Alternatively we provide a scope variable model:

function foo() {
	$scope = $csp->scopedEnter( __METHOD__ );
	do_something();
}

The critical section exits when the scope object is destroyed. However, with this method, it is important to not terminate the request during the critical section, for example by calling exit(), or by keeping the scope object in global variable after the function returns. The library may throw an exception from a destructor during request shutdown, which causes a PHP fatal error.

Critical sections are not functional in the fallback mode.