Introduction

Chronos implements the async/await paradigm in a self-contained library using macro and closure iterator transformation features provided by Nim.

Features include:

  • Asynchronous socket and process I/O
  • HTTP client / server with SSL/TLS support out of the box (no OpenSSL needed)
  • Synchronization primitivies like queues, events and locks
  • Cancellation
  • Efficient dispatch pipeline with excellent multi-platform support
  • Exception effect support

Installation

Install chronos using nimble:

nimble install chronos

or add a dependency to your .nimble file:

requires "chronos"

and start using it:

import chronos/apps/http/httpclient

proc retrievePage*(uri: string): Future[string] {.async.} =
  # Create a new HTTP session
  let httpSession = HttpSessionRef.new()
  try:
    # Fetch page contents
    let resp = await httpSession.fetch(parseUri(uri))
    # Convert response to a string, assuming its encoding matches the terminal!
    bytesToString(resp.data)
  finally: # Close the session
    await noCancel(httpSession.closeWait())

echo waitFor retrievePage(
  "https://raw.githubusercontent.com/status-im/nim-chronos/master/README.md")

There are more examples throughout the manual!

Platform support

Several platforms are supported, with different backend options:

  • Windows: IOCP
  • Linux: epoll / poll
  • OSX / BSD: kqueue / poll
  • Android / Emscripten / posix: poll

API documentation

This guide covers basic usage of chronos - for details, see the API reference.