Description
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
SyncIoBridgeto a non-async compression library) - Explain how to parse data using serde-json correctly. (read data into a
Vec<u8>and usefrom_sliceinstead of attempting to usefrom_readerwithSyncIoBridge) - When doing things with files, you probably want to use
std::fsinsidespawn_blockinginstead of combiningtokio::fs::FilewithSyncIoBridge. (seetokio::fsmodule docs) - Example of correct usage of
SyncIoBridgeinsidespawn_blocking. - Add links to the above in other relevant places. For example
tokio::io::copycould 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.
Activity