reactphp · WyriHaximus · Apr 28, 2017 · Apr 26, 2017 · Apr 26, 2017 · Apr 26, 2017
diff --git a/README.md b/README.md
@@ -118,6 +118,131 @@ All of the loops support these features:
 * Periodic timers
 * Deferred execution on future loop tick
 
+### addTimer()
+
+The `addTimer(float $interval, callable $callback): TimerInterface` method can be used to
+enqueue a callback to be invoked once after the given interval.
+
+The timer callback function MUST be able to accept a single parameter,
+the timer instance as also returned by this method or you MAY use a
+function which has no parameters at all.
+
+The timer callback function MUST NOT throw an `Exception`.
+The return value of the timer callback function will be ignored and has
+no effect, so for performance reasons you're recommended to not return
+any excessive data structures.
+
+Unlike [`addPeriodicTimer()`](#addperiodictimer), this method will ensure
+the callback will be invoked only once after the given interval.
+You can invoke [`cancelTimer`](#canceltimer) to cancel a pending timer.
+
+```php
+$loop->addTimer(0.8, function () {
+    echo 'world!' . PHP_EOL;
+});
+
+$loop->addTimer(0.3, function () {
+    echo 'hello ';
+});
+```
+
+See also [example #1](examples).
+
+If you want to access any variables within your callback function, you
+can bind arbitrary data to a callback closure like this:
+
+```php
+function hello(LoopInterface $loop, $name)
+{
+    $loop->addTimer(1.0, function () use ($name) {
+        echo "hello $name\n";
+    });
+}
+
+hello('Tester');
+```
+
+The execution order of timers scheduled to execute at the same time is
+not guaranteed.
+
+### addPeriodicTimer()
+
+The `addPeriodicTimer(float $interval, callable $callback): TimerInterface` method can be used to
+enqueue a callback to be invoked repeatedly after the given interval.
+
+The timer callback function MUST be able to accept a single parameter,
+the timer instance as also returned by this method or you MAY use a
+function which has no parameters at all.
+
+The timer callback function MUST NOT throw an `Exception`.
+The return value of the timer callback function will be ignored and has
+no effect, so for performance reasons you're recommended to not return
+any excessive data structures.
+
+Unlike [`addTimer()`](#addtimer), this method will ensure the the
+callback will be invoked infinitely after the given interval or until you
+invoke [`cancelTimer`](#canceltimer).
+
+```php
+$timer = $loop->addPeriodicTimer(0.1, function () {
+    echo 'tick!' . PHP_EOL;
+});
+
+$loop->addTimer(1.0, function () use ($loop, $timer) {
+    $loop->cancelTimer($timer);
+    echo 'Done' . PHP_EOL;
+});
+```
+
+See also [example #2](examples).
+
+If you want to limit the number of executions, you can bind
+arbitrary data to a callback closure like this:
+
+```php
+function hello(LoopInterface $loop, $name)
+{
+    $n = 3;
+    $loop->addPeriodicTimer(1.0, function ($timer) use ($name, $loop, &$n) {
+        if ($n > 0) {
+            --$n;
+            echo "hello $name\n";
+        } else {
+            $loop->cancelTimer($timer);
+        }
+    });
+}
+
+hello('Tester');
+```
+
+The execution order of timers scheduled to execute at the same time is
+not guaranteed.
+
+### cancelTimer()
+
+The `cancelTimer(TimerInterface $timer): void` method can be used to
+cancel a pending timer.
+
+See also [`addPeriodicTimer()`](#addperiodictimer) and [example #2](examples).
+
+You can use the [`isTimerActive()`](#istimeractive) method to check if
+this timer is still "active". After a timer is successfully canceled,
+it is no longer considered "active".
+
+Calling this method on a timer instance that has not been added to this
+loop instance or on a timer
+
+### isTimerActive()
+
+The `isTimerActive(TimerInterface $timer): bool` method can be used to
+check if a given timer is active.
+
+A timer is considered "active" if it has been added to this loop instance
+via [`addTimer()`](#addtimer) or [`addPeriodicTimer()`](#addperiodictimer)
+and has not been canceled via [`cancelTimer()`](#canceltimer) and is not
+a non-periodic timer that has already been triggered after its interval.
+
 ### futureTick()
 
 The `futureTick(callable $listener): void` method can be used to

diff --git a/src/ExtEventLoop.php b/src/ExtEventLoop.php
@@ -112,7 +112,7 @@ public function removeStream($stream)
      */
     public function addTimer($interval, callable $callback)
     {
-        $timer = new Timer($this, $interval, $callback, false);
+        $timer = new Timer($interval, $callback, false);
 
         $this->scheduleTimer($timer);
 
@@ -124,7 +124,7 @@ public function addTimer($interval, callable $callback)
      */
     public function addPeriodicTimer($interval, callable $callback)
     {
-        $timer = new Timer($this, $interval, $callback, true);
+        $timer = new Timer($interval, $callback, true);
 
         $this->scheduleTimer($timer);
 

diff --git a/src/LibEvLoop.php b/src/LibEvLoop.php
@@ -108,7 +108,7 @@ public function removeStream($stream)
      */
     public function addTimer($interval, callable $callback)
     {
-        $timer = new Timer($this, $interval, $callback, false);
+        $timer = new Timer( $interval, $callback, false);
 
         $callback = function () use ($timer) {
             call_user_func($timer->getCallback(), $timer);
@@ -130,7 +130,7 @@ public function addTimer($interval, callable $callback)
      */
     public function addPeriodicTimer($interval, callable $callback)
     {
-        $timer = new Timer($this, $interval, $callback, true);
+        $timer = new Timer($interval, $callback, true);
 
         $callback = function () use ($timer) {
             call_user_func($timer->getCallback(), $timer);

diff --git a/src/LibEventLoop.php b/src/LibEventLoop.php
@@ -116,7 +116,7 @@ public function removeStream($stream)
      */
     public function addTimer($interval, callable $callback)
     {
-        $timer = new Timer($this, $interval, $callback, false);
+        $timer = new Timer($interval, $callback, false);
 
         $this->scheduleTimer($timer);
 
@@ -128,7 +128,7 @@ public function addTimer($interval, callable $callback)
      */
     public function addPeriodicTimer($interval, callable $callback)
     {
-        $timer = new Timer($this, $interval, $callback, true);
+        $timer = new Timer($interval, $callback, true);
 
         $this->scheduleTimer($timer);
 

diff --git a/src/LoopInterface.php b/src/LoopInterface.php
@@ -46,6 +46,45 @@ public function removeStream($stream);
     /**
      * Enqueue a callback to be invoked once after the given interval.
      *
+     * The timer callback function MUST be able to accept a single parameter,
+     * the timer instance as also returned by this method or you MAY use a
+     * function which has no parameters at all.
+     *
+     * The timer callback function MUST NOT throw an `Exception`.
+     * The return value of the timer callback function will be ignored and has
+     * no effect, so for performance reasons you're recommended to not return
+     * any excessive data structures.
+     *
+     * Unlike [`addPeriodicTimer()`](#addperiodictimer), this method will ensure
+     * the callback will be invoked only once after the given interval.
+     * You can invoke [`cancelTimer`](#canceltimer) to cancel a pending timer.
+     *
+     * ```php
+     * $loop->addTimer(0.8, function () {
+     *     echo 'world!' . PHP_EOL;
+     * });
+     *
+     * $loop->addTimer(0.3, function () {
+     *     echo 'hello ';
+     * });
+     * ```
+     *
+     * See also [example #1](examples).
+     *
+     * If you want to access any variables within your callback function, you
+     * can bind arbitrary data to a callback closure like this:
+     *
+     * ```php
+     * function hello(LoopInterface $loop, $name)
+     * {
+     *     $loop->addTimer(1.0, function () use ($name) {
+     *         echo "hello $name\n";
+     *     });
+     * }
+     *
+     * hello('Tester');
+     * ```
+     *
      * The execution order of timers scheduled to execute at the same time is
      * not guaranteed.
      *
@@ -59,6 +98,52 @@ public function addTimer($interval, callable $callback);
     /**
      * Enqueue a callback to be invoked repeatedly after the given interval.
      *
+     * The timer callback function MUST be able to accept a single parameter,
+     * the timer instance as also returned by this method or you MAY use a
+     * function which has no parameters at all.
+     *
+     * The timer callback function MUST NOT throw an `Exception`.
+     * The return value of the timer callback function will be ignored and has
+     * no effect, so for performance reasons you're recommended to not return
+     * any excessive data structures.
+     *
+     * Unlike [`addTimer()`](#addtimer), this method will ensure the the
+     * callback will be invoked infinitely after the given interval or until you
+     * invoke [`cancelTimer`](#canceltimer).
+     *
+     * ```php
+     * $timer = $loop->addPeriodicTimer(0.1, function () {
+     *     echo 'tick!' . PHP_EOL;
+     * });
+     *
+     * $loop->addTimer(1.0, function () use ($loop, $timer) {
+     *     $loop->cancelTimer($timer);
+     *     echo 'Done' . PHP_EOL;
+     * });
+     * ```
+     *
+     * See also [example #2](examples).
+     *
+     * If you want to limit the number of executions, you can bind
+     * arbitrary data to a callback closure like this:
+     *
+     * ```php
+     * function hello(LoopInterface $loop, $name)
+     * {
+     *     $n = 3;
+     *     $loop->addPeriodicTimer(1.0, function ($timer) use ($name, $loop, &$n) {
+     *         if ($n > 0) {
+     *             --$n;
+     *             echo "hello $name\n";
+     *         } else {
+     *             $loop->cancelTimer($timer);
+     *         }
+     *     });
+     * }
+     *
+     * hello('Tester');
+     * ```
+     *
      * The execution order of timers scheduled to execute at the same time is
      * not guaranteed.
      *
@@ -72,13 +157,30 @@ public function addPeriodicTimer($interval, callable $callback);
     /**
      * Cancel a pending timer.
      *
+     * See also [`addPeriodicTimer()`](#addperiodictimer) and [example #2](examples).
+     *
+     * You can use the [`isTimerActive()`](#istimeractive) method to check if
+     * this timer is still "active". After a timer is successfully canceled,
+     * it is no longer considered "active".
+     *
+     * Calling this method on a timer instance that has not been added to this
+     * loop instance or on a timer that is not "active" (or has already been
+     * canceled) has no effect.
+     *
      * @param TimerInterface $timer The timer to cancel.
+     *
+     * @return void
      */
     public function cancelTimer(TimerInterface $timer);
 
     /**
      * Check if a given timer is active.
      *
+     * A timer is considered "active" if it has been added to this loop instance
+     * via [`addTimer()`](#addtimer) or [`addPeriodicTimer()`](#addperiodictimer)
+     * and has not been canceled via [`cancelTimer()`](#canceltimer) and is not
+     * a non-periodic timer that has already been triggered after its interval.
+     *
      * @param TimerInterface $timer The timer to check.
      *
      * @return boolean True if the timer is still enqueued for execution.

diff --git a/src/StreamSelectLoop.php b/src/StreamSelectLoop.php
@@ -94,7 +94,7 @@ public function removeStream($stream)
      */
     public function addTimer($interval, callable $callback)
     {
-        $timer = new Timer($this, $interval, $callback, false);
+        $timer = new Timer($interval, $callback, false);
 
         $this->timers->add($timer);
 
@@ -106,7 +106,7 @@ public function addTimer($interval, callable $callback)
      */
     public function addPeriodicTimer($interval, callable $callback)
     {
-        $timer = new Timer($this, $interval, $callback, true);
+        $timer = new Timer($interval, $callback, true);
 
         $this->timers->add($timer);