# std/asyncdispatch

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

This module implements asynchronous IO. This includes a dispatcher, a `Future` type implementation, and an `async` macro which allows asynchronous code to be written in a synchronous style with the `await` keyword.

The dispatcher acts as a kind of event loop. You must call `poll` on it (or a function which does so for you such as `waitFor` or `runForever`) in order to poll for any outstanding events. The underlying implementation is based on epoll on Linux, IO Completion Ports on Windows and select on other operating systems.

The `poll` function will not, on its own, return any events. Instead an appropriate `Future` object will be completed. A `Future` is a type which holds a value which is not yet available, but which may be available in the future. You can check whether a future is finished by using the `finished` function. When a future is finished it means that either the value that it holds is now available or it holds an error instead. The latter situation occurs when the operation to complete a future fails with an exception. You can distinguish between the two situations with the `failed` function.

Future objects can also store a callback procedure which will be called automatically once the future completes.

Futures therefore can be thought of as an implementation of the proactor pattern. In this pattern you make a request for an action, and once that action is fulfilled a future is completed with the result of that action. Requests can be made by calling the appropriate functions. For example: calling the `recv` function will create a request for some data to be read from a socket. The future which the `recv` function returns will then complete once the requested amount of data is read or an exception occurs.

Code to read some data from a socket may look something like this:

    var future = socket.recv(100)
    future.addCallback(
      proc () =
        echo(future.read)
    )

All asynchronous functions returning a `Future` will not block. They will not however return immediately. An asynchronous function will have code which will be executed before an asynchronous request is made, in most cases this code sets up the request.

In the above example, the `recv` function will return a brand new `Future` instance once the request for data to be read from the socket is made. This `Future` instance will complete once the requested amount of data is read, in this case it is 100 bytes. The second line sets a callback on this future which will be called once the future completes. All the callback does is write the data stored in the future to `stdout`. The `read` function is used for this and it checks whether the future completes with an error for you (if it did, it will simply raise the error), if there is no error, however, it returns the value of the future.

# Asynchronous procedures

Asynchronous procedures remove the pain of working with callbacks. They do this by allowing you to write asynchronous code the same way as you would write synchronous code.

An asynchronous procedure is marked using the `{.async.}` pragma. When marking a procedure with the `{.async.}` pragma it must have a `Future[T]` return type or no return type at all. If you do not specify a return type then `Future[void]` is assumed.

Inside asynchronous procedures `await` can be used to call any procedures which return a `Future`; this includes asynchronous procedures. When a procedure is "awaited", the asynchronous procedure it is awaited in will suspend its execution until the awaited procedure's Future completes. At which point the asynchronous procedure will resume its execution. During the period when an asynchronous procedure is suspended other asynchronous procedures will be run by the dispatcher.

The `await` call may be used in many contexts. It can be used on the right hand side of a variable declaration: `var data = await socket.recv(100)`, in which case the variable will be set to the value of the future automatically. It can be used to await a `Future` object, and it can be used to await a procedure returning a `Future[void]`: `await socket.send("foobar")`.

If an awaited future completes with an error, then `await` will re-raise this error. To avoid this, you can use the `yield` keyword instead of `await`. The following section shows different ways that you can handle exceptions in async procs.

Caution: Procedures marked {.async.} do not support mutable parameters such as `var int`. References such as `ref int` should be used instead.

## Handling Exceptions

You can handle exceptions in the same way as in ordinary Nim code; by using the try statement:

    try:
      let data = await sock.recv(100)
      echo("Received ", data)
    except:
      # Handle exception

An alternative approach to handling exceptions is to use `yield` on a future then check the future's `failed` property. For example:

    var future = sock.recv(100)
    yield future
    if future.failed:
      # Handle exception

# Discarding futures

Futures should never be discarded directly because they may contain errors. If you do not care for the result of a Future then you should use the `asyncCheck` procedure instead of the `discard` keyword. Note that this does not wait for completion, and you should use `waitFor` or `await` for that purpose.

Note: `await` also checks if the future fails, so you can safely discard its result.

# Handling futures

There are many different operations that apply to a future. The three primary high-level operations are `asyncCheck`, `waitFor`, and `await`.

- `asyncCheck`: Raises an exception if the future fails. It neither waits for the future to finish nor returns the result of the future.
- `waitFor`: Polls the event loop and blocks the current thread until the future finishes. This is often used to call an async procedure from a synchronous context and should never be used in an `async` proc.
- `await`: Pauses execution in the current async procedure until the future finishes. While the current procedure is paused, other async procedures will continue running. Should be used instead of `waitFor` in an async procedure.

Here is a handy quick reference chart showing their high-level differences:

Procedure | Context | Blocking
--- | --- | ---
`asyncCheck` | non-async and async | non-blocking
`waitFor` | non-async | blocks current thread
`await` | async | suspends current proc

# Examples

For examples take a look at the documentation for the modules implementing asynchronous IO. A good place to start is the asyncnet module.

# Investigating pending futures

It's possible to get into a situation where an async proc, or more accurately a `Future[T]` gets stuck and never completes. This can happen for various reasons and can cause serious memory leaks. When this occurs it's hard to identify the procedure that is stuck.

Thankfully there is a mechanism which tracks the count of each pending future. All you need to do to enable it is compile with `-d:futureLogging` and use the `getFuturesInProgress` procedure to get the list of pending futures together with the stack traces to the moment of their creation.

You may also find it useful to use this prometheus package which will log the pending futures into prometheus, allowing you to analyse them via a nice graph.

# Limitations/Bugs

- The effect system (`raises: []`) does not work with async procedures.
- Mutable parameters are not supported by async procedures.

# Multiple async backend support

Thanks to its powerful macro support, Nim allows `async`/`await` to be implemented in libraries with only minimal support from the language - as such, multiple `async` libraries exist, including `asyncdispatch` and `chronos`, and more may come to be developed in the future.

Libraries built on top of async/await may wish to support multiple async backends - the best way to do so is to create separate modules for each backend that may be imported side-by-side.

An alternative way is to select backend using a global compile flag - this method makes it difficult to compose applications that use both backends as may happen with transitive dependencies, but may be appropriate in some cases - libraries choosing this path should call the flag `asyncBackend`, allowing applications to choose the backend with `-d:asyncBackend=<backend_name>`.

Known `async` backends include:

- `-d:asyncBackend=none`: disable `async` support completely
- `-d:asyncBackend=asyncdispatch`: https://nim-lang.org/docs/asyncdispatch.html
- `-d:asyncBackend=chronos`: https://github.com/status-im/nim-chronos/

`none` can be used when a library supports both a synchronous and asynchronous API, to disable the latter.

# Imports

os, tables, strutils, times, heapqueue, options, asyncstreams, math, monotimes, asyncfutures, nativesockets, net, deques, assertions, syncio, winlean, sets, hashes, asyncmacro, posix

# Types

    AsyncEvent = ptr AsyncEventImpl

  Source Edit

    AsyncFD = distinct int

  Source Edit

    Callback = proc (fd: AsyncFD): bool {.closure, ...gcsafe.}

  Source Edit

    CompletionData = object
      fd*: AsyncFD
      cb*: owned(proc (fd: AsyncFD; bytesTransferred: DWORD; errcode: OSErrorCode) {.
          closure, ...gcsafe.})
      cell*: ForeignCell

  Source Edit

    CustomRef = ref CustomObj

  Source Edit

    PDispatcher = ref object of PDispatcherBase
      handles*: HashSet[AsyncFD]

  Source Edit

# Procs

    proc `==`(x: AsyncFD; y: AsyncFD): bool {.borrow, ...raises: [], tags: [],
        forbids: [].}

  Source Edit

    proc accept(socket: AsyncFD; flags = {SafeDisconn};
                inheritable = defined(nimInheritHandles)): owned(Future[AsyncFD]) {.
        ...raises: [ValueError, OSError, Exception], tags: [RootEffect], forbids: [].}

  Accepts a new connection. Returns a future containing the client socket corresponding to that connection.

  If `inheritable` is false (the default), the resulting client socket will not be inheritable by child processes.

  The future will complete when the connection is successfully accepted.

  Source Edit

    proc acceptAddr(socket: AsyncFD; flags = {SafeDisconn};
                    inheritable = defined(nimInheritHandles)): owned(
        Future[tuple[address: string, client: AsyncFD]]) {....gcsafe,
        raises: [ValueError, OSError, Exception, ValueError, Exception],
        tags: [RootEffect], forbids: [].}

  Accepts a new connection. Returns a future containing the client socket corresponding to that connection and the remote address of the client. The future will complete when the connection is successfully accepted.

  The resulting client socket is automatically registered to the dispatcher.

  If `inheritable` is false (the default), the resulting client socket will not be inheritable by child processes.

  The `accept` call may result in an error if the connecting socket disconnects during the duration of the `accept`. If the `SafeDisconn` flag is specified then this error will not be raised and instead accept will be called again.

  Source Edit

    proc activeDescriptors(): int {.inline, ...raises: [], tags: [], forbids: [].}

  Returns the current number of active file descriptors for the current event loop. This is a cheap operation that does not involve a system call. Source Edit

    proc addEvent(ev: AsyncEvent; cb: Callback) {....raises: [OSError], tags: [],
        forbids: [].}

  Registers callback `cb` to be called when `ev` will be signaled Source Edit

    proc addProcess(pid: int; cb: Callback) {....raises: [OSError], tags: [],
        forbids: [].}

  Registers callback `cb` to be called when process with process ID `pid` exited. Source Edit

    proc addRead(fd: AsyncFD; cb: Callback) {....raises: [OSError], tags: [],
        forbids: [].}

  Start watching the file descriptor for read availability and then call the callback `cb`.

  This is not `pure` mechanism for Windows Completion Ports (IOCP), so if you can avoid it, please do it. Use `addRead` only if really need it (main usecase is adaptation of unix-like libraries to be asynchronous on Windows).

  If you use this function, you don't need to use asyncdispatch.recv() or asyncdispatch.accept(), because they are using IOCP, please use nativesockets.recv() and nativesockets.accept() instead.

  Be sure your callback `cb` returns `true`, if you want to remove watch of `read` notifications, and `false`, if you want to continue receiving notifications.

  Source Edit

    proc addTimer(timeout: int; oneshot: bool; cb: Callback) {....raises: [OSError],
        tags: [], forbids: [].}

  Registers callback `cb` to be called when timer expired.

  Parameters:

  - `timeout` - timeout value in milliseconds.
  - `oneshot`
    - `true` - generate only one timeout event
    - `false` - generate timeout events periodically
  Source Edit

    proc addWrite(fd: AsyncFD; cb: Callback) {....raises: [OSError], tags: [],
        forbids: [].}

  Start watching the file descriptor for write availability and then call the callback `cb`.

  This is not `pure` mechanism for Windows Completion Ports (IOCP), so if you can avoid it, please do it. Use `addWrite` only if really need it (main usecase is adaptation of unix-like libraries to be asynchronous on Windows).

  If you use this function, you don't need to use asyncdispatch.send() or asyncdispatch.connect(), because they are using IOCP, please use nativesockets.send() and nativesockets.connect() instead.

  Be sure your callback `cb` returns `true`, if you want to remove watch of `write` notifications, and `false`, if you want to continue receiving notifications.

  Source Edit

    proc callSoon(cbproc: proc () {....gcsafe.}) {....gcsafe, raises: [], tags: [],
        forbids: [].}

  Schedule `cbproc` to be called as soon as possible. The callback is called when control returns to the event loop. Source Edit

    proc close(ev: AsyncEvent) {....raises: [OSError], tags: [], forbids: [].}

  Closes event `ev`. Source Edit

    proc closeSocket(socket: AsyncFD) {....raises: [], tags: [], forbids: [].}

  Closes a socket and ensures that it is unregistered. Source Edit

    proc connect(socket: AsyncFD; address: string; port: Port;
                 domain = Domain.AF_INET): owned(Future[void]) {.
        ...raises: [OSError, IOError, ValueError, Exception], tags: [RootEffect],
        forbids: [].}

  Source Edit

    proc contains(disp: PDispatcher; fd: AsyncFD): bool {....raises: [], tags: [],
        forbids: [].}

  Source Edit

    proc createAsyncNativeSocket(domain: cint; sockType: cint; protocol: cint;
                                 inheritable = defined(nimInheritHandles)): AsyncFD {.
        ...raises: [OSError], tags: [], forbids: [].}

  Source Edit

    proc createAsyncNativeSocket(domain: Domain = Domain.AF_INET;
                                 sockType: SockType = SOCK_STREAM;
                                 protocol: Protocol = IPPROTO_TCP;
                                 inheritable = defined(nimInheritHandles)): AsyncFD {.
        ...raises: [OSError], tags: [], forbids: [].}

  Source Edit

    proc dial(address: string; port: Port; protocol: Protocol = IPPROTO_TCP): owned(
        Future[AsyncFD]) {....raises: [OSError, ValueError, Exception],
                           tags: [RootEffect], forbids: [].}

  Establishes connection to the specified `address`:`port` pair via the specified protocol. The procedure iterates through possible resolutions of the `address` until it succeeds, meaning that it seamlessly works with both IPv4 and IPv6. Returns the async file descriptor, registered in the dispatcher of the current thread, ready to send or receive data. Source Edit

    proc drain(timeout = 500) {....raises: [ValueError, Exception, OSError],
                                tags: [TimeEffect, RootEffect], forbids: [].}

  Waits for completion of all events and processes them. Raises `ValueError` if there are no pending operations. In contrast to `poll` this processes as many events as are available until the timeout has elapsed. Source Edit

    proc getGlobalDispatcher(): PDispatcher {....raises: [], tags: [], forbids: [].}

  Source Edit

    proc getIoHandler(disp: PDispatcher): Handle {....raises: [], tags: [], forbids: [].}

  Returns the underlying IO Completion Port handle (Windows) or selector (Unix) for the specified dispatcher. Source Edit

    proc hasPendingOperations(): bool {....raises: [], tags: [], forbids: [].}

  Returns `true` if the global dispatcher has pending operations. Source Edit

    proc maxDescriptors(): int {....raises: OSError, tags: [], forbids: [].}

  Returns the maximum number of active file descriptors for the current process. This involves a system call. For now `maxDescriptors` is supported on the following OSes: Windows, Linux, OSX, BSD, Solaris. Source Edit

    proc newAsyncEvent(): AsyncEvent {....raises: [OSError], tags: [], forbids: [].}

  Creates a new thread-safe `AsyncEvent` object.

  New `AsyncEvent` object is not automatically registered with dispatcher like `AsyncSocket`.

  Source Edit

    proc newCustom(): CustomRef {....raises: [], tags: [], forbids: [].}

  Source Edit

    proc newDispatcher(): owned PDispatcher {....raises: [], tags: [], forbids: [].}

  Creates a new Dispatcher instance. Source Edit

    proc poll(timeout = 500) {....raises: [ValueError, Exception, OSError],
                               tags: [TimeEffect, RootEffect], forbids: [].}

  Waits for completion events and processes them. Raises `ValueError` if there are no pending operations. This runs the underlying OS epoll or kqueue primitive only once. Source Edit

    proc readAll(future: FutureStream[string]): owned(Future[string]) {.
        ...stackTrace: false, raises: [Exception, ValueError], tags: [RootEffect],
        forbids: [].}

  Returns a future that will complete when all the string data from the specified future stream is retrieved. Source Edit

    proc recv(socket: AsyncFD; size: int; flags = {SafeDisconn}): owned(
        Future[string]) {....raises: [ValueError, Exception], tags: [RootEffect],
                          forbids: [].}

  Reads up to `size` bytes from `socket`. Returned future will complete once all the data requested is read, a part of the data has been read, or the socket has disconnected in which case the future will complete with a value of `""`.
  Warning: The `Peek` socket flag is not supported on Windows.
  Source Edit

    proc recvFromInto(socket: AsyncFD; data: pointer; size: int;
                      saddr: ptr SockAddr; saddrLen: ptr SockLen;
                      flags = {SafeDisconn}): owned(Future[int]) {.
        ...raises: [ValueError, Exception], tags: [RootEffect], forbids: [].}

  Receives a datagram data from `socket` into `buf`, which must be at least of size `size`, address of datagram's sender will be stored into `saddr` and `saddrLen`. Returned future will complete once one datagram has been received, and will return size of packet received. Source Edit

    proc recvInto(socket: AsyncFD; buf: pointer; size: int; flags = {SafeDisconn}): owned(
        Future[int]) {....raises: [ValueError, Exception], tags: [RootEffect],
                       forbids: [].}

  Reads up to `size` bytes from `socket` into `buf`, which must at least be of that size. Returned future will complete once all the data requested is read, a part of the data has been read, or the socket has disconnected in which case the future will complete with a value of `0`.
  Warning: The `Peek` socket flag is not supported on Windows.
  Source Edit

    proc register(fd: AsyncFD) {....raises: [OSError], tags: [], forbids: [].}

  Registers `fd` with the dispatcher. Source Edit

    proc runForever() {....raises: [ValueError, Exception, OSError],
                        tags: [TimeEffect, RootEffect], forbids: [].}

  Begins a never ending global dispatcher poll loop. Source Edit

    proc send(socket: AsyncFD; buf: pointer; size: int; flags = {SafeDisconn}): owned(
        Future[void]) {....raises: [ValueError, Exception], tags: [RootEffect],
                        forbids: [].}

  Sends `size` bytes from `buf` to `socket`. The returned future will complete once all data has been sent.
  Warning: Use it with caution. If `buf` refers to GC'ed object, you must use GC_ref/GC_unref calls to avoid early freeing of the buffer.
  Source Edit

    proc send(socket: AsyncFD; data: string; flags = {SafeDisconn}): owned(
        Future[void]) {....raises: [ValueError, Exception], tags: [RootEffect],
                        forbids: [].}

  Sends `data` to `socket`. The returned future will complete once all data has been sent. Source Edit

    proc sendTo(socket: AsyncFD; data: pointer; size: int; saddr: ptr SockAddr;
                saddrLen: SockLen; flags = {SafeDisconn}): owned(Future[void]) {.
        ...raises: [ValueError, Exception], tags: [RootEffect], forbids: [].}

  Sends `data` to specified destination `saddr`, using socket `socket`. The returned future will complete once all data has been sent. Source Edit

    proc setGlobalDispatcher(disp: sink PDispatcher) {....raises: [], tags: [],
        forbids: [].}

  Source Edit

    proc setInheritable(fd: AsyncFD; inheritable: bool): bool {....raises: [],
        tags: [], forbids: [].}

  Control whether a file handle can be inherited by child processes. Returns `true` on success.

  This procedure is not guaranteed to be available for all platforms. Test for availability with declared().

  Source Edit

    proc sleepAsync(ms: int | float): owned(Future[void])

  Suspends the execution of the current async procedure for the next `ms` milliseconds. Source Edit

    proc trigger(ev: AsyncEvent) {....raises: [OSError], tags: [], forbids: [].}

  Set event `ev` to signaled state. Source Edit

    proc unregister(ev: AsyncEvent) {....raises: [OSError], tags: [], forbids: [].}

  Unregisters event `ev`. Source Edit

    proc unregister(fd: AsyncFD) {....raises: [], tags: [], forbids: [].}

  Unregisters `fd`. Source Edit

    proc waitFor[T](fut: Future[T]): T

  Blocks the current thread until the specified future completes. Source Edit

    proc withTimeout[T](fut: Future[T]; timeout: int): owned(Future[bool])

  Returns a future which will complete once `fut` completes or after `timeout` milliseconds has elapsed.

  If `fut` completes first the returned future will hold true, otherwise, if `timeout` milliseconds has elapsed first, the returned future will hold false.

  Source Edit

# Exports

Port, SocketFlag, and, addCallback, asyncCheck, or, read, fail, setCallSoonProc, addCallback, clean, clearCallbacks, newFutureVar, mget, Future, failed, $, callback=, complete, callback=, NimAsyncContinueSuffix, FutureBase, all, complete, FutureError, getCallSoonProc, FutureVar, isFutureLoggingEnabled, complete, readError, complete, newFuture, read, finished, len, callback=, fail, newFutureStream, finished, write, complete, FutureStream, read, failed, multisync, await, async, await