Documentation inconsistency concerning @async

[algunion]

The @async macro documentation includes the following warning:

It is strongly encouraged to favor Threads.@spawn over @async always even when no parallelism is required especially in publicly distributed libraries. This is because a use of @async disables the migration of the parent task across worker threads in the current implementation of Julia. Thus, seemingly innocent use of @async in a library function can have a large impact on the performance of very different parts of user applications.

However, the asynchronous programming piece of the manual presents @async as a legitimate way to do things - and @async is even used in the how-to related to Channels. Take a look here and in general to the asynchronous programming section of the manual.

From the timestamps, it seems that the asynchronous programming section of the manual might be outdated - and is basically suggesting practices that are labeled as to be avoided in other parts of the documentation.

I also opened a topic on discourse, but it didn't grab much attention.

Is the @async/@swap warning still standing and the manual is to be updated? Or the other way around?

[vchuravy]

The manual needs to be updated.

cc: @carstenbauer since we talked about this recently.