From 0635697a89b3aef2a188a0bddb46965bae7ee70f Mon Sep 17 00:00:00 2001
From: Jacek Sieka <arnetheduck@gmail.com>
Date: Fri, 3 Sep 2021 14:20:57 +0200
Subject: [PATCH] Document `-d:async_backend` flag (#18700)

* Document `-d:asyncBackend` flag

Since libraries may want to support multiple async backends, it's useful
to standardize the way this is done, so as to simplify usage of any
async backend within the ecosystem.

A similar text is being added to chronos here:
https://github.com/status-im/nim-chronos/pull/216

See also https://github.com/status-im/nim-chronos/issues/207

* typos, add none

* Update lib/pure/asyncdispatch.nim

* Update lib/pure/asyncdispatch.nim

Co-authored-by: Andreas Rumpf <rumpf_a@web.de>
---
 lib/pure/asyncdispatch.nim | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/lib/pure/asyncdispatch.nim b/lib/pure/asyncdispatch.nim
index 955e66f6ba..d87e2360f7 100644
--- a/lib/pure/asyncdispatch.nim
+++ b/lib/pure/asyncdispatch.nim
@@ -165,6 +165,34 @@
 ## ================
 ##
 ## * The effect system (`raises: []`) does not work with 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:
+##
+## * `none` - ``-d:asyncBackend=none`` - disable ``async`` support completely
+## * `asyncdispatch <https://nim-lang.org/docs/asyncdispatch.html> -``-d:asyncBackend=asyncdispatch``
+## * `chronos <https://github.com/status-im/nim-chronos/>` - ``-d:asyncBackend=chronos``
+##
+## ``none`` can be used when a library supports both a synchronous and
+## asynchronous API, to disable the latter.
 
 import os, tables, strutils, times, heapqueue, options, asyncstreams
 import options, math, std/monotimes