Add note about watchers being enabled by default to every method creating a watcher

Author: kelunik

src/Loop.php

@@ -136,8 +136,11 @@ public static function stop()
     /**
      * Defer the execution of a callback.
      *
-     * The deferred callable MUST be executed in the next tick of the event loop and before any other type of watcher.
-     * Order of enabling MUST be preserved when executing the callbacks.
+     * The deferred callable MUST be executed before any other type of watcher in a tick. Order of enabling MUST be
+     * preserved when executing the callbacks.
+     *
+     * The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
+     * right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
      *
      * @param callable(string $watcherId, mixed $data) $callback The callback to defer. The `$watcherId` will be
      *     invalidated before the callback call.
@@ -157,6 +160,9 @@ public static function defer(callable $callback, $data = null)
      * The delay is a minimum and approximate, accuracy is not guaranteed. Order of calls MUST be determined by which
      * timers expire first, but timers with the same expiration time MAY be executed in any order.
      *
+     * The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
+     * right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
+     *
      * @param int $delay The amount of time, in milliseconds, to delay the execution for.
      * @param callable(string $watcherId, mixed $data) $callback The callback to delay. The `$watcherId` will be
      *     invalidated before the callback call.
@@ -177,6 +183,9 @@ public static function delay($time, callable $callback, $data = null)
      * determined by which timers expire first, but timers with the same expiration time MAY be executed in any order.
      * The first execution is scheduled after the first interval period.
      *
+     * The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
+     * right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
+     *
      * @param int $interval The time interval, in milliseconds, to wait between executions.
      * @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.
@@ -199,6 +208,9 @@ public static function repeat($interval, callable $callback, $data = null)
      *
      * Multiple watchers on the same stream MAY be executed in any order.
      *
+     * The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
+     * right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
+     *
      * @param resource $stream The stream to monitor.
      * @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.
@@ -221,6 +233,9 @@ public static function onReadable($stream, callable $callback, $data = null)
      *
      * Multiple watchers on the same stream MAY be executed in any order.
      *
+     * The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
+     * right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
+     *
      * @param resource $stream The stream to monitor.
      * @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.
@@ -242,6 +257,9 @@ public static function onWritable($stream, callable $callback, $data = null)
      *
      * Multiple watchers on the same signal MAY be executed in any order.
      *
+     * The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
+     * right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
+     *
      * @param int $signo The signal number to monitor.
      * @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.
@@ -257,7 +275,7 @@ public static function onSignal($signo, callable $callback, $data = null)
     }
 
     /**
-     * Enable a watcher.
+     * Enable a watcher to be active starting in the next tick.
      *
      * Watchers MUST immediately be marked as enabled, but only be activated (i.e. callbacks can be called) right before
      * the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
@@ -275,7 +293,10 @@ public static function enable($watcherId)
     }
 
     /**
-     * Disable a watcher.
+     * Disable a watcher immediately.
+     *
+     * A watcher MUST be disabled immediately, e.g. if a defer watcher disables a later defer watcher, the second defer
+     * watcher isn't executed in this tick.
      *
      * Disabling a watcher MUST NOT invalidate the watcher. Calling this function MUST NOT fail, even if passed an
      * invalid watcher.

src/Loop/Driver.php

@@ -47,8 +47,11 @@ abstract public function stop();
     /**
      * Defer the execution of a callback.
      *
-     * The deferred callable MUST be executed in the next tick of the event loop and before any other type of watcher.
-     * Order of enabling MUST be preserved when executing the callbacks.
+     * The deferred callable MUST be executed before any other type of watcher in a tick. Order of enabling MUST be
+     * preserved when executing the callbacks.
+     *
+     * The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
+     * right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
      *
      * @param callable(string $watcherId, mixed $data) $callback The callback to defer. The `$watcherId` will be
      *     invalidated before the callback call.
@@ -64,6 +67,9 @@ abstract public function defer(callable $callback, $data = null);
      * The delay is a minimum and approximate, accuracy is not guaranteed. Order of calls MUST be determined by which
      * timers expire first, but timers with the same expiration time MAY be executed in any order.
      *
+     * The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
+     * right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
+     *
      * @param int $delay The amount of time, in milliseconds, to delay the execution for.
      * @param callable(string $watcherId, mixed $data) $callback The callback to delay. The `$watcherId` will be
      *     invalidated before the callback call.
@@ -80,6 +86,9 @@ abstract public function delay($delay, callable $callback, $data = null);
      * determined by which timers expire first, but timers with the same expiration time MAY be executed in any order.
      * The first execution is scheduled after the first interval period.
      *
+     * The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
+     * right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
+     *
      * @param int $interval The time interval, in milliseconds, to wait between executions.
      * @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.
@@ -98,6 +107,9 @@ abstract public function repeat($interval, callable $callback, $data = null);
      *
      * Multiple watchers on the same stream MAY be executed in any order.
      *
+     * The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
+     * right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
+     *
      * @param resource $stream The stream to monitor.
      * @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.
@@ -116,6 +128,9 @@ abstract public function onReadable($stream, callable $callback, $data = null);
      *
      * Multiple watchers on the same stream MAY be executed in any order.
      *
+     * The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
+     * right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
+     *
      * @param resource $stream The stream to monitor.
      * @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.
@@ -133,6 +148,9 @@ abstract public function onWritable($stream, callable $callback, $data = null);
      *
      * Multiple watchers on the same signal MAY be executed in any order.
      *
+     * The created watcher MUST immediately be marked as enabled, but only be activated (i.e. callback can be called)
+     * right before the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
+     *
      * @param int $signo The signal number to monitor.
      * @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.
@@ -144,7 +162,7 @@ abstract public function onWritable($stream, callable $callback, $data = null);
     abstract public function onSignal($signo, callable $callback, $data = null);
 
     /**
-     * Enable a watcher.
+     * Enable a watcher to be active starting in the next tick.
      *
      * Watchers MUST immediately be marked as enabled, but only be activated (i.e. callbacks can be called) right before
      * the next tick. Callbacks of watchers MUST NOT be called in the tick they were enabled.
@@ -158,7 +176,10 @@ abstract public function onSignal($signo, callable $callback, $data = null);
     abstract public function enable($watcherId);
 
     /**
-     * Disable a watcher.
+     * Disable a watcher immediately.
+     *
+     * A watcher MUST be disabled immediately, e.g. if a defer watcher disables a later defer watcher, the second defer
+     * watcher isn't executed in this tick.
      *
      * Disabling a watcher MUST NOT invalidate the watcher. Calling this function MUST NOT fail, even if passed an
      * invalid watcher.