Reentrancy causes event reordering and stack explosions, in addition to
leading to hard-to-debug scenarios.
Since none of chronos is actually tested under reentrant conditions (ie
that all features such as exceptions, cancellations, buffer operations,
timers etc work reliably when the loop is reentered), this is hard to
support over time and prevents useful optimizations - this PR simply
detects and disallows the behaviour to remove the uncertainty,
simplifying reasoning about the event loop in general.
* introduce user guide based on `mdbook`
* set up structure for adding simple `chronos` usage examples
* move most readme content to book
* ci deploys book and api guide automatically
* remove most of existing engine docs (obsolete)
Per discussion in
https://github.com/status-im/nim-chronos/pull/251#issuecomment-1559233139,
`async: (parameters..)` is introduced as a way to customize the async
transformation instead of relying on separate keywords (like
asyncraises).
Two parameters are available as of now:
`raises`: controls the exception effect tracking
`raw`: disables body transformation
Parameters are added to `async` as a tuple allowing more params to be
added easily in the future:
```nim:
proc f() {.async: (name: value, ...).}`
```
* Introduce chronos/internals, move some code
This PR breaks the include dependencies between `asyncfutures2` and
`asyncmacros2` by moving the dispatcher and some other code to a new
module.
This step makes it easier to implement `asyncraises` support for future
utilities like `allFutures` etc avoiding the need to play tricks with
include order etc.
Future PR:s may further articulate the difference between "internal"
stuff subject to API breakage and regular public API intended for end
users (rather than advanced integrators).
* names
* windows fix
Jacek Sieka
Eugene Kabanov