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.

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.

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:

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.