PR submitted! Thanks for the encouragement https://github.com/elixir-lang/elixir/pull/10359

I think it could be better worded as “when you’re using tasks only for the side effects”. The ordered key will not make side effects occur in the order of the enumerable, it’ll only affect the returned stream. Side effects will always occur when the task is processed, so if you need to rely on side effect order you should use Enum.each or Enum.map. As you point out, with ordered: false, there’s no need to buffer the results. So the docs are saying basically if you’re going to pipe Task.async_stream into Enum.each, you should use ordered: false.

I don’t know why they mention side effects in the docs. Seems to me those could be sensitive to ordering. It really all depends on your algorithm whether the order of the results is important to preserve.

If you have ordered: true but the tasks complete in order of b, a, c, then the internal logic has to buffer the result of b, wait for a to finish, send a’s result downstream, then it sends the buffered b’s response, etc.

If your algorithm can operate correctly with ordered: false I would recommend it, no matter the size of the stream or side-effects.

Both of your points are great, PR to the docs are appreciated.

I’ve never had the chance to submit a pr to the docs, this seems like a great opportunity! I’ll get on that today