exception tracking

README.md

@@ -15,6 +15,7 @@ Chronos is an efficient [async/await](https://en.wikipedia.org/wiki/Async/await)
 * Cancellation support
 * Synchronization primitivies like queues, events and locks
 * FIFO processing order of dispatch queue
+* Minimal exception effect support (see [exception effects](#exception-effects))
 
 ## Installation
 
@@ -198,15 +199,49 @@ proc p3() {.async.} =
     fut2 = p2()
   try:
     await fut1
-  except:
+  except CachableError:
     echo "p1() failed: ", fut1.error.name, ": ", fut1.error.msg
   echo "reachable code here"
   await fut2
 ```
 
-Exceptions inheriting from `Defect` are treated differently, being raised
-directly. Don't try to catch them coming out of `poll()`, because this would
-leave behind some zombie futures.
+Chronos does not allow that future continuations and other callbacks raise
+`CatchableError` - as such, calls to `poll` will never raise exceptions caused
+originating from tasks on the dispatcher queue. It is however possible that
+`Defect` that happen in tasks bubble up through `poll` as these are not caught
+by the transformation.
+
+### Platform independence
+
+Several functions in `chronos` are backed by the operating system, such as
+waiting for network events, creating files and sockets etc. The specific
+exceptions that are raised by the OS is platform-dependent, thus such functions
+are declared as raising `CatchableError` but will in general raise something
+more specific. In particular, it's possible that some functions that are
+annotated as raising `CatchableError` only raise on _some_ platforms - in order
+to work on all platforms, calling code must assume that they will raise even
+when they don't seem to do so on one platform.
+
+### Exception effects
+
+`chronos` currently offers minimal support for exception effects and `raises`
+annotations. In general, during the `async` transformation, a generic
+`except CatchableError` handler is added around the entire function being
+transformed, in order to catch any exceptions and transfer them to the `Future`.
+Because of this, the effect system thinks no exceptions are "leaking" because in
+fact, exception _handling_ is deferred to when the future is being read.
+
+Effectively, this means that while code can be compiled with
+`{.push raises: [Defect]}`, the intended effect propagation and checking is
+**disabled** for `async` functions.
+
+To enable checking exception effects in `async` code, enable strict mode with
+`-d:chronosStrictException`.
+
+In the strict mode, `async` functions are checked such that they only raise
+`CatchableError` and thus must make sure to explicitly specify exception
+effects on forward declarations, callbacks and methods using
+`{.raises: [CatchableError].}` (or more strict) annotations.
 
 ## TODO
   * Pipe/Subprocess Transports.

chronos.nimble

@@ -1,5 +1,5 @@
 packageName   = "chronos"
-version       = "2.6.1"
+version       = "3.0.0"
 author        = "Status Research & Development GmbH"
 description   = "Chronos"
 license       = "Apache License 2.0 or MIT"
@@ -10,12 +10,13 @@ skipDirs      = @["tests"]
 requires "nim > 1.2.0",
          "stew",
          "bearssl",
-         "httputils"
+         "httputils",
+         "https://github.com/status-im/nim-unittest2.git#head"
 
 task test, "Run all tests":
   var commands = @[
     "nim c -r -d:useSysAssert -d:useGcAssert tests/",
-    "nim c -r -d:chronosStackTrace tests/",
+    "nim c -r -d:chronosStackTrace -d:chronosStrictException tests/",
     "nim c -r -d:release tests/",
     "nim c -r -d:release -d:chronosFutureTracking tests/"
   ]

chronos/apps.nim

@@ -6,5 +6,5 @@
 #              Licensed under either of
 #  Apache License, version 2.0, (LICENSE-APACHEv2)
 #              MIT license (LICENSE-MIT)
-import apps/http/httpserver, apps/http/shttpserver
+import ./apps/http/[httpserver, shttpserver]
 export httpserver, shttpserver

chronos/apps/http/httpserver.nim

@@ -44,11 +44,12 @@ type
     Empty, Prepared, Sending, Finished, Failed, Cancelled, Dumb
 
   HttpProcessCallback* =
-    proc(req: RequestFence): Future[HttpResponseRef] {.gcsafe.}
+    proc(req: RequestFence): Future[HttpResponseRef] {.
+      gcsafe, raises: [Defect, CatchableError].}
 
   HttpConnectionCallback* =
     proc(server: HttpServerRef,
-         transp: StreamTransport): Future[HttpConnectionRef] {.gcsafe.}
+         transp: StreamTransport): Future[HttpConnectionRef] {.gcsafe, raises: [Defect].}
 
   HttpServer* = object of RootObj
     instance*: StreamServer