4abd7a5645
* exception tracking This PR adds minimal exception tracking to chronos, moving the goalpost one step further. In particular, it becomes invalid to raise exceptions from `callSoon` callbacks: this is critical for writing correct error handling because there's no reasonable way that a user of chronos can possibly _reason_ about exceptions coming out of there: the event loop will be in an indeterminite state when the loop is executing an _random_ callback. As expected, there are several issues in the error handling of chronos: in particular, it will end up in an inconsistent internal state whenever the selector loop operations fail, because the internal state update functions are not written in an exception-safe way. This PR turns this into a Defect, which probably is not the optimal way of handling things - expect more work to be done here. Some API have no way of reporting back errors to callers - for example, when something fails in the accept loop, there's not much it can do, and no way to report it back to the user of the API - this has been fixed with the new accept flow - the old one should be deprecated. Finally, there is information loss in the API: in composite operations like `poll` and `waitFor` there's no way to differentiate internal errors from user-level errors originating from callbacks. * store `CatchableError` in future * annotate proc's with correct raises information * `selectors2` to avoid non-CatchableError IOSelectorsException * `$` should never raise * remove unnecessary gcsafe annotations * fix exceptions leaking out of timer waits * fix some imports * functions must signal raising the union of all exceptions across all platforms to enable cross-platform code * switch to unittest2 * add `selectors2` which supercedes the std library version and fixes several exception handling issues in there * fixes * docs, platform-independent eh specifiers for some functions * add feature flag for strict exception mode also bump version to 3.0.0 - _most_ existing code should be compatible with this version of exception handling but some things might need fixing - callbacks, existing raises specifications etc. * fix AsyncCheck for non-void T |
||
---|---|---|
.github/workflows | ||
chronos | ||
tests | ||
.appveyor.yml | ||
.gitignore | ||
.travis.yml | ||
LICENSE-APACHEv2 | ||
LICENSE-MIT | ||
README.md | ||
chronos.nim | ||
chronos.nimble |
README.md
Chronos - An efficient library for asynchronous programming
Introduction
Chronos is an efficient async/await framework for Nim. Features include:
- Efficient dispatch pipeline for asynchronous execution
- HTTP server with SSL/TLS support out of the box (no OpenSSL needed)
- Cancellation support
- Synchronization primitivies like queues, events and locks
- FIFO processing order of dispatch queue
- Minimal exception effect support (see exception effects)
Installation
You can use Nim's official package manager Nimble to install Chronos:
nimble install https://github.com/status-im/nim-chronos.git
or add a dependency to your .nimble
file:
requires "chronos"
Projects using chronos
- libp2p - Peer-to-Peer networking stack implemented in many languages
- Looper - Web framework
- 2DeFi - Decentralised file system
chronos
is available in the Nim Playground
Submit a PR to add yours!
Documentation
Concepts
Chronos implements the async/await paradigm in a self-contained library, using macros, with no specific helpers from the compiler.
Our event loop is called a "dispatcher" and a single instance per thread is created, as soon as one is needed.
To trigger a dispatcher's processing step, we need to call poll()
- either
directly or through a wrapper like runForever()
or waitFor()
. This step
handles any file descriptors, timers and callbacks that are ready to be
processed.
Future
objects encapsulate the result of an async procedure, upon successful
completion, and a list of callbacks to be scheduled after any type of
completion - be that success, failure or cancellation.
(These explicit callbacks are rarely used outside Chronos, being replaced by
implicit ones generated by async procedure execution and await
chaining.)
Async procedures (those using the {.async.}
pragma) return Future
objects.
Inside an async procedure, you can await
the future returned by another async
procedure. At this point, control will be handled to the event loop until that
future is completed.
Future completion is tested with Future.finished()
and is defined as success,
failure or cancellation. This means that a future is either pending or completed.
To differentiate between completion states, we have Future.failed()
and
Future.cancelled()
.
Dispatcher
You can run the "dispatcher" event loop forever, with runForever()
which is defined as:
proc runForever*() =
while true:
poll()
You can also run it until a certain future is completed, with waitFor()
which
will also call Future.read()
on it:
proc p(): Future[int] {.async.} =
await sleepAsync(100.milliseconds)
return 1
echo waitFor p() # prints "1"
waitFor()
is defined like this:
proc waitFor*[T](fut: Future[T]): T =
while not(fut.finished()):
poll()
return fut.read()
Async procedures and methods
The {.async.}
pragma will transform a procedure (or a method) returning a
specialised Future
type into a closure iterator. If there is no return type
specified, a Future[void]
is returned.
proc p() {.async.} =
await sleepAsync(100.milliseconds)
echo p().type # prints "Future[system.void]"
Whenever await
is encountered inside an async procedure, control is passed
back to the dispatcher for as many steps as it's necessary for the awaited
future to complete successfully, fail or be cancelled. await
calls the
equivalent of Future.read()
on the completed future and returns the
encapsulated value.
proc p1() {.async.} =
await sleepAsync(1.seconds)
proc p2() {.async.} =
await sleepAsync(1.seconds)
proc p3() {.async.} =
let
fut1 = p1()
fut2 = p2()
# Just by executing the async procs, both resulting futures entered the
# dispatcher's queue and their "clocks" started ticking.
await fut1
await fut2
# Only one second passed while awaiting them both, not two.
waitFor p3()
Don't let await
's behaviour of giving back control to the dispatcher surprise
you. If an async procedure modifies global state, and you can't predict when it
will start executing, the only way to avoid that state changing underneath your
feet, in a certain section, is to not use await
in it.
Error handling
Exceptions inheriting from CatchableError
are caught by hidden try
blocks
and placed in the Future.error
field, changing the future's status to
Failed
.
When a future is awaited, that exception is re-raised, only to be caught again
by a hidden try
block in the calling async procedure. That's how these
exceptions move up the async chain.
A failed future's callbacks will still be scheduled, but it's not possible to resume execution from the point an exception was raised.
proc p1() {.async.} =
await sleepAsync(1.seconds)
raise newException(ValueError, "ValueError inherits from CatchableError")
proc p2() {.async.} =
await sleepAsync(1.seconds)
proc p3() {.async.} =
let
fut1 = p1()
fut2 = p2()
await fut1
echo "unreachable code here"
await fut2
# `waitFor()` would call `Future.read()` unconditionally, which would raise the
# exception in `Future.error`.
let fut3 = p3()
while not(fut3.finished()):
poll()
echo "fut3.state = ", fut3.state # "Failed"
if fut3.failed():
echo "p3() failed: ", fut3.error.name, ": ", fut3.error.msg
# prints "p3() failed: ValueError: ValueError inherits from CatchableError"
You can put the await
in a try
block, to deal with that exception sooner:
proc p3() {.async.} =
let
fut1 = p1()
fut2 = p2()
try:
await fut1
except CachableError:
echo "p1() failed: ", fut1.error.name, ": ", fut1.error.msg
echo "reachable code here"
await fut2
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.
- Multithreading Stream/Datagram servers
Contributing
When submitting pull requests, please add test cases for any new features or fixes and make sure nimble test
is still able to execute the entire test suite successfully.
chronos
follows the Status Nim Style Guide.
Other resources
License
Licensed and distributed under either of
- MIT license: LICENSE-MIT or http://opensource.org/licenses/MIT
or
- Apache License, Version 2.0, (LICENSE-APACHEv2 or http://www.apache.org/licenses/LICENSE-2.0)
at your option. These files may not be copied, modified, or distributed except according to those terms.