From 72e4f9475a9d21e37ca0e1c52200d289e5c5ebf4 Mon Sep 17 00:00:00 2001 From: Rafael Bachmann Date: Tue, 13 Aug 2024 22:18:12 +0200 Subject: [PATCH] sync: document mpsc channel allocation behavior Co-authored-by: Alice Ryhl Fixes: #6754 --- tokio/src/sync/mpsc/mod.rs | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/tokio/src/sync/mpsc/mod.rs b/tokio/src/sync/mpsc/mod.rs index 052620be1a9..e6601e90a4a 100644 --- a/tokio/src/sync/mpsc/mod.rs +++ b/tokio/src/sync/mpsc/mod.rs @@ -78,6 +78,22 @@ //! within a Tokio runtime, however it is still not tied to one specific Tokio //! runtime, and the sender may be moved from one Tokio runtime to another. //! +//! # Allocation behavior +//! +//!
The implementation details described in this section may change in future +//! Tokio releases.
+//! +//! The mpsc channel stores elements in blocks. Blocks are organized in a linked list. Sending +//! pushes new elements onto the block at the front of the list, and receiving pops them off the +//! one at the back. A block can hold 32 messages on a 64-bit target and 16 messages on a 32-bit +//! target. This number is independent of channel and message size. Each block also stores 4 +//! pointer-sized values for bookkeeping (so on a 64-bit machine, each message has 1 byte of +//! overhead). +//! +//! When all values in a block have been received, it becomes empty. It will then be freed, unless +//! the channel's first block (where newly-sent elements are being stored) has no next block. In +//! that case, the empty block is reused as the next block. +//! //! [`Sender`]: crate::sync::mpsc::Sender //! [`Receiver`]: crate::sync::mpsc::Receiver //! [bounded-send]: crate::sync::mpsc::Sender::send()