Document performance considerations tokio::fs

[Darksonn]

All file operations are currently spawned on a thread pool with spawn_blocking which is rather expensive. We should document these performance considerations a lot better than we are doing now.

Refs: #1976, #1844

[lnicola]

Is it possible to use block_in_place in their implementation? I suppose there's still some value in using tokio-fs, as it might get io_uring support in some nebulous future.

[Darksonn]

Using block_in_place is a massive footgun and will break any code that uses things such as select!, join! or join_all.

[LucioFranco]

We likely want to create a section on the website for this. I am happy to contribute to this one.

[Darksonn]

I opened an issue on the website repository too.

[Lol3rrr]

It seems like this issue is no longer relevant (i think?), as the docs for fs mention that blocking tasks are spawned for the operations

[PaulDotSH]

Using block_in_place is a massive footgun and will break any code that uses things such as select!, join! or join_all.

What about having another API that specifically uses block_in_place, that users can use if they chose to, and that way we will both prevent having a breaking-change that breaks other uses, and both possibly let users benefit from performance improvements

[sfackler]

That seems like a thing you can trivially do yourself with block_in_place and std::fs::File.

[Darksonn]

Closing as fixed by #6467.

Tokio will not encourage use of block_in_place by providing such APIs.