docs(ThingBuf): queue types docs & API polish (#28)

Signed-off-by: Eliza Weisman <eliza@buoyant.io>

README.md

@@ -10,7 +10,7 @@ to slots in the buffer by reference. It's also [asynchronous][`thingbuf::mpsc`]
 and [blocking][`thingbuf::mpsc::sync`] bounded MPSC channels implemented using
 the ring buffer.
 
-## When Should I Use It?
+### When Should I Use It?
 
 - **If you want a high-throughput bounded MPSC channel** that allocates only on
   channel creation. Some MPSC channels have good throughput. Some other MPSC
@@ -38,7 +38,7 @@ the ring buffer.
   than switching between separate `std` and `#![no_std]` channel
   implementations.
 
-## When *Shouldn't* I Use It?
+### When *Shouldn't* I Use It?
 
 It's equally important to discuss when `thingbuf` should *not* be used. Here are
 some cases where you might be better off considering other options:
@@ -65,6 +65,29 @@ some cases where you might be better off considering other options:
 - **You want an unbounded channel**. I'm not going to write an unbounded
   channel. Unbounded channels are evil.
 
+## Terminology
+
+This crate's API and documentation makes a distinction between the terms "queue"
+and "channel". The term _queue_ will refer to the [queue abstract data
+type][q-adt] in general — any first-in, first-out data structure is a
+queue.
+
+The term _channel_ will refer to a subtype of concurrent queue that also
+functions as a synchronization primitive. A channel is a queue which can be
+shared between multiple threads or asynchronous tasks, and which allows those
+threads or tasks to wait for elements to be added or removed from the queue.
+
+In the Rust standard library, the [`std::collections::VecDeque`] type
+is an example of a queue that is not a channel: it is a first-in, first-out data
+structure, but it cannot be concurrently enqueued to and dequeued from by
+multiple threads or tasks. In comparison, the types in the [`std::sync::mpsc`]
+module provide a prototypical example of channels, as they serve as
+synchronization primitives for cross-thread communication.
+
+[q-adt]: https://en.wikipedia.org/wiki/Queue_(abstract_data_type)
+[`std::collections::VecDeque`]: https://doc.rust-lang.org/stable/std/collections/struct.VecDeque.html
+[`std::sync::mpsc`]: https://doc.rust-lang.org/stable/std/sync/mpsc/index.html
+
 ## Usage
 
 To get started using `thingbuf`, add the following to your `Cargo.toml`:

src/lib.rs

@@ -47,7 +47,7 @@ pub struct Ref<'slot, T> {
 }
 
 /// Error returned when sending a message failed because a channel is at capacity.
-
+#[derive(Eq, PartialEq)]
 pub struct Full<T = ()>(T);
 
 /// State variables for the atomic ring buffer algorithm.

src/static_thingbuf.rs

@@ -1,7 +1,194 @@
 use crate::loom::atomic::Ordering;
 use crate::{Core, Full, Ref, Slot};
-use core::{fmt, ptr};
+use core::{fmt, mem, ptr};
 
+/// A statically allocated, fixed-size lock-free multi-producer multi-consumer
+/// queue.
+///
+/// This type is identical to the [`ThingBuf`] type, except that the queue's
+/// capacity is controlled by a const generic parameter, rather than dynamically
+/// allocated at runtime. This means that a `StaticThingBuf` can be used without
+/// requiring heap allocation, and can be stored in a `static`.
+///
+/// `StaticThingBuf` will likely be particularly useful for embedded systems,
+/// bare-metal code like operating system kernels or device drivers, and other
+/// contexts where allocations may not be available. It can also be used to
+/// implement a global queue that lives for the entire lifespan of a program,
+/// without having to pass around reference-counted [`std::sync::Arc`] pointers.
+///
+/// # Examples
+///
+/// Storing a `StaticThingBuf` in a `static`:
+///
+/// ```rust
+/// use thingbuf::StaticThingBuf;
+///
+/// static MY_THINGBUF: StaticThingBuf<i32, 8> = StaticThingBuf::new();
+///
+/// fn main() {
+///     assert_eq!(MY_THINGBUF.push(1), Ok(()));
+///     assert_eq!(MY_THINGBUF.pop(), Some(1));
+/// }
+/// ```
+///
+/// Constructing a `StaticThingBuf` on the stack:
+///
+/// ```rust
+/// use thingbuf::StaticThingBuf;
+///
+/// let q = StaticThingBuf::<_, 2>::new();
+///
+/// // Push some values to the queue.
+/// q.push(1).unwrap();
+/// q.push(2).unwrap();
+///
+/// // Now, the queue is at capacity.
+/// assert!(q.push(3).is_err());
+/// ```
+///
+/// # Allocation
+///
+/// A `StaticThingBuf` is a fixed-size, array-based queue. Elements in the queue are
+/// stored in a single array whose capacity is specified at compile time as a
+/// `const` generic parameter. This means that a `StaticThingBuf` requires *no*
+/// heap allocations. Calling [`StaticThingBuf::new`], [`push`] or [`pop`] will
+/// never allocate or deallocate memory.
+///
+/// If the size of the queue is dynamic and not known at compile-time, the [`ThingBuf`]
+/// type, which performs a single heap allocation, can be used instead (provided
+/// that the `alloc` feature flag is enabled).
+///
+/// ## Reusing Allocations
+///
+/// Of course, if the *elements* in the queue are themselves heap-allocated
+/// (such as `String`s or `Vec`s), heap allocations and deallocations may still
+/// occur when those types are created or dropped. However, `StaticThingBuf` also
+/// provides an API for enqueueing and dequeueing elements *by reference*. In
+/// some use cases, this API can be used to reduce allocations for queue elements.
+///
+/// As an example, consider the case where multiple threads in a program format
+/// log messages and send them to a dedicated worker thread that writes those
+/// messages to a file. A naive implementation might look something like this:
+///
+/// ```rust
+/// use thingbuf::StaticThingBuf;
+/// use std::{sync::Arc, fmt, thread, fs::File, error::Error, io::Write};
+///
+/// static LOG_QUEUE: StaticThingBuf<String, 1048> = StaticThingBuf::new();
+///
+/// // Called by application threads to log a message.
+/// fn log_event(message: &dyn fmt::Debug) {
+///     // Format the log line to a `String`.
+///     let line = format!("{:?}\n", message);
+///     // Send the string to the worker thread.
+///     let _ = LOG_QUEUE.push(line);
+///     // If the queue was full, ignore the error and drop the log line.
+/// }
+///
+/// fn main() -> Result<(), Box<dyn Error>> {
+/// # // wrap the actual code in a function that's never called so that running
+/// # // the test never actually creates the log file.
+/// # fn docs() -> Result<(), Box<dyn Error>> {
+///     // Spawn the background worker thread.
+///     let mut file = File::create("myapp.log")?;
+///     thread::spawn(move || {
+///         use std::io::Write;
+///         loop {
+///             // Pop from the queue, and write each log line to the file.
+///             while let Some(line) = LOG_QUEUE.pop() {
+///                 file.write_all(line.as_bytes()).unwrap();
+///             }
+///
+///             // No more messages in the queue!
+///             file.flush().unwrap();
+///             thread::yield_now();
+///         }
+///     });
+///
+///     // ...
+///     # Ok(())
+/// # }
+/// # Ok(())
+/// }
+/// ```
+///
+/// With this design, however, new `String`s are allocated for every message
+/// that's logged, and then are immediately deallocated once they are written to
+/// the file. This can have a negative performance impact.
+///
+/// Using `ThingBuf`'s [`push_ref`] and [`pop_ref`] methods, this code can be
+/// redesigned to _reuse_ `String` allocations in place. With these methods,
+/// rather than moving an element by-value into the queue when enqueueing, we
+/// instead reserve the rights to _mutate_ a slot in the queue in place,
+/// returning a [`Ref`]. Similarly, when dequeueing, we also recieve a [`Ref`]
+/// that allows reading from (and mutating) the dequeued element. This allows
+/// the queue to _own_ the set of `String`s used for formatting log messages,
+/// which are cleared in place and the existing allocation reused.
+///
+/// The rewritten code might look like this:
+///
+/// ```rust
+/// use thingbuf::StaticThingBuf;
+/// use std::{sync::Arc, fmt, thread, fs::File, error::Error};
+///
+/// static LOG_QUEUE: StaticThingBuf<String, 1048> = StaticThingBuf::new();
+///
+/// // Called by application threads to log a message.
+/// fn log_event( message: &dyn fmt::Debug) {
+///     use std::fmt::Write;
+///
+///     // Reserve a slot in the queue to write to.
+///     if let Ok(mut slot) = LOG_QUEUE.push_ref() {
+///         // Clear the string in place, retaining the allocated capacity.
+///         slot.clear();
+///         // Write the log message to the string.
+///         write!(&mut *slot, "{:?}\n", message);
+///     }
+///     // Otherwise, if `push_ref` returns an error, the queue is full;
+///     // ignore this log line.
+/// }
+///
+/// fn main() -> Result<(), Box<dyn Error>> {
+/// # // wrap the actual code in a function that's never called so that running
+/// # // the test never actually creates the log file.
+/// # fn docs() -> Result<(), Box<dyn Error>> {
+///     // Spawn the background worker thread.
+///     let mut file = File::create("myapp.log")?;
+///     thread::spawn(move || {
+///         use std::io::Write;
+///         loop {
+///             // Pop from the queue, and write each log line to the file.
+///             while let Some(line) = LOG_QUEUE.pop_ref() {
+///                 file.write_all(line.as_bytes()).unwrap();
+///             }
+///
+///             // No more messages in the queue!
+///             file.flush().unwrap();
+///             thread::yield_now();
+///         }
+///     });
+///
+///     // ...
+///     # Ok(())
+/// # }
+/// # Ok(())
+/// }
+/// ```
+///
+/// In this implementation, the strings will only be reallocated if their
+/// current capacity is not large enough to store the formatted representation
+/// of the log message.
+///
+/// When using a `ThingBuf` in this manner, it can be thought of as a
+/// combination of a concurrent queue and an [object pool].
+///
+/// [`push`]: Self::push
+/// [`pop`]: Self::pop
+/// [`push_ref`]: Self::push_ref
+/// [`pop_ref`]: Self::pop_ref
+/// [`ThingBuf`]: crate::ThingBuf
+/// [vyukov]: https://www.1024cores.net/home/lock-free-algorithms/queues/bounded-mpmc-queue
+/// [object pool]: https://en.wikipedia.org/wiki/Object_pool_pattern
 pub struct StaticThingBuf<T, const CAP: usize> {
     core: Core,
     slots: [Slot<T>; CAP],
@@ -11,6 +198,7 @@ pub struct StaticThingBuf<T, const CAP: usize> {
 
 #[cfg(not(test))]
 impl<T, const CAP: usize> StaticThingBuf<T, CAP> {
+    /// Returns a new `StaticThingBuf` with space for `capacity` elements.
     pub const fn new() -> Self {
         Self {
             core: Core::new(CAP),
@@ -20,16 +208,95 @@ impl<T, const CAP: usize> StaticThingBuf<T, CAP> {
 }
 
 impl<T, const CAP: usize> StaticThingBuf<T, CAP> {
+    /// Returns the *total* capacity of this queue. This includes both
+    /// occupied and unoccupied entries.
+    ///
+    /// To determine the queue's remaining *unoccupied* capacity, use
+    /// [`remaining`] instead.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use thingbuf::StaticThingBuf;
+    /// static MY_THINGBUF: StaticThingBuf::<usize, 100> = StaticThingBuf::new();
+    ///
+    /// assert_eq!(MY_THINGBUF.capacity(), 100);
+    /// ```
+    ///
+    /// Even after pushing several messages to the queue, the capacity remains
+    /// the same:
+    /// ```
+    /// # use thingbuf::StaticThingBuf;
+    /// static MY_THINGBUF: StaticThingBuf::<usize, 100> = StaticThingBuf::new();
+    ///
+    /// *MY_THINGBUF.push_ref().unwrap() = 1;
+    /// *MY_THINGBUF.push_ref().unwrap() = 2;
+    /// *MY_THINGBUF.push_ref().unwrap() = 3;
+    ///
+    /// assert_eq!(MY_THINGBUF.capacity(), 100);
+    /// ```
+    ///
+    /// [`remaining`]: Self::remaining
     #[inline]
     pub fn capacity(&self) -> usize {
         CAP
     }
 
+    /// Returns the unoccupied capacity of the queue (i.e., how many additional
+    /// elements can be enqueued before the queue will be full).
+    ///
+    /// This is equivalent to subtracting the queue's [`len`] from its [`capacity`].
+    ///
+    /// [`len`]: Self::len
+    /// [`capacity`]: Self::capacity
+    pub fn remaining(&self) -> usize {
+        self.capacity() - self.len()
+    }
+
+    /// Returns the number of elements in the queue
+    ///
+    /// To determine the queue's remaining *unoccupied* capacity, use
+    /// [`remaining`] instead.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use thingbuf::StaticThingBuf;
+    /// static MY_THINGBUF: StaticThingBuf::<usize, 100> = StaticThingBuf::new();
+    ///
+    /// assert_eq!(MY_THINGBUF.len(), 0);
+    ///
+    /// *MY_THINGBUF.push_ref().unwrap() = 1;
+    /// *MY_THINGBUF.push_ref().unwrap() = 2;
+    /// *MY_THINGBUF.push_ref().unwrap() = 3;
+    /// assert_eq!(MY_THINGBUF.len(), 3);
+    ///
+    /// let _ = MY_THINGBUF.pop_ref();
+    /// assert_eq!(MY_THINGBUF.len(), 2);
+    /// ```
+    ///
+    /// [`remaining`]: Self::remaining
     #[inline]
     pub fn len(&self) -> usize {
         self.core.len()
     }
 
+    /// Returns `true` if there are currently no elements in this `StaticThingBuf`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use thingbuf::StaticThingBuf;
+    /// static MY_THINGBUF: StaticThingBuf::<usize, 100> = StaticThingBuf::new();
+    ///
+    /// assert!(MY_THINGBUF.is_empty());
+    ///
+    /// *MY_THINGBUF.push_ref().unwrap() = 1;
+    /// assert!(!MY_THINGBUF.is_empty());
+    ///
+    /// let _ = MY_THINGBUF.pop_ref();
+    /// assert!(MY_THINGBUF.is_empty());
+    /// ```
     #[inline]
     pub fn is_empty(&self) -> bool {
         self.len() == 0
@@ -37,6 +304,82 @@ impl<T, const CAP: usize> StaticThingBuf<T, CAP> {
 }
 
 impl<T: Default, const CAP: usize> StaticThingBuf<T, CAP> {
+    /// Reserves a slot to push an element into the queue, returning a [`Ref`] that
+    /// can be used to write to that slot.
+    ///
+    /// This can be used to reuse allocations for queue elements in place,
+    /// by clearing previous data prior to writing. In order to ensure
+    /// allocations can be reused in place, elements should be dequeued using
+    /// [`pop_ref`] rather than [`pop`]. If values are expensive to produce,
+    /// `push_ref` can also be used to avoid producing a value if there is no
+    /// capacity for it in the queue.
+    ///
+    /// For values that don't own heap allocations, or heap allocated values
+    /// that cannot be reused in place, [`push`] can also be used.
+    ///
+    /// # Returns
+    ///
+    /// - `Ok(`[`Ref`]`)` if there is space for a new element
+    /// - `Err(`[`Full`]`)`, if there is no capacity remaining in the queue
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use thingbuf::StaticThingBuf;
+    ///
+    /// static MY_THINGBUF: StaticThingBuf<i32, 1> = StaticThingBuf::new();
+    ///
+    /// // Reserve a `Ref` and enqueue an element.
+    /// *MY_THINGBUF.push_ref().expect("queue should have capacity") = 10;
+    ///
+    /// // Now that the queue has one element in it, a subsequent `push_ref`
+    /// // call will fail.
+    /// assert!(MY_THINGBUF.push_ref().is_err());
+    /// ```
+    ///
+    /// Avoiding producing an expensive element when the queue is at capacity:
+    ///
+    /// ```rust
+    /// use thingbuf::StaticThingBuf;
+    ///
+    /// static MESSAGES: StaticThingBuf<Message, 16> = StaticThingBuf::new();
+    ///
+    /// #[derive(Default)]
+    /// struct Message {
+    ///     // ...
+    /// }
+    ///
+    /// fn make_expensive_message() -> Message {
+    ///     // Imagine this function performs some costly operation, or acquires
+    ///     // a limited resource...
+    ///     # Message::default()
+    /// }
+    ///
+    /// fn enqueue_message() {
+    ///     loop {
+    ///         match MESSAGES.push_ref() {
+    //              // If `push_ref` returns `Ok`, we've reserved a slot in
+    ///             // the queue for our message, so it's okay to generate
+    ///             // the expensive message.
+    ///             Ok(mut slot) => {
+    ///                 *slot = make_expensive_message();
+    ///                 return;
+    ///             },
+    ///
+    ///             // If there's no space in the queue, avoid generating
+    ///             // an expensive message that won't be sent.
+    ///             Err(_) => {
+    ///                 // Wait until the queue has capacity...
+    ///                 std::thread::yield_now();
+    ///             }
+    ///         }
+    ///     }
+    /// }
+    /// ```
+    ///
+    /// [`pop`]: Self::pop
+    /// [`pop_ref`]: Self::pop_ref
+    /// [`push`]: Self::push_ref
     pub fn push_ref(&self) -> Result<Ref<'_, T>, Full> {
         self.core.push_ref(&self.slots).map_err(|e| match e {
             crate::mpsc::TrySendError::Full(()) => Full(()),
@@ -44,15 +387,99 @@ impl<T: Default, const CAP: usize> StaticThingBuf<T, CAP> {
         })
     }
 
+    /// Attempt to enqueue an element by value.
+    ///
+    /// If the queue is full, the element is returned in the [`Full`] error.
+    ///
+    /// Unlike [`push_ref`], this method does not enable the reuse of previously
+    /// allocated elements. If allocations are being reused by using
+    /// [`push_ref`] and [`pop_ref`], this method should not be used, as it will
+    /// drop pooled allocations.
+    ///
+    /// # Returns
+    ///
+    /// - `Ok(())` if the element was enqueued
+    /// - `Err(`[`Full`]`)`, containing the value, if there is no capacity
+    ///   remaining in the queue
+    ///
+    /// [`push_ref`]: Self::push_ref
+    /// [`pop_ref`]: Self::pop_ref
+    #[inline]
+    pub fn push(&self, val: T) -> Result<(), Full<T>> {
+        match self.push_ref() {
+            Err(_) => Err(Full(val)),
+            Ok(mut slot) => {
+                *slot = val;
+                Ok(())
+            }
+        }
+    }
+
+    /// Reserves a slot to push an element into the queue, and invokes the
+    /// provided function `f` with a mutable reference to that element.
+    ///
+    /// # Returns
+    ///
+    /// - `Ok(U)` containing the return value of the provided function, if the
+    ///   element was enqueued
+    /// - `Err(`[`Full`]`)`, if there is no capacity remaining in the queue
     #[inline]
     pub fn push_with<U>(&self, f: impl FnOnce(&mut T) -> U) -> Result<U, Full> {
         self.push_ref().map(|mut r| r.with_mut(f))
     }
 
+    /// Dequeue the first element in the queue, returning a [`Ref`] that can be
+    /// used to read from (or mutate) the element.
+    ///
+    /// **Note**: A `StaticThingBuf` is *not* a "broadcast"-style queue. Each element
+    /// is dequeued a single time. Once a thread has dequeued a given element,
+    /// it is no longer the head of the queue.
+    ///
+    /// This can be used to reuse allocations for queue elements in place,
+    /// by clearing previous data prior to writing. In order to ensure
+    /// allocations can be reused in place, elements should be enqueued using
+    /// [`push_ref`] rather than [`push`].
+    ///
+    /// For values that don't own heap allocations, or heap allocated values
+    /// that cannot be reused in place, [`pop`] can also be used.
+    ///
+    /// # Returns
+    ///
+    /// - `Some(`[`Ref<T>`](Ref)`)` if an element was dequeued
+    /// - `None` if there are no elements in the queue
+    ///
+    /// [`push_ref`]: Self::push_ref
+    /// [`push`]: Self::push
+    /// [`pop`]: Self::pop
     pub fn pop_ref(&self) -> Option<Ref<'_, T>> {
         self.core.pop_ref(&self.slots).ok()
     }
 
+    /// Dequeue the first element in the queue *by value*, moving it out of the
+    /// queue.
+    ///
+    /// **Note**: A `StaticThingBuf` is *not* a "broadcast"-style queue. Each element
+    /// is dequeued a single time. Once a thread has dequeued a given element,
+    /// it is no longer the head of the queue.
+    ///
+    /// # Returns
+    ///
+    /// - `Some(T)` if an element was dequeued
+    /// - `None` if there are no elements in the queue
+    #[inline]
+    pub fn pop(&self) -> Option<T> {
+        let mut slot = self.pop_ref()?;
+        Some(mem::take(&mut *slot))
+    }
+
+    /// Dequeue the first element in the queue by reference, and invoke the
+    /// provided function `f` with a mutable reference to the dequeued element.
+    ///
+    /// # Returns
+    ///
+    /// - `Some(U)` containing the return value of the provided function, if the
+    ///   element was dequeued
+    /// - `None` if the queue is empty
     #[inline]
     pub fn pop_with<U>(&self, f: impl FnOnce(&mut T) -> U) -> Option<U> {
         self.pop_ref().map(|mut r| r.with_mut(f))

src/thingbuf.rs

@@ -1,12 +1,182 @@
 use crate::loom::atomic::Ordering;
 use crate::{Core, Full, Ref, Slot};
 use alloc::boxed::Box;
-use core::{fmt, ptr};
+use core::{fmt, mem, ptr};
 
 #[cfg(all(loom, test))]
 mod tests;
 
-/// A fixed-size, lock-free multi-producer multi-consumer queue.
+/// A fixed-size, lock-free, multi-producer multi-consumer (MPMC) queue.
+///
+/// This is a fixed-capacity, first-in, first-out data structure. Elements are
+/// enqueued at the front of the queue by calling the [`push`] method, and
+/// dequeued from the end of the queue by calling the [`pop`] method. Elements
+/// may be enqueued and dequeued from a `ThingBuf` concurrently by any number of
+/// threads or asynchronous tasks.
+///
+/// This queue is an implementation of a [design by Dmitry Vyukov][vyukov] of
+/// 1024cores.net.
+///
+/// # Examples
+///
+/// ```
+/// use thingbuf::ThingBuf;
+///
+/// let q = ThingBuf::new(2);
+///
+/// // Push some values to the queue.
+/// q.push(1).unwrap();
+/// q.push(2).unwrap();
+///
+/// // Now, the queue is at capacity.
+/// assert!(q.push(3).is_err());
+/// ```
+///
+/// # Allocation
+///
+/// A `ThingBuf` is a fixed-size, array-based queue. Elements in the queue are
+/// stored in a single array whose capacity is specified when the `ThingBuf` is
+/// constructed. This means that a `ThingBuf` requires only a single heap
+/// allocation over its entire lifespan. Calling [`ThingBuf::new`] will allocate
+/// an array to store `capacity` elements. Subsequent calls to [`push`] and
+/// [`pop`] will never allocate or deallocate memory.
+///
+/// If the size of the queue is known at compile-time, the [`StaticThingBuf`]
+/// type, which requires *no* heap allocations at all, can be used instead.
+///
+/// ## Reusing Allocations
+///
+/// Of course, if the *elements* in the queue are themselves heap-allocated
+/// (such as `String`s or `Vec`s), heap allocations and deallocations may still
+/// occur when those types are created or dropped. However, `ThingBuf` also
+/// provides an API for enqueueing and dequeueing elements *by reference*. In
+/// some use cases, this API can be used to reduce allocations for queue elements.
+///
+/// As an example, consider the case where multiple threads in a program format
+/// log messages and send them to a dedicated worker thread that writes those
+/// messages to a file. A naive implementation might look something like this:
+///
+/// ```rust
+/// use thingbuf::ThingBuf;
+/// use std::{sync::Arc, fmt, thread, fs::File, error::Error, io::Write};
+///
+/// // Called by application threads to log a message.
+/// fn log_event(q: &Arc<ThingBuf<String>>, message: &dyn fmt::Debug) {
+///     // Format the log line to a `String`.
+///     let line = format!("{:?}\n", message);
+///     // Send the string to the worker thread.
+///     let _ = q.push(line);
+///     // If the queue was full, ignore the error and drop the log line.
+/// }
+///
+/// fn main() -> Result<(), Box<dyn Error>> {
+/// # // wrap the actual code in a function that's never called so that running
+/// # // the test never actually creates the log file.
+/// # fn docs() -> Result<(), Box<dyn Error>> {
+///     let log_queue = Arc::new(ThingBuf::<String>::new(1024));
+///
+///     // Spawn the background worker thread.
+///     let q = log_queue.clone();
+///     let mut file = File::create("myapp.log")?;
+///     thread::spawn(move || {
+///         use std::io::Write;
+///         loop {
+///             // Pop from the queue, and write each log line to the file.
+///             while let Some(line) = q.pop() {
+///                 file.write_all(line.as_bytes()).unwrap();
+///             }
+///
+///             // No more messages in the queue!
+///             file.flush().unwrap();
+///             thread::yield_now();
+///         }
+///     });
+///
+///     // ...
+///     # Ok(())
+/// # }
+/// # Ok(())
+/// }
+/// ```
+///
+/// With this design, however, new `String`s are allocated for every message
+/// that's logged, and then are immediately deallocated once they are written to
+/// the file. This can have a negative performance impact.
+///
+/// Using `ThingBuf`'s [`push_ref`] and [`pop_ref`] methods, this code can be
+/// redesigned to _reuse_ `String` allocations in place. With these methods,
+/// rather than moving an element by-value into the queue when enqueueing, we
+/// instead reserve the rights to _mutate_ a slot in the queue in place,
+/// returning a [`Ref`]. Similarly, when dequeueing, we also recieve a [`Ref`]
+/// that allows reading from (and mutating) the dequeued element. This allows
+/// the queue to _own_ the set of `String`s used for formatting log messages,
+/// which are cleared in place and the existing allocation reused.
+///
+/// The rewritten code might look like this:
+///
+/// ```rust
+/// use thingbuf::ThingBuf;
+/// use std::{sync::Arc, fmt, thread, fs::File, error::Error};
+///
+/// // Called by application threads to log a message.
+/// fn log_event(q: &Arc<ThingBuf<String>>, message: &dyn fmt::Debug) {
+///     use std::fmt::Write;
+///
+///     // Reserve a slot in the queue to write to.
+///     if let Ok(mut slot) = q.push_ref() {
+///         // Clear the string in place, retaining the allocated capacity.
+///         slot.clear();
+///         // Write the log message to the string.
+///         write!(&mut *slot, "{:?}\n", message);
+///     }
+///     // Otherwise, if `push_ref` returns an error, the queue is full;
+///     // ignore this log line.
+/// }
+///
+/// fn main() -> Result<(), Box<dyn Error>> {
+/// # // wrap the actual code in a function that's never called so that running
+/// # // the test never actually creates the log file.
+/// # fn docs() -> Result<(), Box<dyn Error>> {
+///     let log_queue = Arc::new(ThingBuf::<String>::new(1024));
+///
+///     // Spawn the background worker thread.
+///     let q = log_queue.clone();
+///     let mut file = File::create("myapp.log")?;
+///     thread::spawn(move || {
+///         use std::io::Write;
+///         loop {
+///             // Pop from the queue, and write each log line to the file.
+///             while let Some(line) = q.pop_ref() {
+///                 file.write_all(line.as_bytes()).unwrap();
+///             }
+///
+///             // No more messages in the queue!
+///             file.flush().unwrap();
+///             thread::yield_now();
+///         }
+///     });
+///
+///     // ...
+///     # Ok(())
+/// # }
+/// # Ok(())
+/// }
+/// ```
+///
+/// In this implementation, the strings will only be reallocated if their
+/// current capacity is not large enough to store the formatted representation
+/// of the log message.
+///
+/// When using a `ThingBuf` in this manner, it can be thought of as a
+/// combination of a concurrent queue and an [object pool].
+///
+/// [`push`]: Self::push
+/// [`pop`]: Self::pop
+/// [`push_ref`]: Self::push_ref
+/// [`pop_ref`]: Self::pop_ref
+/// [`StaticThingBuf`]: crate::StaticThingBuf
+/// [vyukov]: https://www.1024cores.net/home/lock-free-algorithms/queues/bounded-mpmc-queue
+/// [object pool]: https://en.wikipedia.org/wiki/Object_pool_pattern
 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
 pub struct ThingBuf<T> {
     pub(crate) core: Core,
@@ -16,7 +186,7 @@ pub struct ThingBuf<T> {
 // === impl ThingBuf ===
 
 impl<T: Default> ThingBuf<T> {
-    /// Return a new `ThingBuf` with space for `capacity` entries.
+    /// Returns a new `ThingBuf` with space for `capacity` elements.
     pub fn new(capacity: usize) -> Self {
         assert!(capacity > 0);
         Self {
@@ -25,11 +195,80 @@ impl<T: Default> ThingBuf<T> {
         }
     }
 
-    /// Reserve a slot to push an entry into the queue, returning a [`Ref`] that
+    /// Reserves a slot to push an element into the queue, returning a [`Ref`] that
     /// can be used to write to that slot.
     ///
-    /// This can be used to reuse allocations for queue entries in place,
-    /// by clearing previous data prior to writing.
+    /// This can be used to reuse allocations for queue elements in place,
+    /// by clearing previous data prior to writing. In order to ensure
+    /// allocations can be reused in place, elements should be dequeued using
+    /// [`pop_ref`] rather than [`pop`]. If values are expensive to produce,
+    /// `push_ref` can also be used to avoid producing a value if there is no
+    /// capacity for it in the queue.
+    ///
+    /// For values that don't own heap allocations, or heap allocated values
+    /// that cannot be reused in place, [`push`] can also be used.
+    ///
+    /// # Returns
+    ///
+    /// - `Ok(`[`Ref`]`)` if there is space for a new element
+    /// - `Err(`[`Full`]`)`, if there is no capacity remaining in the queue
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use thingbuf::ThingBuf;
+    ///
+    /// let q = ThingBuf::new(1);
+    ///
+    /// // Reserve a `Ref` and enqueue an element.
+    /// *q.push_ref().expect("queue should have capacity") = 10;
+    ///
+    /// // Now that the queue has one element in it, a subsequent `push_ref`
+    /// // call will fail.
+    /// assert!(q.push_ref().is_err());
+    /// ```
+    ///
+    /// Avoiding producing an expensive element when the queue is at capacity:
+    ///
+    /// ```rust
+    /// use thingbuf::ThingBuf;
+    ///
+    /// #[derive(Default)]
+    /// struct Message {
+    ///     // ...
+    /// }
+    ///
+    /// fn make_expensive_message() -> Message {
+    ///     // Imagine this function performs some costly operation, or acquires
+    ///     // a limited resource...
+    ///     # Message::default()
+    /// }
+    ///
+    /// fn enqueue_message(q: &ThingBuf<Message>) {
+    ///     loop {
+    ///         match q.push_ref() {
+    //              // If `push_ref` returns `Ok`, we've reserved a slot in
+    ///             // the queue for our message, so it's okay to generate
+    ///             // the expensive message.
+    ///             Ok(mut slot) => {
+    ///                 *slot = make_expensive_message();
+    ///                 return;
+    ///             },
+    ///
+    ///             // If there's no space in the queue, avoid generating
+    ///             // an expensive message that won't be sent.
+    ///             Err(_) => {
+    ///                 // Wait until the queue has capacity...
+    ///                 std::thread::yield_now();
+    ///             }
+    ///         }
+    ///     }
+    /// }
+    /// ```
+    ///
+    /// [`pop`]: Self::pop
+    /// [`pop_ref`]: Self::pop_ref
+    /// [`push`]: Self::push_ref
     pub fn push_ref(&self) -> Result<Ref<'_, T>, Full> {
         self.core.push_ref(&*self.slots).map_err(|e| match e {
             crate::mpsc::TrySendError::Full(()) => Full(()),
@@ -37,6 +276,42 @@ impl<T: Default> ThingBuf<T> {
         })
     }
 
+    /// Attempt to enqueue an element by value.
+    ///
+    /// If the queue is full, the element is returned in the [`Full`] error.
+    ///
+    /// Unlike [`push_ref`], this method does not enable the reuse of previously
+    /// allocated elements. If allocations are being reused by using
+    /// [`push_ref`] and [`pop_ref`], this method should not be used, as it will
+    /// drop pooled allocations.
+    ///
+    /// # Returns
+    ///
+    /// - `Ok(())` if the element was enqueued
+    /// - `Err(`[`Full`]`)`, containing the value, if there is no capacity
+    ///   remaining in the queue
+    ///
+    /// [`push_ref`]: Self::push_ref
+    /// [`pop_ref`]: Self::pop_ref
+    #[inline]
+    pub fn push(&self, val: T) -> Result<(), Full<T>> {
+        match self.push_ref() {
+            Err(_) => Err(Full(val)),
+            Ok(mut slot) => {
+                *slot = val;
+                Ok(())
+            }
+        }
+    }
+
+    /// Reserves a slot to push an element into the queue, and invokes the
+    /// provided function `f` with a mutable reference to that element.
+    ///
+    /// # Returns
+    ///
+    /// - `Ok(U)` containing the return value of the provided function, if the
+    ///   element was enqueued
+    /// - `Err(`[`Full`]`)`, if there is no capacity remaining in the queue
     #[inline]
     pub fn push_with<U>(&self, f: impl FnOnce(&mut T) -> U) -> Result<U, Full> {
         self.push_ref().map(|mut r| r.with_mut(f))
@@ -44,10 +319,56 @@ impl<T: Default> ThingBuf<T> {
 
     /// Dequeue the first element in the queue, returning a [`Ref`] that can be
     /// used to read from (or mutate) the element.
+    ///
+    /// **Note**: A `ThingBuf` is *not* a "broadcast"-style queue. Each element
+    /// is dequeued a single time. Once a thread has dequeued a given element,
+    /// it is no longer the head of the queue.
+    ///
+    /// This can be used to reuse allocations for queue elements in place,
+    /// by clearing previous data prior to writing. In order to ensure
+    /// allocations can be reused in place, elements should be enqueued using
+    /// [`push_ref`] rather than [`push`].
+    ///
+    /// For values that don't own heap allocations, or heap allocated values
+    /// that cannot be reused in place, [`pop`] can also be used.
+    ///
+    /// # Returns
+    ///
+    /// - `Some(`[`Ref<T>`](Ref)`)` if an element was dequeued
+    /// - `None` if there are no elements in the queue
+    ///
+    /// [`push_ref`]: Self::push_ref
+    /// [`push`]: Self::push
+    /// [`pop`]: Self::pop
     pub fn pop_ref(&self) -> Option<Ref<'_, T>> {
         self.core.pop_ref(&*self.slots).ok()
     }
 
+    /// Dequeue the first element in the queue *by value*, moving it out of the
+    /// queue.
+    ///
+    /// **Note**: A `ThingBuf` is *not* a "broadcast"-style queue. Each element
+    /// is dequeued a single time. Once a thread has dequeued a given element,
+    /// it is no longer the head of the queue.
+    ///
+    /// # Returns
+    ///
+    /// - `Some(T)` if an element was dequeued
+    /// - `None` if there are no elements in the queue
+    #[inline]
+    pub fn pop(&self) -> Option<T> {
+        let mut slot = self.pop_ref()?;
+        Some(mem::take(&mut *slot))
+    }
+
+    /// Dequeue the first element in the queue by reference, and invoke the
+    /// provided function `f` with a mutable reference to the dequeued element.
+    ///
+    /// # Returns
+    ///
+    /// - `Some(U)` containing the return value of the provided function, if the
+    ///   element was dequeued
+    /// - `None` if the queue is empty
     #[inline]
     pub fn pop_with<U>(&self, f: impl FnOnce(&mut T) -> U) -> Option<U> {
         self.pop_ref().map(|mut r| r.with_mut(f))
@@ -55,11 +376,11 @@ impl<T: Default> ThingBuf<T> {
 }
 
 impl<T> ThingBuf<T> {
-    /// Returns the total capacity of the `ThingBuf`. This includes both
+    /// Returns the *total* capacity of this queue. This includes both
     /// occupied and unoccupied entries.
     ///
-    /// The number of _unoccupied_ entries can be determined by subtracing the
-    /// value returned by [`len`] from the value returned by `capacity`.
+    /// To determine the queue's remaining *unoccupied* capacity, use
+    /// [`remaining`] instead.
     ///
     /// # Examples
     ///
@@ -83,22 +404,35 @@ impl<T> ThingBuf<T> {
     ///
     /// assert_eq!(q.capacity(), 100);
     /// ```
+    ///
+    /// [`remaining`]: Self::remaining
     #[inline]
     pub fn capacity(&self) -> usize {
         self.slots.len()
     }
 
-    /// Returns the number of messages in the queue
+    /// Returns the unoccupied capacity of the queue (i.e., how many additional
+    /// elements can be enqueued before the queue will be full).
     ///
-    /// The number of _unoccupied_ entries can be determined by subtracing the
-    /// value returned by [`len`] from the value returned by `capacity`.
+    /// This is equivalent to subtracting the queue's [`len`] from its [`capacity`].
+    ///
+    /// [`len`]: Self::len
+    /// [`capacity`]: Self::capacity
+    pub fn remaining(&self) -> usize {
+        self.capacity() - self.len()
+    }
+
+    /// Returns the number of elements in the queue
+    ///
+    /// To determine the queue's remaining *unoccupied* capacity, use
+    /// [`remaining`] instead.
     ///
     /// # Examples
     ///
     /// ```
     /// use thingbuf::ThingBuf;
     ///
-    /// let q = ThingBuf::<usize>::new(100);
+    /// let q = ThingBuf::new(100);
     /// assert_eq!(q.len(), 0);
     ///
     /// *q.push_ref().unwrap() = 1;
@@ -109,19 +443,21 @@ impl<T> ThingBuf<T> {
     /// let _ = q.pop_ref();
     /// assert_eq!(q.len(), 2);
     /// ```
+    ///
+    /// [`remaining`]: Self::remaining
     #[inline]
     pub fn len(&self) -> usize {
         self.core.len()
     }
 
-    /// Returns `true` if there are currently no entries in this `ThingBuf`.
+    /// Returns `true` if there are currently no elements in this `ThingBuf`.
     ///
     /// # Examples
     ///
     /// ```
     /// use thingbuf::ThingBuf;
     ///
-    /// let q = ThingBuf::<usize>::new(100);
+    /// let q = ThingBuf::new(100);
     /// assert!(q.is_empty());
     ///
     /// *q.push_ref().unwrap() = 1;