Accept terminator function as second parameter to Api::suspend().

src/Kernel/Api.php

@@ -122,12 +122,17 @@ public function strand(Strand $strand);
      * This operation is typically used to integrate coroutines with other forms
      * of asynchronous code.
      *
-     * @param Strand        $strand The strand executing the API call.
-     * @param callable|null $fn     A function invoked with the strand after it is suspended.
+     * @param Strand        $strand      The strand executing the API call.
+     * @param callable|null $suspendFn   A function invoked with the strand after it is suspended.
+     * @param callable|null $terminateFn A function invoked if the strand is terminated while suspended.
      *
      * @return Generator|null
      */
-    public function suspend(Strand $strand, callable $fn = null);
+    public function suspend(
+        Strand $strand,
+        callable $suspendFn = null,
+        callable $terminateFn = null
+    );
 
     /**
      * Terminate the calling strand.

src/Kernel/ApiTrait.php

@@ -157,10 +157,16 @@ public function strand(Strand $strand)
      * @param Strand        $strand The strand executing the API call.
      * @param callable|null $fn     A function invoked with the strand after it is suspended.
      */
-    public function suspend(Strand $strand, callable $fn = null)
-    {
-        if ($fn) {
-            $fn($strand);
+    public function suspend(
+        Strand $strand,
+        callable $suspendFn = null,
+        callable $terminateFn = null
+    ) {
+        if ($terminateFn) {
+            $strand->setTerminator($terminateFn);
+        }
+        if ($suspendFn) {
+            $suspendFn($strand);
         }
     }
 

test/suite-functional/api/functional.suspend.spec.php

@@ -29,3 +29,19 @@
 
     expect($strand)->to->equal($expected);
 });
+
+rit('invokes the terminate callback if the strand is terminated', function () {
+    $strand = yield Recoil::execute(function () {
+        $expected = yield Recoil::strand();
+        yield Recoil::suspend(
+            null,
+            function ($strand) use ($expected) {
+                expect($strand)->to->equal($expected);
+            }
+        );
+        assert(false, 'strand was not terminated');
+    });
+
+    yield;
+    $strand->terminate();
+});

test/suite/Kernel/ApiTrait.spec.php

@@ -297,6 +297,19 @@
             $fn->calledWith($this->strand);
             $this->strand->noInteraction();
         });
+
+        it('sets the terminator callback, if provided', function () {
+            $fn = Phony::spy();
+
+            $this->subject->mock()->suspend(
+                $this->strand->mock(),
+                null,
+                $fn
+            );
+
+            $fn->never()->called();
+            $this->strand->setTerminator($fn);
+        });
     });
 
     describe('->terminate()', function () {