Merge pull request #72 from async-interop/invalid-watcher-handling

(Re-)Introduce InvalidWatcherException

Author: trowski

src/Loop.php

@@ -4,6 +4,8 @@
 
 use Interop\Async\Loop\Driver;
 use Interop\Async\Loop\DriverFactory;
+use Interop\Async\Loop\InvalidWatcherException;
+use Interop\Async\Loop\UnsupportedFeatureException;
 
 final class Loop
 {
@@ -199,6 +201,8 @@ public static function onWritable($stream, callable $callback, $data = null)
      * @param mixed $data Arbitrary data given to the callback function as the $data parameter.
      *
      * @return string An identifier that can be used to cancel, enable or disable the watcher.
+     *
+     * @throws UnsupportedFeatureException Thrown if signal handling is not supported.
      */
     public static function onSignal($signo, callable $callback, $data = null)
     {
@@ -212,6 +216,8 @@ public static function onSignal($signo, callable $callback, $data = null)
      * @param string $watcherId The watcher identifier.
      *
      * @return void
+     *
+     * @throws InvalidWatcherException Thrown if the watcher identifier is invalid.
      */
     public static function enable($watcherId)
     {
@@ -225,6 +231,8 @@ public static function enable($watcherId)
      * @param string $watcherId The watcher identifier.
      *
      * @return void
+     *
+     * @throws InvalidWatcherException Thrown if the watcher identifier is invalid.
      */
     public static function disable($watcherId)
     {
@@ -233,7 +241,7 @@ public static function disable($watcherId)
     }
 
     /**
-     * Cancel a watcher.
+     * Cancel a watcher. This marks the watcher identifier as invalid.
      *
      * @param string $watcherId The watcher identifier.
      *
@@ -254,6 +262,8 @@ public static function cancel($watcherId)
      * @param string $watcherId The watcher identifier.
      *
      * @return void
+     *
+     * @throws InvalidWatcherException Thrown if the watcher identifier is invalid.
      */
     public static function reference($watcherId)
     {
@@ -270,6 +280,8 @@ public static function reference($watcherId)
      * @param string $watcherId The watcher identifier.
      *
      * @return void
+     *
+     * @throws InvalidWatcherException Thrown if the watcher identifier is invalid.
      */
     public static function unreference($watcherId)
     {

src/Loop/Driver.php

@@ -33,7 +33,7 @@ public function stop();
      * @param callable(string $watcherId, mixed $data) $callback The callback to defer. The $watcherId will be invalidated before the callback call.
      * @param mixed $data Arbitrary data given to the callback function as the $data parameter.
      *
-     * @return string An identifier that can be used to cancel, enable or disable the watcher.
+     * @return string An unique identifier that can be used to cancel, enable or disable the watcher.
      */
     public function defer(callable $callback, $data = null);
 
@@ -46,7 +46,7 @@ public function defer(callable $callback, $data = null);
      * @param callable(string $watcherId, mixed $data) $callback The callback to delay. The $watcherId will be invalidated before the callback call.
      * @param mixed $data Arbitrary data given to the callback function as the $data parameter.
      *
-     * @return string An identifier that can be used to cancel, enable or disable the watcher.
+     * @return string An unique identifier that can be used to cancel, enable or disable the watcher.
      */
     public function delay($delay, callable $callback, $data = null);
 
@@ -60,7 +60,7 @@ public function delay($delay, callable $callback, $data = null);
      * @param callable(string $watcherId, mixed $data) $callback The callback to repeat.
      * @param mixed $data Arbitrary data given to the callback function as the $data parameter.
      *
-     * @return string An identifier that can be used to cancel, enable or disable the watcher.
+     * @return string An unique identifier that can be used to cancel, enable or disable the watcher.
      */
     public function repeat($interval, callable $callback, $data = null);
 
@@ -71,7 +71,7 @@ public function repeat($interval, callable $callback, $data = null);
      * @param callable(string $watcherId, resource $stream, mixed $data) $callback The callback to execute.
      * @param mixed $data Arbitrary data given to the callback function as the $data parameter.
      *
-     * @return string An identifier that can be used to cancel, enable or disable the watcher.
+     * @return string An unique identifier that can be used to cancel, enable or disable the watcher.
      */
     public function onReadable($stream, callable $callback, $data = null);
 
@@ -82,7 +82,7 @@ public function onReadable($stream, callable $callback, $data = null);
      * @param callable(string $watcherId, resource $stream, mixed $data) $callback The callback to execute.
      * @param mixed $data Arbitrary data given to the callback function as the $data parameter.
      *
-     * @return string An identifier that can be used to cancel, enable or disable the watcher.
+     * @return string An unique identifier that can be used to cancel, enable or disable the watcher.
      */
     public function onWritable($stream, callable $callback, $data = null);
 
@@ -93,7 +93,7 @@ public function onWritable($stream, callable $callback, $data = null);
      * @param callable(string $watcherId, int $signo, mixed $data) $callback The callback to execute.
      * @param mixed $data Arbitrary data given to the callback function as the $data parameter.
      *
-     * @return string An identifier that can be used to cancel, enable or disable the watcher.
+     * @return string An unique identifier that can be used to cancel, enable or disable the watcher.
      *
      * @throws UnsupportedFeatureException Thrown if signal handling is not supported.
      */
@@ -105,6 +105,8 @@ public function onSignal($signo, callable $callback, $data = null);
      * @param string $watcherId The watcher identifier.
      *
      * @return void
+     *
+     * @throws InvalidWatcherException Thrown if the watcher identifier is invalid.
      */
     public function enable($watcherId);
 
@@ -114,11 +116,13 @@ public function enable($watcherId);
      * @param string $watcherId The watcher identifier.
      *
      * @return void
+     *
+     * @throws InvalidWatcherException Thrown if the watcher identifier is invalid.
      */
     public function disable($watcherId);
 
     /**
-     * Cancel a watcher.
+     * Cancel a watcher. This marks the watcher as invalid. Calling this function MUST never fail, even when passed an invalid watcher.
      *
      * @param string $watcherId The watcher identifier.
      *
@@ -135,6 +139,8 @@ public function cancel($watcherId);
      * @param string $watcherId The watcher identifier.
      *
      * @return void
+     *
+     * @throws InvalidWatcherException Thrown if the watcher identifier is invalid.
      */
     public function reference($watcherId);
 
@@ -147,6 +153,8 @@ public function reference($watcherId);
      * @param string $watcherId The watcher identifier.
      *
      * @return void
+     *
+     * @throws InvalidWatcherException Thrown if the watcher identifier is invalid.
      */
     public function unreference($watcherId);
 

src/Loop/InvalidWatcherException.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Interop\Async\Loop;
+
+/**
+ * MUST be thrown if any operation (except cancel()) is attempted with an invalid watcher identifier. [Invalid watcher identifier: any identifier not yet emitted by the driver or cancelled by the user]
+ */
+class InvalidWatcherException extends \LogicException
+{
+
+}