Document the nature of the main future

[huntc]

Fixes #5446

[huntc]

I suspect failing on an unrelated issue???

[satakuma]

CI failure is unrelated and should be fixed soon.

I think it would be easier to understand if we also included an example basically saying “do X instead of Y”, with X and Y being something like your examples from the linked issue, which show how to improve performance. Such example could be then placed in the module level documentation of tokio::runtime and linked from docs for the main macro and block_on function.

[huntc]

I think it would be easier to understand if we also included an example basically saying “do X instead of Y”, with X and Y being something like your examples from the linked issue, which show how to improve performance. Such example could be then placed in the module level documentation of tokio::runtime and linked from docs for the main macro and block_on function.

I get what you mean, but it isn't easy to change the existing examples due to the following error not being Send:

error[E0277]: `dyn std::error::Error` cannot be sent between threads safely

I'd rather not see the existing module-level samples change that much.

[satakuma]

I agree that it's better to leave the existing examples unchanged, I apologize for not being clear. I wondered if we could create a new section in the module-level docs and put a pair of new examples there. The goal of new examples would be to visualize that code with busy loops like this:

rt.block_on(async move {
    while let Some(msg) = rx.recv().await { ... }
});

should be transformed to this:

rt.block_on(async move {
    let handle = tokio::spawn(async move {
        while let Some(msg) = rx.recv().await { ... }
    });
    handle.await.unwrap();
});

That said, I don't think it will be easy to explain why the latter is preferable without going into too much detail. As far as I can tell from the discussion, performance can degrade if we cross a thread boundary with many channel messages. It means that the transformation above does not really apply to every busy loop, for example it does not apply to the one from the existing samples, which waits for an IO resource. This might be confusing without a detailed explanation of how Tokio's runtime works, and such explanation can quickly get outdated anyway.

I think the additions from this PR should be fine. Maybe in the future Tokio will get a page dedicated to benchmarking with more detailed examples.

[Darksonn]

Thanks!