Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Recommend alternatives to SyncIoBridge #6795

Open
6 tasks
Darksonn opened this issue Aug 20, 2024 · 6 comments
Open
6 tasks

Recommend alternatives to SyncIoBridge #6795

Darksonn opened this issue Aug 20, 2024 · 6 comments
Labels
A-tokio-util Area: The tokio-util crate C-bug Category: This is a bug. E-help-wanted Call for participation: Help is requested to fix this issue. M-io Module: tokio/io T-docs Topic: documentation

Comments

@Darksonn
Copy link
Contributor

Darksonn commented Aug 20, 2024

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.

@Darksonn Darksonn added E-help-wanted Call for participation: Help is requested to fix this issue. T-docs Topic: documentation A-tokio-util Area: The tokio-util crate M-io Module: tokio/io C-bug Category: This is a bug. labels Aug 20, 2024
@lixiang365
Copy link

lixiang365 commented Aug 23, 2024

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
Copy link
Contributor Author

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
Copy link

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

@lixiang365
Copy link

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

@Nathy-bajo
Copy link

Hello @Darksonn
I dropped a PR on this. #6815
Please can you check on it? I want to know if there is anything else needed to add.

@Darksonn
Copy link
Contributor Author

Darksonn commented Sep 3, 2024

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-tokio-util Area: The tokio-util crate C-bug Category: This is a bug. E-help-wanted Call for participation: Help is requested to fix this issue. M-io Module: tokio/io T-docs Topic: documentation
Projects
None yet
Development

No branches or pull requests

3 participants