Skip to content

Commit 9483983

Browse files
WyriHaximusWyriHaximus
authored
Merge pull request #102 from clue-labs/timers
Documentation for timer API and clean up unneeded timer API
2 parents 1e498d9 + a6acc48 commit 9483983

File tree

11 files changed

+264
-104
lines changed

11 files changed

+264
-104
lines changed

‎README.md

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,131 @@ All of the loops support these features:
118118
* Periodic timers
119119
* Deferred execution on future loop tick
120120

121+
### addTimer()
122+
123+
The `addTimer(float $interval, callable $callback): TimerInterface` method can be used to
124+
enqueue a callback to be invoked once after the given interval.
125+
126+
The timer callback function MUST be able to accept a single parameter,
127+
the timer instance as also returned by this method or you MAY use a
128+
function which has no parameters at all.
129+
130+
The timer callback function MUST NOT throw an `Exception`.
131+
The return value of the timer callback function will be ignored and has
132+
no effect, so for performance reasons you're recommended to not return
133+
any excessive data structures.
134+
135+
Unlike [`addPeriodicTimer()`](#addperiodictimer), this method will ensure
136+
the callback will be invoked only once after the given interval.
137+
You can invoke [`cancelTimer`](#canceltimer) to cancel a pending timer.
138+
139+
```php
140+
$loop->addTimer(0.8, function () {
141+
echo 'world!' . PHP_EOL;
142+
});
143+
144+
$loop->addTimer(0.3, function () {
145+
echo 'hello ';
146+
});
147+
```
148+
149+
See also [example #1](examples).
150+
151+
If you want to access any variables within your callback function, you
152+
can bind arbitrary data to a callback closure like this:
153+
154+
```php
155+
function hello(LoopInterface $loop, $name)
156+
{
157+
$loop->addTimer(1.0, function () use ($name) {
158+
echo "hello $name\n";
159+
});
160+
}
161+
162+
hello('Tester');
163+
```
164+
165+
The execution order of timers scheduled to execute at the same time is
166+
not guaranteed.
167+
168+
### addPeriodicTimer()
169+
170+
The `addPeriodicTimer(float $interval, callable $callback): TimerInterface` method can be used to
171+
enqueue a callback to be invoked repeatedly after the given interval.
172+
173+
The timer callback function MUST be able to accept a single parameter,
174+
the timer instance as also returned by this method or you MAY use a
175+
function which has no parameters at all.
176+
177+
The timer callback function MUST NOT throw an `Exception`.
178+
The return value of the timer callback function will be ignored and has
179+
no effect, so for performance reasons you're recommended to not return
180+
any excessive data structures.
181+
182+
Unlike [`addTimer()`](#addtimer), this method will ensure the the
183+
callback will be invoked infinitely after the given interval or until you
184+
invoke [`cancelTimer`](#canceltimer).
185+
186+
```php
187+
$timer = $loop->addPeriodicTimer(0.1, function () {
188+
echo 'tick!' . PHP_EOL;
189+
});
190+
191+
$loop->addTimer(1.0, function () use ($loop, $timer) {
192+
$loop->cancelTimer($timer);
193+
echo 'Done' . PHP_EOL;
194+
});
195+
```
196+
197+
See also [example #2](examples).
198+
199+
If you want to limit the number of executions, you can bind
200+
arbitrary data to a callback closure like this:
201+
202+
```php
203+
function hello(LoopInterface $loop, $name)
204+
{
205+
$n = 3;
206+
$loop->addPeriodicTimer(1.0, function ($timer) use ($name, $loop, &$n) {
207+
if ($n > 0) {
208+
--$n;
209+
echo "hello $name\n";
210+
} else {
211+
$loop->cancelTimer($timer);
212+
}
213+
});
214+
}
215+
216+
hello('Tester');
217+
```
218+
219+
The execution order of timers scheduled to execute at the same time is
220+
not guaranteed.
221+
222+
### cancelTimer()
223+
224+
The `cancelTimer(TimerInterface $timer): void` method can be used to
225+
cancel a pending timer.
226+
227+
See also [`addPeriodicTimer()`](#addperiodictimer) and [example #2](examples).
228+
229+
You can use the [`isTimerActive()`](#istimeractive) method to check if
230+
this timer is still "active". After a timer is successfully canceled,
231+
it is no longer considered "active".
232+
233+
Calling this method on a timer instance that has not been added to this
234+
loop instance or on a timer
235+
236+
### isTimerActive()
237+
238+
The `isTimerActive(TimerInterface $timer): bool` method can be used to
239+
check if a given timer is active.
240+
241+
A timer is considered "active" if it has been added to this loop instance
242+
via [`addTimer()`](#addtimer) or [`addPeriodicTimer()`](#addperiodictimer)
243+
and has not been canceled via [`cancelTimer()`](#canceltimer) and is not
244+
a non-periodic timer that has already been triggered after its interval.
245+
121246
### futureTick()
122247

123248
The `futureTick(callable $listener): void` method can be used to

‎src/ExtEventLoop.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ public function removeStream($stream)
112112
*/
113113
public function addTimer($interval, callable $callback)
114114
{
115-
$timer = new Timer($this, $interval, $callback, false);
115+
$timer = new Timer($interval, $callback, false);
116116

117117
$this->scheduleTimer($timer);
118118

@@ -124,7 +124,7 @@ public function addTimer($interval, callable $callback)
124124
*/
125125
public function addPeriodicTimer($interval, callable $callback)
126126
{
127-
$timer = new Timer($this, $interval, $callback, true);
127+
$timer = new Timer($interval, $callback, true);
128128

129129
$this->scheduleTimer($timer);
130130

‎src/LibEvLoop.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@ public function removeStream($stream)
108108
*/
109109
public function addTimer($interval, callable $callback)
110110
{
111-
$timer = new Timer($this, $interval, $callback, false);
111+
$timer = new Timer( $interval, $callback, false);
112112

113113
$callback = function () use ($timer) {
114114
call_user_func($timer->getCallback(), $timer);
@@ -130,7 +130,7 @@ public function addTimer($interval, callable $callback)
130130
*/
131131
public function addPeriodicTimer($interval, callable $callback)
132132
{
133-
$timer = new Timer($this, $interval, $callback, true);
133+
$timer = new Timer($interval, $callback, true);
134134

135135
$callback = function () use ($timer) {
136136
call_user_func($timer->getCallback(), $timer);

‎src/LibEventLoop.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -116,7 +116,7 @@ public function removeStream($stream)
116116
*/
117117
public function addTimer($interval, callable $callback)
118118
{
119-
$timer = new Timer($this, $interval, $callback, false);
119+
$timer = new Timer($interval, $callback, false);
120120

121121
$this->scheduleTimer($timer);
122122

@@ -128,7 +128,7 @@ public function addTimer($interval, callable $callback)
128128
*/
129129
public function addPeriodicTimer($interval, callable $callback)
130130
{
131-
$timer = new Timer($this, $interval, $callback, true);
131+
$timer = new Timer($interval, $callback, true);
132132

133133
$this->scheduleTimer($timer);
134134

‎src/LoopInterface.php

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,45 @@ public function removeStream($stream);
4646
/**
4747
* Enqueue a callback to be invoked once after the given interval.
4848
*
49+
* The timer callback function MUST be able to accept a single parameter,
50+
* the timer instance as also returned by this method or you MAY use a
51+
* function which has no parameters at all.
52+
*
53+
* The timer callback function MUST NOT throw an `Exception`.
54+
* The return value of the timer callback function will be ignored and has
55+
* no effect, so for performance reasons you're recommended to not return
56+
* any excessive data structures.
57+
*
58+
* Unlike [`addPeriodicTimer()`](#addperiodictimer), this method will ensure
59+
* the callback will be invoked only once after the given interval.
60+
* You can invoke [`cancelTimer`](#canceltimer) to cancel a pending timer.
61+
*
62+
* ```php
63+
* $loop->addTimer(0.8, function () {
64+
* echo 'world!' . PHP_EOL;
65+
* });
66+
*
67+
* $loop->addTimer(0.3, function () {
68+
* echo 'hello ';
69+
* });
70+
* ```
71+
*
72+
* See also [example #1](examples).
73+
*
74+
* If you want to access any variables within your callback function, you
75+
* can bind arbitrary data to a callback closure like this:
76+
*
77+
* ```php
78+
* function hello(LoopInterface $loop, $name)
79+
* {
80+
* $loop->addTimer(1.0, function () use ($name) {
81+
* echo "hello $name\n";
82+
* });
83+
* }
84+
*
85+
* hello('Tester');
86+
* ```
87+
*
4988
* The execution order of timers scheduled to execute at the same time is
5089
* not guaranteed.
5190
*
@@ -59,6 +98,52 @@ public function addTimer($interval, callable $callback);
5998
/**
6099
* Enqueue a callback to be invoked repeatedly after the given interval.
61100
*
101+
* The timer callback function MUST be able to accept a single parameter,
102+
* the timer instance as also returned by this method or you MAY use a
103+
* function which has no parameters at all.
104+
*
105+
* The timer callback function MUST NOT throw an `Exception`.
106+
* The return value of the timer callback function will be ignored and has
107+
* no effect, so for performance reasons you're recommended to not return
108+
* any excessive data structures.
109+
*
110+
* Unlike [`addTimer()`](#addtimer), this method will ensure the the
111+
* callback will be invoked infinitely after the given interval or until you
112+
* invoke [`cancelTimer`](#canceltimer).
113+
*
114+
* ```php
115+
* $timer = $loop->addPeriodicTimer(0.1, function () {
116+
* echo 'tick!' . PHP_EOL;
117+
* });
118+
*
119+
* $loop->addTimer(1.0, function () use ($loop, $timer) {
120+
* $loop->cancelTimer($timer);
121+
* echo 'Done' . PHP_EOL;
122+
* });
123+
* ```
124+
*
125+
* See also [example #2](examples).
126+
*
127+
* If you want to limit the number of executions, you can bind
128+
* arbitrary data to a callback closure like this:
129+
*
130+
* ```php
131+
* function hello(LoopInterface $loop, $name)
132+
* {
133+
* $n = 3;
134+
* $loop->addPeriodicTimer(1.0, function ($timer) use ($name, $loop, &$n) {
135+
* if ($n > 0) {
136+
* --$n;
137+
* echo "hello $name\n";
138+
* } else {
139+
* $loop->cancelTimer($timer);
140+
* }
141+
* });
142+
* }
143+
*
144+
* hello('Tester');
145+
* ```
146+
*
62147
* The execution order of timers scheduled to execute at the same time is
63148
* not guaranteed.
64149
*
@@ -72,13 +157,30 @@ public function addPeriodicTimer($interval, callable $callback);
72157
/**
73158
* Cancel a pending timer.
74159
*
160+
* See also [`addPeriodicTimer()`](#addperiodictimer) and [example #2](examples).
161+
*
162+
* You can use the [`isTimerActive()`](#istimeractive) method to check if
163+
* this timer is still "active". After a timer is successfully canceled,
164+
* it is no longer considered "active".
165+
*
166+
* Calling this method on a timer instance that has not been added to this
167+
* loop instance or on a timer that is not "active" (or has already been
168+
* canceled) has no effect.
169+
*
75170
* @param TimerInterface $timer The timer to cancel.
171+
*
172+
* @return void
76173
*/
77174
public function cancelTimer(TimerInterface $timer);
78175

79176
/**
80177
* Check if a given timer is active.
81178
*
179+
* A timer is considered "active" if it has been added to this loop instance
180+
* via [`addTimer()`](#addtimer) or [`addPeriodicTimer()`](#addperiodictimer)
181+
* and has not been canceled via [`cancelTimer()`](#canceltimer) and is not
182+
* a non-periodic timer that has already been triggered after its interval.
183+
*
82184
* @param TimerInterface $timer The timer to check.
83185
*
84186
* @return boolean True if the timer is still enqueued for execution.

‎src/StreamSelectLoop.php

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ public function removeStream($stream)
9494
*/
9595
public function addTimer($interval, callable $callback)
9696
{
97-
$timer = new Timer($this, $interval, $callback, false);
97+
$timer = new Timer($interval, $callback, false);
9898

9999
$this->timers->add($timer);
100100

@@ -106,7 +106,7 @@ public function addTimer($interval, callable $callback)
106106
*/
107107
public function addPeriodicTimer($interval, callable $callback)
108108
{
109-
$timer = new Timer($this, $interval, $callback, true);
109+
$timer = new Timer($interval, $callback, true);
110110

111111
$this->timers->add($timer);
112112

0 commit comments

Comments
 (0)