Merge pull request #63 from async-interop/throw-on-invalid-watcher

Throw on invalid watcher identifier

Author: bwoebi

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
 {
@@ -209,6 +211,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)
     {
@@ -221,6 +225,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 or cancelled.
      */
     public static function enable($watcherId)
     {
@@ -233,6 +239,8 @@ public static function enable($watcherId)
      * @param string $watcherId The watcher identifier.
      *
      * @return void
+     *
+     * @throws InvalidWatcherException Thrown if the watcher identifier is invalid or cancelled.
      */
     public static function disable($watcherId)
     {
@@ -245,6 +253,8 @@ public static function disable($watcherId)
      * @param string $watcherId The watcher identifier.
      *
      * @return void
+     *
+     * @throws InvalidWatcherException Thrown if the watcher identifier is invalid or cancelled.
      */
     public static function cancel($watcherId)
     {
@@ -260,6 +270,8 @@ public static function cancel($watcherId)
      * @param string $watcherId The watcher identifier.
      *
      * @return void
+     *
+     * @throws InvalidWatcherException Thrown if the watcher identifier is invalid or cancelled.
      */
     public static function reference($watcherId)
     {
@@ -275,6 +287,8 @@ public static function reference($watcherId)
      * @param string $watcherId The watcher identifier.
      *
      * @return void
+     *
+     * @throws InvalidWatcherException Thrown if the watcher identifier is invalid or cancelled.
      */
     public static function unreference($watcherId)
     {

src/Loop/Driver.php

@@ -94,6 +94,8 @@ public 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 function onSignal($signo, callable $callback, $data = null);
 
@@ -103,15 +105,19 @@ 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 or cancelled.
      */
     public function enable($watcherId);
 
     /**
-     * Disable a watcher.
+     * Disable a watcher. Disabling a watcher MUST NOT invalidate the watcher.
      *
      * @param string $watcherId The watcher identifier.
      *
      * @return void
+     *
+     * @throws InvalidWatcherException Thrown if the watcher identifier is invalid or cancelled.
      */
     public function disable($watcherId);
 
@@ -121,6 +127,8 @@ public function disable($watcherId);
      * @param string $watcherId The watcher identifier.
      *
      * @return void
+     *
+     * @throws InvalidWatcherException Thrown if the watcher identifier is invalid or cancelled.
      */
     public function cancel($watcherId);
 
@@ -133,6 +141,8 @@ public function cancel($watcherId);
      * @param string $watcherId The watcher identifier.
      *
      * @return void
+     *
+     * @throws InvalidWatcherException Thrown if the watcher identifier is invalid or cancelled.
      */
     public function reference($watcherId);
 
@@ -145,6 +155,8 @@ public function reference($watcherId);
      * @param string $watcherId The watcher identifier.
      *
      * @return void
+     *
+     * @throws InvalidWatcherException Thrown if the watcher identifier is invalid or cancelled.
      */
     public function unreference($watcherId);
 

src/Loop/InvalidWatcherException.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Interop\Async\Loop;
+
+/**
+ * Must be thrown if an operation is attempted with an invalid watcher identifier.
+ */
+class InvalidWatcherException extends \LogicException
+{
+
+}