This module implements a high-level asynchronous sockets API based on the asynchronous dispatcher defined in the asyncdispatch module.

Asynchronous IO in Nim

Async IO in Nim consists of multiple layers (from highest to lowest):

asyncnet module
Async await
asyncdispatch module (event loop)
selectors module

Each builds on top of the layers below it. The selectors module is an abstraction for the various system select() mechanisms such as epoll or kqueue. If you wish you can use it directly, and some people have done so successfully. But you must be aware that on Windows it only supports select().

The async dispatcher implements the proactor pattern and also has an implementation of IOCP. It implements the proactor pattern for other OS' via the selectors module. Futures are also implemented here, and indeed all the procedures return a future.

The final layer is the async await transformation. This allows you to write asynchronous code in a synchronous style and works similar to C#'s await. The transformation works by converting any async procedures into an iterator.

This is all single threaded, fully non-blocking and does give you a lot of control. In theory you should be able to work with any of these layers interchangeably (as long as you only care about non-Windows platforms).

For most applications using asyncnet is the way to go as it builds over all the layers, providing some extra features such as buffering.

SSL ===

SSL can be enabled by compiling with the -d:ssl flag.

You must create a new SSL context with the newContext function defined in the net module. You may then call wrapSocket on your socket using the newly created SSL context to get an SSL socket.

Examples

Chat server

The following example demonstrates a simple chat server.

import asyncnet, asyncdispatch

var clients {.threadvar.}: seq[AsyncSocket]

proc processClient(client: AsyncSocket) {.async.} =
  while true:
    let line = await client.recvLine()
    if line.len == 0: break
    for c in clients:
      await c.send(line & "\c\L")

proc serve() {.async.} =
  clients = @[]
  var server = newAsyncSocket()
  server.setSockOpt(OptReuseAddr, true)
  server.bindAddr(Port(12345))
  server.listen()
  
  while true:
    let client = await server.accept()
    clients.add client
    
    asyncCheck processClient(client)

asyncCheck serve()
runForever()

Imports

since, asyncdispatch, nativesockets, net, os, openssl

Types

AsyncSocket = ref AsyncSocketDesc: Source Edit

Procs

proc newAsyncSocket(fd: AsyncFD; domain: Domain = AF_INET; sockType: SockType = SOCK_STREAM; protocol: Protocol = IPPROTO_TCP; buffered = true; inheritable = defined(nimInheritHandles)): owned(AsyncSocket) {...}{. raises: [OSError], tags: [].}

Creates a new AsyncSocket based on the supplied params.

The supplied fd's non-blocking state will be enabled implicitly.

If inheritable is false (the default), the supplied fd will not be inheritable by child processes.

Note: This procedure will NOT register fd with the global async dispatcher. You need to do this manually. If you have used newAsyncNativeSocket to create fd then it's already registered.