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)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy