From 834e9c7283bbe685436ebe9335e14c93468809ab Mon Sep 17 00:00:00 2001 From: Charles Lowell Date: Mon, 7 Aug 2023 10:43:49 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=91=8DClarify=20halt()=20error=20behavior?= =?UTF-8?q?.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- www/docs/errors.mdx | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/www/docs/errors.mdx b/www/docs/errors.mdx index 2871f781c..f5fcafa8e 100644 --- a/www/docs/errors.mdx +++ b/www/docs/errors.mdx @@ -54,24 +54,35 @@ nor will it ever raise an error. And, because it will produce neither a positive nor negative outcome, it is an error to `await` the result of a halted operation. -When this happens, the promise is rejected with a special halt error: +When this happens, the promise is rejected with a special halt error. +In this example, we show a very long running task that is stopped in the +middle of its work even though it would eventually return a value if we +waited long enough. ``` typescript -import { run, suspend } from 'effection'; +import { run, sleep } from 'effection'; async function runExample() { + // this task takes a long time to return + let task = run(function*() { + yield* sleep(10_000_000); + return "hello world"; + }); + try { - let task = run(supsend); + // halt it. It will no longer result in "hello world" await task.halt(); + + // no value will ever be available no matter how long we `await`. await task; } catch(err) { - console.log("got error", err.message) // => "got error halted" + console.log(err.message) // => "halted" } } ``` -Notice how it is not an error to `await` the halt operation itself, only to -`await` the outcome of a halted operation. +Notice how it is not an error to await the `task.halt()` operation, only +to `await` the outcome of the operation which has been halted. ## Error propagation