Merge pull request #26 from async-interop/when-invocation

Require sync "when" invocations after resolution

Author: bwoebi

README.md

@@ -72,7 +72,7 @@ Any implementation MUST at least provide these two parameters. The implementatio
 
 > **NOTE:** The signature doesn't specify a type for `$error`. This is due to the new `Throwable` interface introduced in PHP 7. As this specification is PHP 5 compatible, we can use neither `Throwable` nor `Exception`.
 
-All registered callbacks MUST be executed in the order they were registered. If one of the callbacks throws an `Exception` or `Throwable`, it MUST be forwarded to `Async\Interop\Promise\ErrorHandler::notify`. The `Promise` implementation MUST then continue to call the remaining callbacks with the original parameters.
+All callbacks registered before the resolution MUST be executed in the order they were registered. Callbacks registered after the resolution MUST be executed immediately. If one of the callbacks throws an `Exception` or `Throwable`, it MUST be forwarded to `Async\Interop\Promise\ErrorHandler::notify`. The `Promise` implementation MUST then continue to call the remaining callbacks with the original parameters.
 
 Registered callbacks MUST NOT be called from a file with strict types enabled (`declare(strict_types=1)`).
 

src/Promise.php

@@ -10,7 +10,14 @@ interface Promise
     /**
      * Registers a callback to be invoked when the promise is resolved.
      *
-     * @param callable(\Throwable|\Exception|null $exception, mixed $result) $onResolved
+     * The callback receives `null` as first parameter and `$value` as second parameter on success. It receives the
+     * failure reason as first parameter and `null` as second parameter on failure.
+     *
+     * If the promise is already resolved, the callback MUST be executed immediately.
+     *
+     * Warning: If you use type declarations for `$value`, be sure to make them accept `null` in case of failures.
+     *
+     * @param callable(\Throwable|\Exception|null $exception, mixed $value) $onResolved Callback to be executed.
      *
      * @return void
      */