Merge pull request #74 from async-interop/calltime_guarantees

Specify exact guarantees when a callback has to be called

Author: trowski

src/Loop/Driver.php

@@ -28,7 +28,7 @@ public function stop();
     /**
      * Defer the execution of a callback.
      *
-     * The deferred callable MUST be executed in the next tick of the event loop.
+     * The deferred callable MUST be executed in the next tick of the event loop and before any other type of watcher. Order of definition MUST be preserved when executing the callbacks.
      *
      * @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.
@@ -40,7 +40,7 @@ public function defer(callable $callback, $data = null);
     /**
      * Delay the execution of a callback.
      *
-     * The delay is a minimum and approximate, accuracy is not guaranteed.
+     * The delay is a minimum and approximate, accuracy is not guaranteed. Order of calls MUST be determined by which timers expire first and secondarily the order of definition.
      *
      * @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.
@@ -53,7 +53,7 @@ public function delay($delay, callable $callback, $data = null);
     /**
      * Repeatedly execute a callback.
      *
-     * The interval between executions is a minimum and approximate, accuracy is not guaranteed.
+     * The interval between executions is a minimum and approximate, accuracy is not guaranteed. Order of calls MUST be determined by which timers expire first and secondarily the order of definition.
      * The first execution is scheduled after the first interval period.
      *
      * @param int $interval The time interval, in milliseconds, to wait between executions.
@@ -67,6 +67,8 @@ public function repeat($interval, callable $callback, $data = null);
     /**
      * Execute a callback when a stream resource becomes readable.
      *
+     * In case of multiple watchers on a same stream, order of definition MUST be preserved when executing the callbacks.
+     *
      * @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.
@@ -78,6 +80,8 @@ public function onReadable($stream, callable $callback, $data = null);
     /**
      * Execute a callback when a stream resource becomes writable.
      *
+     * In case of multiple watchers on a same stream, order of definition MUST be preserved when executing the callbacks.
+     *
      * @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.
@@ -89,6 +93,8 @@ public function onWritable($stream, callable $callback, $data = null);
     /**
      * Execute a callback when a signal is received.
      *
+     * In case of multiple watchers on a same signal, order of definition MUST be preserved when executing the callbacks.
+     *
      * @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.