Recommend alternatives to SyncIoBridge

[Darksonn]

Often when people try to use SyncIoBridge, there is a better alternative. We should improve the documentation to explain this and provide some alternatives. We should also provide an example of how to use it correctly with spawn_blocking.

As an example, if you wish to hash some data with blake3, then you should not do this:

let hasher = blake3::Hasher::new();
let reader = SyncIoBridge::new(reader);
std::io::copy(&mut reader, &mut hasher)?;
let hash = hasher.finalize();

instead you should do this:

let mut data = Vec::new();
reader.read_to_end(&mut data).await?;
let hash = blake3::hash(&data);

or this:

let mut data = vec![0; 64*1024];
loop {
    let len = reader.read(&mut data).await?;
    if len == 0 { break; }
    hasher.update(&data[..len]);
}
let hash = hasher.finalize();

Here are some ways we can improve the documentation:

• [ ] Explain how to compute a hash of some data correctly. (as above)
• [ ] Explain how to compress a stream of data correctly. (use async-compression and don't pass a SyncIoBridge to a non-async compression library)
• [ ] Explain how to parse data using serde-json correctly. (read data into a Vec<u8> and use from_slice instead of attempting to use from_reader with SyncIoBridge)
• [ ] When doing things with files, you probably want to use std::fs inside spawn_blocking instead of combining tokio::fs::File with SyncIoBridge. (see tokio::fs module docs)
• [ ] Example of correct usage of SyncIoBridge inside spawn_blocking.
• [ ] Add links to the above in other relevant places. For example tokio::io::copy could use a note about this, since people often look here.

Once we've added the examples to SyncIoBridge, we will probably copy them into a new topic page.

This is a good first issue. Contact me for mentoring. I'm also open to other examples than the ones I mentioned; they're just my ideas. It is perfectly okay to submit a PR that only partially resolves this issue, e.g. by adding just one example.

[lixiang365]

I am a beginner in open source contributions and am very interested in Tokio. I think the issue is not particularly complex, mainly involving documentation improvements. Could you guide me through making my first contribution to an open source project? @Darksonn

[Darksonn]

Yes. Please contact me through our discord server. You can also reach out via my email address in my github profile if that doesn't work for you.

[Nathy-bajo]

Hello @lixiang365 @Darksonn. Is this still unattended? I want to drop a PR and fix this.

[lixiang365]

I've written a few examples and will provide additional explanations. I'll submit it today.It might not be perfect.

[Nathy-bajo]

Hello @Darksonn I dropped a PR on this. https://github.com/tokio-rs/tokio/pull/6815 Please can you check on it? I want to know if there is anything else needed to add.

[Darksonn]

It looks like there are two PRs: #6813 and #6815. I'll have to look over both and decide on a way forward.