Async F# Article Re-architecting.

[cartermp]

I'm not really happy with how I wrote this a while back. While it gets some necessary information across, it is misleading, the section comparing to C#/VB is unnecessary, and the article doesn't describe what's going on under the covers at all. There's also nothing about using MailboxProcessor<'T>, but it's a critical sibling component of the language that deserves mentioning here. It should also get its own article for teaching how to do concurrent programming in F#, but that's another issue. Here's what I'm thinking as an outline:

1. Start with the motivation - why write async code? Why in F#?
2. Explain the three core components: Async<'T>, async as a special kind of computation expression, and the Async starting functions.
3. Simple example.
4. Example combining workflows.
5. Parallel example.
6. Example showing interop with Task, and Task<T>.
7. Explain what's going on under the covers:
   • What does the compiler transform the async workflow into?
   • How is work scheduled on a thread? How are callbacks handled?
   • What do each of the starting functions do?
   • Thread trampolining to handle tons of calls that aren't taken as tailcalls by the runtime. What, why, and how?
8. An aside on Agents and why they matter when writing asynchronous code. Link to alternative documentation for now, since we don't have anything official.

[pr-yemibedu]

Hello, Please have point (1.) described under the level up article here: https://docs.microsoft.com/en-us/dotnet/articles/fsharp/tutorials/asynchronous-and-concurrent-programming/

Please do not put anything about Agents (or the MailboxProcessor) on the async side beyond stating that "There is an alternative concurrency model using Agents." with its explanation left in another page preferably: https://docs.microsoft.com/en-us/dotnet/articles/fsharp/tutorials/asynchronous-and-concurrent-programming/agents

Please put anything of summary about agents in the parent link and leave the meat of it for the subordinate article. This will leave a nice structure that people can focus on and absorb step-wise without side stepping and mixing up concepts and strategies.

The C# VB stuff is an article in its own right. You can elaborate and possibly include other CLR languages or the relationship with other runtimes with a similar or contrasting model (like Erlang/Elixir, Java, GoLang, Rust, etc.) A third link could be: https://docs.microsoft.com/en-us/dotnet/articles/fsharp/tutorials/asynchronous-and-concurrent-programming/comparisons

The F# articles are much appreciated. Thank you. Good day.

[schwack]

So, a year and a half later, how relevant is the notice in the book? "Some inaccuracies have been discovered in this article. It is being rewritten. See Issue #666 to learn about the changes."

Is ' inaccuracies' appropriate? The last thing I think anyone wants is to learn ' inaccurate' information, but it sounds like that is not actually the case. Obviously rewriting the article is not a priority, so perhaps editing the note would be more appropriate.

[mairaw]

@cartermp can you comment on this? The sample code also seems not to work on this topic.

[Ytrog]

As someone with a C# background with an Interest in F# I would like to see more info about the difference between the async/await (or Task.ContinueWith) and async in F#.

[Jarak-Jakar]

Was discussing the first example from this page on the F# Foundation's Slack (starting at here) with a couple of other people - someone was trying it out and it wasn't working for them, as the AsyncDownloadString method on WebClient didn't seem to exist. We eventually found it at this page, which apparently shows that it's a Visual F#-only extension method. This person was running .NET Core on Ubuntu. I think it's only an issue because the example pre-dates .NET Core, but it might be good to update the example, and/or highlight that it uses a Visual F#-specific feature :)

[cartermp]

9648 is a WIP that addresses the original issue and the samples issue mentioned by @Jarak-Jakar. @Ytrog, I'll see what I can do about a C# comparison, but I do view that as a secondary priority. I want to make sure the article conveys the right things from an F# perspective before diving into C# comparisons.

[gusennan]

Just reading the F# docs now, and it's apparent that #9648 never was merged in and deployed. Would it still be considered "in-progress?"

[cartermp]

@gusennan Yes, it's in progress.

[OmanF]

2019... Just copy-pasted the first, top-most, code snippet into both Rider and VSCode. Rider recognizes, and color-codes webClient.AsyncDownloadString(uri). VSCode, on the other hand, immediately red-squiggles it.

Sending both snippets to FSI though gives the same result: an error, ...AsyncDownloadString is not defined. Maybe you mean DownloadString.

Rider:

VSCode:

[pr-yemibedu]

Hello @OmanF , I wonder if there is not a proper reference to so FSharp library as the method you show is an extension method. Maybe you need more than just core Fsharp sytnax highlighting enabled? https://msdn.microsoft.com/visualfsharpdocs/conceptual/webclient.asyncdownloadstring-extension-method-%5bfsharp%5d mentions it is not something out of the box and Rider may be doing a little heavy lifting behind the scenes for you.

Please share with us the Extensions you have installed. Since FSI in both complains too, you may need to add an "#INCLUDE" directive at the top of the file. Let us know. Thank you. Good day.

[OmanF]

I think I got what was the issue: the underlying extension method does say on its page that the supported .Net version are 2 and 4, I'm guessing Core/Standard and Framework, respectively (might want to make that more clear on that page as well).

My initial run was with FSharp.Core 4.6.2 which runs .Net standard 1.6. Had to upgrade to 4.7 and everything works fine, FSI included.

So, as for the documentation, may I propose that you add the .Net requirements to the Async Programming page as well, preferably in a red, bold, box like the one that led me to this PR. Better yet would be to include a sentence about FSharp.Core only being compatible starting 4.7.

[pr-yemibedu]

Hello, I agree that the examples that are created should be tested with the .Net Framework, .Net Core, and Xamarin for library availability and compatibility. Labeled notes below examples should be used to indicate such testing to the reader. Possibly noting if "FSI" is directly ready to handle the code or would need any #Inlcudes or #references. So a "using Fsharp.Core 4.0.0.1 and 4.7.0 with .Net Framework 4.5 or Fsharp.Core 4.2.1 with .Net Standard 1.6 (#reference Fsharp.Data) ", would let them know to how the snippets were tested.

The landscape of those technologies being developed alongside the language and its libraries are well likely to have edge cases and possible breakage from using the wrong version of something. It would help newcomers in quickly troubleshooting issues, it something like in the above paragraph was considered. Doesn't have to be extensive, just helpful in recruiting developers and easing difficulties. Thank you. Good day.