neutron / tip-top
Tip-Top, a library to set timeouts and periodic timers
Requires
- php: >=5.3.3
- ext-pcntl: *
- ext-posix: *
- evenement/evenement: ~1.0
Requires (Dev)
- phpunit/phpunit: ~3.7
- sami/sami: ~1.0
This package is auto-updated.
Last update: 2024-09-25 06:54:03 UTC
README
#TIP-TOP
A micro library to set timeouts and periodic timers.
$clock = new Clock(); // triggers a callback every second $timer = $clock->addPeriodicTimer(1, function ($timer) { echo "BOOM ! I'm triggered every second !\n"; });
It uses Evenement. Most of the timers code has been taken from ReactPHP timers implementation.
Installation
The recommended way to use tip-top is through composer.
{ "require": { "neutron/tip-top": "0.2.*" } }
Disclaimer
Limitations
- Tip-Top requires you declare ticks in the script you're running.
declare(ticks=1);
- Tip-Top may not work as expected with blocking calls (try it before)
Is this blocking or non-blocking IO ?
TipTop is non blocking, but it has been designed to support some blocking
calls. Timers and timeout may be triggered lately in case you use blocking
calls like sleep(5)
.
A common workaround for sleep
is to iterate 1 seconds sleeps :
for ($i=0; $i!=5; $i++;) {sleep(1);}
.
Has the clock atomic precision ?
Unfortunately, this library is based on a hack on the pcntl_alarm function. Therefore, the resolution of the clock is the second, and it has shift that is approximatively 0,001 second per second.
What's the use case for such clock ?
Think about long running processes that have to be checked regularly.
Documentation
Examples
There are two main methods on the Neutron\TipTop\Clock
object :
addPeriodicTimer
and addTimer
.
use Neutron\TipTop\Clock; // mandatory for the clock to work declare(ticks=1); $clock = new Clock(); // triggers a callback every second $timer = $clock->addPeriodicTimer(1, function ($timer) { echo "BOOM ! I'm triggered every second !\n"; }); // triggers a callback in 5 second $timer = $clock->addTimer(5, function ($timer) { echo "BOOM ! I was planned 5 seconds ago !\n"; }); // removes all timers $clock->clear();
Remove a timer
You can remove a timer using its cancel
method :
use Neutron\TipTop\Clock; // mandatory for the clock to work declare(ticks=1); $clock = new Clock(); $timer = $clock->addPeriodicTimer(1, function ($timer) { if ($stop) { $timer->cancel(); } });
Clear all timers
You may want to clear all timers :
use Neutron\TipTop\Clock; // mandatory for the clock to work declare(ticks=1); $clock = new Clock(); $timer = $clock->addPeriodicTimer(1, function ($timer) { echo "Hello"; }); $timer = $clock->addPeriodicTimer(1, function ($timer) { echo "Hello World"; }); // removes all timers $clock->clear();
Block
You can sometimes want to block until all timers have finished, use the block
method to do that.
use Neutron\TipTop\Clock; // mandatory for the clock to work declare(ticks=1); $clock = new Clock(); // echoes three times $clock->addPeriodicTimer(1, function (signature) { echo "The block method blocks \n"; }, 3); $clock->block(); echo "This line will be blocked until last timer executes
Tests
Tip Top is functional and unit testable with PHPUnit.
To run tests on your system, please be sure to install dev-dependencies with
composer install --dev
, then run either bin/phpunit -c phpunit.xml.dist
for
unit tests, either bin/phpunit -c phpunit-functional.xml.dist
for functional
tests.
##License
This project is licensed under the MIT license.