When to use different block_on functions?

[ThatGeoGuy]

In smol, as of v2.0.0, there are three block_on functions:

• smol::block_on
• smol::future::block_on
• smol::stream::block_on

Of the three, smol::stream::block_on is the most obvious in my mind in terms of "when do I use this?" — If I need an iterator from something that's normally a stream, smol::stream::block_on is great.

What I don't understand, is when to use smol::block_on (technically async_io::block_on) vs. smol::futures::block_on (technically futures_lite::block_on).

The documentation here is fairly sparse (the core difference being "processing I/O events when idle" or not), but that doesn't give me a good intuition on when each block_on call would be best utilized.

The executor docs use future::block_on, but how would I know if there are IO events that might be necessary for my block_on to not get stalled?

[notgull]

Really there is no difference. smol::block_on sets up the thread to run the I/O reactor while smol::future::block_on doesn't. However, the I/O reactor can run on its own thread even if smol::block_on isn't running. So functionally there is no difference.

If you care about benchmarks, smol::future::block_on is slightly faster to run if you are blocking on a lot of little futures. So in general I use smol::block_on for long-running futures and smol::future::block_on if I have to block on a tiny one.

If you can't decide it can't hurt to just use smol::block_on.

[ThatGeoGuy]

Thanks! I suppose I often don't know if the I/O reactor is running, or if it should be, so maybe smol::block_on is a better default unless I know better and am avoiding I/O entirely.