From 604ef4c7671b8afdc72c90f1734fe1b76076b723 Mon Sep 17 00:00:00 2001
From: Niklas Keller <me@kelunik.com>
Date: Fri, 23 Dec 2016 20:30:08 +0100
Subject: [PATCH 1/2] Clarify Promise::when docblock

It specifies the exact invocation parameter values now and includes a statement about always-sync when callbacks.

Closes #20.
---
 src/Promise.php | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/src/Promise.php b/src/Promise.php
index 057f5ae..4ef0416 100644
--- a/src/Promise.php
+++ b/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
      */

From 88cf01c34916ca23efa72100a6e8299349e8f802 Mon Sep 17 00:00:00 2001
From: Niklas Keller <me@kelunik.com>
Date: Fri, 23 Dec 2016 23:54:28 +0100
Subject: [PATCH 2/2] Change Promise callback invocation order

Callbacks can't be executed always-sync and in the same order as registered in the edge case where another when handler is registered within a when handler. Once a promise is resolved, all new when handlers must be executed immediately now.
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 6743aca..166dd55 100644
--- a/README.md
+++ b/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.
 
 If a `Promise` is resolved with another `Promise`, the `Promise` MUST keep in pending state until the passed `Promise` is resolved. Thus, the value of a `Promise` can never be a `Promise`.