diff --git a/src/Loop.php b/src/Loop.php index de3947a..a23ef55 100644 --- a/src/Loop.php +++ b/src/Loop.php @@ -4,6 +4,8 @@ namespace Interop\Async; 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 @@ final class Loop * @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 @@ final class Loop * @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 @@ final class Loop * @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 @@ final class Loop } /** - * Cancel a watcher. + * Cancel a watcher. This marks the watcher identifier as invalid. * * @param string $watcherId The watcher identifier. * @@ -254,6 +262,8 @@ final class Loop * @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 @@ final class Loop * @param string $watcherId The watcher identifier. * * @return void + * + * @throws InvalidWatcherException Thrown if the watcher identifier is invalid. */ public static function unreference($watcherId) { diff --git a/src/Loop/Driver.php b/src/Loop/Driver.php index 91d7236..e504146 100644 --- a/src/Loop/Driver.php +++ b/src/Loop/Driver.php @@ -33,7 +33,7 @@ interface Driver * @param callable(string $watcherId, mixed $data) $callback The callback to defer. * @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 @@ interface Driver * @param callable(string $watcherId, mixed $data) $callback The callback to delay. * @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 @@ interface Driver * @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 @@ interface Driver * @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 @@ interface Driver * @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 @@ interface Driver * @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 @@ interface Driver * @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 @@ interface Driver * @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 @@ interface Driver * @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 @@ interface Driver * @param string $watcherId The watcher identifier. * * @return void + * + * @throws InvalidWatcherException Thrown if the watcher identifier is invalid. */ public function unreference($watcherId); diff --git a/src/Loop/InvalidWatcherException.php b/src/Loop/InvalidWatcherException.php new file mode 100644 index 0000000..856d440 --- /dev/null +++ b/src/Loop/InvalidWatcherException.php @@ -0,0 +1,11 @@ +