sync: elaborate on unbounded send not being async #2600

Darksonn · 2020-06-10T08:57:54Z

I keep seeing people being confused about the unbounded send method not being async, and thinking that our channels are actually blocking. I hope that this snippet improves on this.

Darksonn · 2020-06-10T09:20:19Z

It seems like the macos CI fix didn't work? @taiki-e

hawkw

This looks good to me!

What do you think about also adding a similar note in the top-level docs for mpsc? We mention the existence of the unbounded channel here:

tokio/tokio/src/sync/mpsc/mod.rs

Lines 13 to 14 in 44f45bd

    
           //! Unbounded channels are also available using the `unbounded_channel` 
        
           //! constructor.

but never really explain what that means. It might be helpful for new users to highlight the key difference between the bounded and unbounded channel's APIs?

tokio/src/sync/mpsc/unbounded.rs

taiki-e · 2020-06-10T19:04:33Z

It seems like the macos CI fix didn't work?

Oops, It seems I've only fixed the azure pipelines.
It should be fixed in #2602.

…blocking

hawkw

Thanks for adding to the module level docs! I had some minor suggestions, but they aren't blockers.

tokio/src/sync/mpsc/mod.rs

hawkw · 2020-06-10T21:44:03Z

tokio/src/sync/mpsc/mod.rs

+//! **Bounded channel**: If you need a bounded channel, you should use a bounded
+//! Tokio mpsc channel for both directions of communication. To call the async
+//! [`send`][bounded-send] or [`recv`][bounded-recv] methods in sync code, you
+//! should use [`Handle::block_on`].


Maybe something like:

Suggested change

//! should use [`Handle::block_on`].

//! should use [`Handle::block_on`]. This is because the sender must be able to wait

//! for additional capacity when the channel is full. `Handle::block_on` allows a

//! synchronous caller to wait on an `async fn`.

(in general, I want to make sure all docs that state "you should do X" also explain why you should do that)

tokio/src/sync/mpsc/mod.rs

Darksonn · 2020-06-11T08:47:53Z

I added a similar comment to the oneshot channel.

hawkw

looks good to me! i had a few nits.

hawkw · 2020-06-17T20:14:07Z

tokio/src/sync/mpsc/mod.rs

@@ -10,8 +10,13 @@
 //! is rejected and the task will be notified when additional capacity is
 //! available. In other words, the channel provides backpressure.
 //!
-//! Unbounded channels are also available using the `unbounded_channel`
-//! constructor.
+//! This module provides two variants of the channel: A bounded and an unbounded


nit:

Suggested change

//! This module provides two variants of the channel: A bounded and an unbounded

//! This module provides two variants of the channel: a bounded and an unbounded

hawkw · 2020-06-17T20:14:50Z

tokio/src/sync/mpsc/mod.rs

+//! This module provides two variants of the channel: A bounded and an unbounded
+//! variant. The bounded variant has a limit on the number of messages that the


also, how about just

Suggested change

//! This module provides two variants of the channel: A bounded and an unbounded

//! variant. The bounded variant has a limit on the number of messages that the

//! This module provides two variants of the channel: bounded and unbounded.

//! The bounded variant has a limit on the number of messages that the

hawkw · 2020-06-17T20:15:52Z

tokio/src/sync/mpsc/mod.rs

+//! This module provides two variants of the channel: A bounded and an unbounded
+//! variant. The bounded variant has a limit on the number of messages that the
+//! channel can store, and if this limit is reached, trying to send another
+//! message will sleep until a message is received from the channel. An unbounded


Maybe

Suggested change

//! message will sleep until a message is received from the channel. An unbounded

//! message will wait until a message is received from the channel. An unbounded

rather than "sleep", for consistency?

- docs: misc improvements (#2572, #2658, #2663, #2656, #2647, #2630, #2487, #2621, #2624, #2600, #2623, #2622, #2577, #2569, #2589, #2575, #2540, #2564, #2567, #2520, #2521, #2572, #2493) - rt: allow calls to `block_on` inside calls to `block_in_place` that are themselves inside `block_on` (#2645) - net: fix non-portable behavior when dropping `TcpStream` `OwnedWriteHalf` (#2597) - io: improve stack usage by allocating large buffers on directly on the heap (#2634) - io: fix unsound pin projection in `AsyncReadExt::read_buf` and `AsyncWriteExt::write_buf` (#2612) - io: fix unnecessary zeroing for `AsyncRead` implementors (#2525) - io: Fix `BufReader` not correctly forwarding `poll_write_buf` (#2654) - coop: returning `Poll::Pending` no longer decrements the task budget (#2549) - io: little-endian variants of `AsyncReadExt` and `AsyncWriteExt` methods (#1915) - io: fix panic in `AsyncReadExt::read_line` (#2541) - task: add [`tracing`] instrumentation to spawned tasks (#2655) - sync: allow unsized types in `Mutex` and `RwLock` (via `default` constructors) (#2615) - net: add `ToSocketAddrs` implementation for `&[SocketAddr]` (#2604) - fs: add `OpenOptionsExt` for `OpenOptions` (#2515) - fs: add `DirBuilder` (#2524) [`tracing`]: https://crates.io/crates/tracing Signed-off-by: Eliza Weisman <eliza@buoyant.io>

# 0.2.22 (July 2!, 2020) ### Fixes - docs: misc improvements (#2572, #2658, #2663, #2656, #2647, #2630, #2487, #2621, #2624, #2600, #2623, #2622, #2577, #2569, #2589, #2575, #2540, #2564, #2567, #2520, #2521, #2493) - rt: allow calls to `block_on` inside calls to `block_in_place` that are themselves inside `block_on` (#2645) - net: fix non-portable behavior when dropping `TcpStream` `OwnedWriteHalf` (#2597) - io: improve stack usage by allocating large buffers on directly on the heap (#2634) - io: fix unsound pin projection in `AsyncReadExt::read_buf` and `AsyncWriteExt::write_buf` (#2612) - io: fix unnecessary zeroing for `AsyncRead` implementors (#2525) - io: Fix `BufReader` not correctly forwarding `poll_write_buf` (#2654) - io: fix panic in `AsyncReadExt::read_line` (#2541) ### Changes - coop: returning `Poll::Pending` no longer decrements the task budget (#2549) ### Added - io: little-endian variants of `AsyncReadExt` and `AsyncWriteExt` methods (#1915) - task: add [`tracing`] instrumentation to spawned tasks (#2655) - sync: allow unsized types in `Mutex` and `RwLock` (via `default` constructors) (#2615) - net: add `ToSocketAddrs` implementation for `&[SocketAddr]` (#2604) - fs: add `OpenOptionsExt` for `OpenOptions` (#2515) - fs: add `DirBuilder` (#2524) [`tracing`]: https://crates.io/crates/tracing Signed-off-by: Eliza Weisman <eliza@buoyant.io>

sync: elaborate on unbounded send not being async

44f45bd

Darksonn added T-docs Topic: documentation C-maintenance Category: PRs that clean code up or issues documenting cleanup. A-tokio Area: The main tokio crate M-sync Module: tokio/sync labels Jun 10, 2020

Darksonn self-assigned this Jun 10, 2020

hawkw approved these changes Jun 10, 2020

View reviewed changes

tokio/src/sync/mpsc/unbounded.rs Show resolved Hide resolved

Darksonn added 2 commits June 10, 2020 22:56

Merge remote-tracking branch 'upstream/master' into unbounded-is-not-…

0351dd7

…blocking

more unbounded channel doc

2dae08b

Darksonn requested a review from hawkw June 10, 2020 21:29

hawkw approved these changes Jun 10, 2020

View reviewed changes

more channel doc

8e5c9b6

Darksonn requested a review from hawkw June 11, 2020 08:47

Darksonn merged commit 3db22e2 into tokio-rs:master Jun 17, 2020

Darksonn deleted the unbounded-is-not-blocking branch June 17, 2020 20:15

hawkw approved these changes Jun 17, 2020

View reviewed changes

Darksonn mentioned this pull request Jun 17, 2020

Channel documentation update #2624

Merged

hawkw mentioned this pull request Jul 1, 2020

Document how to use channels between async and sync #2495

Closed

hawkw mentioned this pull request Jul 20, 2020

chore: prepare to release 0.2.22 #2672

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

sync: elaborate on unbounded send not being async #2600

sync: elaborate on unbounded send not being async #2600

Darksonn commented Jun 10, 2020

Darksonn commented Jun 10, 2020

hawkw left a comment

taiki-e commented Jun 10, 2020

hawkw left a comment

hawkw Jun 10, 2020

Darksonn commented Jun 11, 2020

hawkw left a comment

hawkw Jun 17, 2020

hawkw Jun 17, 2020

hawkw Jun 17, 2020

	//! Unbounded channels are also available using the `unbounded_channel`
	//! constructor.

-//! should use [`Handle::block_on`].
+//! should use [`Handle::block_on`]. This is because the sender must be able to wait
+//! for additional capacity when the channel is full. `Handle::block_on` allows a
+//! synchronous caller to wait on an `async fn`.

	//! This module provides two variants of the channel: A bounded and an unbounded
	//! This module provides two variants of the channel: a bounded and an unbounded

		//! This module provides two variants of the channel: A bounded and an unbounded
		//! variant. The bounded variant has a limit on the number of messages that the

	//! message will sleep until a message is received from the channel. An unbounded
	//! message will wait until a message is received from the channel. An unbounded

sync: elaborate on unbounded send not being async #2600

sync: elaborate on unbounded send not being async #2600

Conversation

Darksonn commented Jun 10, 2020

Darksonn commented Jun 10, 2020

hawkw left a comment

Choose a reason for hiding this comment

taiki-e commented Jun 10, 2020

hawkw left a comment

Choose a reason for hiding this comment

hawkw Jun 10, 2020

Choose a reason for hiding this comment

Darksonn commented Jun 11, 2020

hawkw left a comment

Choose a reason for hiding this comment

hawkw Jun 17, 2020

Choose a reason for hiding this comment

hawkw Jun 17, 2020

Choose a reason for hiding this comment

hawkw Jun 17, 2020

Choose a reason for hiding this comment