Documentation async #12979

juancarlospaco · 2019-12-28T10:20:42Z

Document Async. Only Documentation.
Includes MultiSync, asyncCheck, waitFor, await, etc.
Includes Examples.

🙂

dom96

This doesn't belong in the manual as it's not a language feature, it should probably be in a separate document or in asyncdispatch.

mratsim · 2019-12-30T12:02:02Z

Maybe an async tutorial as well?

juancarlospaco · 2019-12-30T12:26:06Z

I agree with @mratsim that also a Tutorial can be nice,
but Tutorials on asyncdispatch module feels weird and probably hard to discover for new users.

Maybe Tutorials improvement can be part of another PR, to keep diff easy to review and merge.

Araq · 2019-12-30T13:15:05Z

IMHO this should be an async tutorial and the asyncdispatch modules should link to the tutorial.

juancarlospaco · 2019-12-30T14:01:54Z

We all agree on that.
But if you want to close this one close it, one way or another users will not complain for too much Documentation. :P

dom96 · 2019-12-30T14:49:57Z

lib/pure/asyncdispatch.nim

+## .. code-block:: nim
+##   proc example() {.async.} =
+##     echo "asyncCheck Example"
+##
+##   asyncCheck example()


I don't see the point of this example, either remove it or give it a descriptive heading.

dom96 · 2019-12-30T14:59:40Z

lib/pure/asyncdispatch.nim

+## waitFor
+## -------
+##
+## ``waitFor`` is similiar to ``asyncCheck`` but it will wait for the ``Future``.


Suggested change

## ``waitFor`` is similiar to ``asyncCheck`` but it will wait for the ``Future``.

## ``waitFor`` is similar to ``asyncCheck`` but it will wait for the ``Future``.

This is a bad description though. waitFor blocks the current thread and runs the async IO loop until the future finishes, it's not really comparable to asyncCheck.

dom96 · 2019-12-30T15:01:09Z

lib/pure/asyncdispatch.nim

+## ``await`` will wait for the ``Future``, and gives you the contents inside the ``Future``,
+## ``await`` only available inside a function with the ``{.async.}`` or ``{.multisync.}`` Pragmas.
+##
+## The usage and features are the same of ``waitFor`` (mentioned above).


usage is the same, I don't understand what features there are to speak of which are the same.

lib/pure/asyncdispatch.nim

dom96 · 2019-12-30T15:02:39Z

lib/pure/asyncdispatch.nim

+## then the same function can be used on asynchronous *and* synchronous code,
+## you can think of it as a function that is async or sync depending on how you use it.
+##
+## The usage and features are the same of ``{.async.}`` (mentioned above). Example:


again with the "features", that tells the reader nothing and is misleading.

lib/pure/asyncdispatch.nim

dom96 · 2019-12-30T15:03:47Z

lib/pure/asyncdispatch.nim

+##
+##   echo Client().multisync_function() # Sync
+##
+## This is one of the reasons Nim wont use syntax like ``async proc fetch() =`` like other languages,


How is this one of the reasons?

dom96 · 2019-12-30T15:03:56Z

lib/pure/asyncdispatch.nim

+##   echo Client().multisync_function() # Sync
+##
+## This is one of the reasons Nim wont use syntax like ``async proc fetch() =`` like other languages,
+## also you dont have to repeat your procedure twice like ``async proc aio_fetch() =`` and ``proc fetch() =``,


dom96 · 2019-12-30T15:04:20Z

lib/pure/asyncdispatch.nim

+##     Client = HttpClient
+##     AsyncClient = AsyncHttpClient
+##
+##   proc multisync_function(this: Client | AsyncClient): Future[string] {.multisync.} =


camelCase is the convention

treeform · 2020-01-11T02:02:55Z

lib/pure/asyncdispatch.nim

+## ================================ ============ ========= =======
+## Waits for the Future to complete  No           Yes       Yes
+## Ignores the Future                Yes          No        No
+## Returns result inside Future      No           No        Yes


"Returns result inside Future" waitFor should be yes?

Example:

import asyncdispatch proc foo(): Future[int] {.async.} = return 42 echo waitFor foo()

treeform · 2020-01-11T02:13:32Z

I really like this. I wish this was there when I started to learn about async. The async only clicked for me when I learned that:

asyncCheck - is like spawn in other languages - it starts a new async-thread and branches execution.
waitFor and await - are basically same thing, one you use inside async code the other one you use outside async code. If compiler complains just switch one to the other :)

Off-topic, but if it was up to me I would:

Rename asyncCheck -> spawn
Make await act like waitFor when outside {.async.} functions
Wrap result in a Future automatically when using {.async.}

juancarlospaco · 2020-01-11T20:30:23Z

...but it does wrap the result on a Future, even if you do not declare an explicit return it returns Future[void]. 🤔

disruptek · 2020-01-11T23:30:24Z

return wraps its argument but result is always Future.

treeform · 2020-01-12T00:15:04Z

Sorry I meant do that in the definitions of the proc. I know it does that on the actual return, I wish it would do that in the signature as well to match.

…

On Sat, Jan 11, 2020, 3:30 PM Andy Davidoff ***@***.***> wrote: return wraps its argument but result is always Future. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#12979?email_source=notifications&email_token=AAA6X7DCRESLFDCZD6JHMT3Q5JJBBA5CNFSM4KAKLK22YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEIWNOJQ#issuecomment-573364006>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAA6X7BKCSV4QKGCZMKSMNLQ5JJBBANCNFSM4KAKLK2Q> .

disruptek · 2020-01-12T06:40:42Z

The problem with that, assuming you didn't have the burden of code in the wild, is that it's hiding even more magic. I wish return behaved as expected, instead.

treeform · 2020-01-12T16:14:55Z

It is too late to change how {.async.} works now. Sorry for derailing the discussion. I think the docs are good.

narimiran · 2020-01-23T07:11:32Z

This doesn't belong in the manual as it's not a language feature, it should probably be in a separate document

Maybe an async tutorial as well?

IMHO this should be an async tutorial and the asyncdispatch modules should link to the tutorial.

We all agree on that.

So, if we all agree on that, can we close this PR and use its content as a basis for doc/tut4.rst, which will be async tutorial?

juancarlospaco · 2020-01-23T09:26:00Z

Feel free to close if is the way forward.

narimiran · 2020-01-23T11:26:20Z

Feel free to close if is the way forward.

I think it is. Now waiting for your async tutorial :)

ringabout · 2020-11-23T09:35:24Z

What's the progress of this tutorial?

Araq · 2020-11-23T14:56:30Z

We don't have a tutorial so we should take the doc improvements. Please continue your work @juancarlospaco !

ringabout · 2020-11-23T15:01:24Z

This also fixes #5021

ringabout · 2022-05-02T16:10:39Z

Succeeded by #19738

juancarlospaco added 4 commits December 28, 2019 07:08

Documentation Async

baa2880

Documentation Async

bf743c3

Documentation Async

5f610a4

Documentation Async

35a3f09

dom96 requested changes Dec 28, 2019

View reviewed changes

Peer Review Feedback #12979 (review)

55d13f7

juancarlospaco requested a review from dom96 December 28, 2019 17:43

dom96 requested changes Dec 30, 2019

View reviewed changes

juancarlospaco added 2 commits December 30, 2019 12:43

Peer Review Feedbacks

bce426d

Merge branch 'devel' of https://github.com/nim-lang/Nim into docs-async

48f2e06

treeform reviewed Jan 11, 2020

View reviewed changes

narimiran closed this Jan 23, 2020

timotheecour mentioned this pull request Mar 30, 2020

misc issues timotheecour/Nim#6

Open

1 task

Araq reopened this Nov 23, 2020

juancarlospaco closed this Dec 11, 2020

timotheecour added the stale Staled PR/issues; remove the label after fixing them label Dec 12, 2020

ringabout removed the stale Staled PR/issues; remove the label after fixing them label May 2, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation async #12979

Documentation async #12979

juancarlospaco commented Dec 28, 2019

dom96 left a comment

mratsim commented Dec 30, 2019

juancarlospaco commented Dec 30, 2019

Araq commented Dec 30, 2019

juancarlospaco commented Dec 30, 2019

dom96 Dec 30, 2019

dom96 Dec 30, 2019

dom96 Dec 30, 2019

dom96 Dec 30, 2019

dom96 Dec 30, 2019

dom96 Dec 30, 2019

dom96 Dec 30, 2019

dom96 Dec 30, 2019

dom96 Dec 30, 2019

treeform Jan 11, 2020

treeform commented Jan 11, 2020

juancarlospaco commented Jan 11, 2020

disruptek commented Jan 11, 2020

treeform commented Jan 12, 2020 via email

disruptek commented Jan 12, 2020

treeform commented Jan 12, 2020

narimiran commented Jan 23, 2020

juancarlospaco commented Jan 23, 2020

narimiran commented Jan 23, 2020

ringabout commented Nov 23, 2020

Araq commented Nov 23, 2020

ringabout commented Nov 23, 2020

ringabout commented May 2, 2022

	## ``waitFor`` is similiar to ``asyncCheck`` but it will wait for the ``Future``.
	## ``waitFor`` is similar to ``asyncCheck`` but it will wait for the ``Future``.

Documentation async #12979

Documentation async #12979

Conversation

juancarlospaco commented Dec 28, 2019

dom96 left a comment

Choose a reason for hiding this comment

mratsim commented Dec 30, 2019

juancarlospaco commented Dec 30, 2019

Araq commented Dec 30, 2019

juancarlospaco commented Dec 30, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

treeform commented Jan 11, 2020

juancarlospaco commented Jan 11, 2020

disruptek commented Jan 11, 2020

treeform commented Jan 12, 2020 via email

disruptek commented Jan 12, 2020

treeform commented Jan 12, 2020

narimiran commented Jan 23, 2020

juancarlospaco commented Jan 23, 2020

narimiran commented Jan 23, 2020

ringabout commented Nov 23, 2020

Araq commented Nov 23, 2020

ringabout commented Nov 23, 2020

ringabout commented May 2, 2022