jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Rework discarding futures documentation in asyncdispatch (#19738)

Browse source 
* Rework discarding futures docs in asyncdispatch

* Fix typos

Co-authored-by: Danil Yarantsev <tiberiumk12@gmail.com>

* Use rst note::

Co-authored-by: flywind <xzsflywind@gmail.com>

* Split discarding and handling futures.

* Update lib/pure/asyncdispatch.nim

* Update lib/pure/asyncdispatch.nim

* Update lib/pure/asyncdispatch.nim

* Update lib/pure/asyncdispatch.nim

Co-authored-by: Danil Yarantsev <tiberiumk12@gmail.com>
Co-authored-by: flywind <xzsflywind@gmail.com>
Co-authored-by: Dominik Picheta <dominikpicheta@googlemail.com>
This commit is contained in:
huantian 2022-05-02 09:06:57 -07:00 • committed by GitHub
commit 927978345b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 33 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

39
lib/pure/asyncdispatch.nim
View file

@ -123,15 +123,42 @@
## if future.failed: ## if future.failed:
## # Handle exception ## # Handle exception
## ##
##
## Discarding futures ## Discarding futures
## ================== ## ==================
## ##
## Futures should **never** be discarded. This is because they may contain ## 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 ## errors. If you do not care for the result of a Future then you should use
## use the `asyncCheck` procedure instead of the `discard` keyword. Note ## the `asyncCheck` procedure instead of the `discard` keyword. Note that this
## however that this does not wait for completion, and you should use ## does not wait for completion, and you should use `waitFor` or `await` for that purpose.
## `waitFor` 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 ## Examples
## ======== ## ========