Add some items documentation to ringbuf, slightly reorganize modules

async/src/rb.rs

@@ -6,7 +6,7 @@ use futures::task::AtomicWaker;
 #[cfg(feature = "alloc")]
 use ringbuf::traits::Split;
 use ringbuf::{
- rb::traits::RbRef,
+ rb::RbRef,
  storage::Storage,
  traits::{Consumer, Observer, Producer, RingBuffer, SplitRef},
  SharedRb,

async/src/wrap/cons.rs

@@ -11,7 +11,7 @@ use ringbuf::{
  consumer::{Consumer, DelegateConsumer},
  Observer,
  },
- wrap::traits::Wrap,
+ wrap::Wrap,
 };
 #[cfg(feature = "std")]
 use std::io;

async/src/wrap/mod.rs

@@ -4,7 +4,7 @@ mod prod;
 use crate::rb::AsyncRbRef;
 use ringbuf::{
  traits::{observer::DelegateObserver, Based},
- wrap::{direct::Direct, traits::Wrap},
+ wrap::{direct::Direct, Wrap},
  Obs,
 };
 

async/src/wrap/prod.rs

@@ -13,7 +13,7 @@ use ringbuf::{
  producer::{DelegateProducer, Producer},
  Observer,
  },
- wrap::traits::Wrap,
+ wrap::Wrap,
 };
 #[cfg(feature = "std")]
 use std::io;

blocking/src/rb.rs

@@ -7,7 +7,7 @@ use core::{mem::MaybeUninit, num::NonZeroUsize};
 #[cfg(feature = "alloc")]
 use ringbuf::traits::Split;
 use ringbuf::{
- rb::traits::RbRef,
+ rb::RbRef,
  storage::Storage,
  traits::{Consumer, Observer, Producer, RingBuffer, SplitRef},
  SharedRb,

blocking/src/wrap/cons.rs

@@ -5,7 +5,7 @@ use core::time::Duration;
 use ringbuf::traits::Based;
 use ringbuf::{
  traits::{consumer::DelegateConsumer, observer::DelegateObserver, Consumer, Observer},
- wrap::traits::Wrap,
+ wrap::Wrap,
 };
 #[cfg(feature = "std")]
 use std::io;

blocking/src/wrap/mod.rs

@@ -5,7 +5,7 @@ use crate::rb::BlockingRbRef;
 use core::time::Duration;
 use ringbuf::{
  traits::Based,
- wrap::{caching::Caching, traits::Wrap},
+ wrap::{caching::Caching, Wrap},
  Obs,
 };
 

blocking/src/wrap/prod.rs

@@ -5,7 +5,7 @@ use core::time::Duration;
 use ringbuf::traits::Based;
 use ringbuf::{
  traits::{observer::DelegateObserver, producer::DelegateProducer, Observer, Producer},
- wrap::traits::Wrap,
+ wrap::Wrap,
 };
 #[cfg(feature = "std")]
 use std::io;

src/lib.rs

@@ -1,6 +1,8 @@
+//! Lock-free SPSC FIFO ring buffer with direct access to inner data.
+//!
+//! For implementation details see [`RingBuffer`](`traits::RingBuffer`) description.
 #![no_std]
 #![allow(clippy::type_complexity)]
-#![allow(clippy::missing_safety_doc)]
 #![cfg_attr(feature = "bench", feature(test))]
 
 #[cfg(feature = "alloc")]

src/rb/local.rs

@@ -34,6 +34,8 @@ impl End {
 }
 
 /// Ring buffer for single-threaded use only.
+///
+/// Slightly faster than multi-threaded version because it doesn't synchronize cache.
 pub struct LocalRb<S: Storage> {
  storage: Shared<S>,
  read: End,
@@ -46,7 +48,7 @@ impl<S: Storage> LocalRb<S> {
  /// # Safety
  ///
  /// The items in storage inside `read..write` range must be initialized, items outside this range must be uninitialized.
- /// `read` and `write` positions must be valid (see [`RbBase`](`crate::ring_buffer::RbBase`)).
+ /// `read` and `write` positions must be valid (see implementation details).
  pub unsafe fn from_raw_parts(storage: S, read: usize, write: usize) -> Self {
  Self {
  storage: Shared::new(storage),

src/rb/mod.rs

@@ -1,8 +1,11 @@
+/// Single-threaded ring buffer implementation.
 pub mod local;
 mod macros;
+/// Multi-threaded ring buffer implementation.
 pub mod shared;
-pub mod traits;
+mod traits;
 mod utils;
 
 pub use local::LocalRb;
 pub use shared::SharedRb;
+pub use traits::*;

src/rb/shared.rs

@@ -22,8 +22,8 @@ use crossbeam_utils::CachePadded;
 
 /// Ring buffer that can be shared between threads.
 ///
-/// Note that there is no explicit requirement of `T: Send`. Instead [`Rb`] will work just fine even with `T: !Send`
-/// until you try to send its [`Prod`] or [`Cons`] to another thread.
+/// Note that there is no explicit requirement of `T: Send`. Instead ring buffer will work just fine even with `T: !Send`
+/// until you try to send its producer or consumer to another thread.
 #[cfg_attr(
  feature = "std",
  doc = r##"
@@ -58,7 +58,7 @@ impl<S: Storage> SharedRb<S> {
  /// # Safety
  ///
  /// The items in storage inside `read..write` range must be initialized, items outside this range must be uninitialized.
- /// `read` and `write` positions must be valid (see [`RbBase`](`crate::ring_buffer::RbBase`)).
+ /// `read` and `write` positions must be valid (see implementation details).
  pub unsafe fn from_raw_parts(storage: S, read: usize, write: usize) -> Self {
  Self {
  storage: Shared::new(storage),

src/rb/traits.rs

@@ -2,8 +2,15 @@ use crate::traits::RingBuffer;
 #[cfg(feature = "alloc")]
 use alloc::{rc::Rc, sync::Arc};
 
+/// Abstract pointer to the owning ring buffer.
+///
+/// # Safety
+///
+/// Implementation must be fair (e.g. not replacing pointers between calls and so on).
 pub unsafe trait RbRef: Clone + AsRef<Self::Rb> {
+ /// Underlying ring buffer.
  type Rb: RingBuffer;
+ /// Get ring buffer reference.
  fn rb(&self) -> &Self::Rb {
  self.as_ref()
  }

src/storage.rs

@@ -6,10 +6,13 @@ use core::{cell::UnsafeCell, mem::MaybeUninit, num::NonZeroUsize, ops::Range, sl
 ///
 /// Storage items must be stored as a contiguous array.
 ///
+/// Storage is converted to internal representation before use (see [`Self::Internal`]).
+///
 /// # Safety
 ///
-/// *[`Self::len`]/[`Self::is_empty`] must always return the same value.*
+/// *[`Self::len`] must always return the same value.*
 pub unsafe trait Storage {
+ /// Stored item.
  type Item: Sized;
 
  /// Internal representation of the storage.
@@ -143,6 +146,8 @@ impl<S: Storage> Shared<S> {
  }
 }
 
+/// Static storage.
 pub type Static<T, const N: usize> = [MaybeUninit<T>; N];
+/// Heap storage.
 #[cfg(feature = "alloc")]
 pub type Heap<T> = Vec<MaybeUninit<T>>;

src/traits/consumer.rs

@@ -9,6 +9,13 @@ use std::io::{self, Write};
 
 /// Consumer part of ring buffer.
 pub trait Consumer: Observer {
+ /// Set read index.
+ ///
+ /// # Safety
+ ///
+ /// Index must go only forward, never backward. It is recommended to use [`Self::advance_read_index`] instead.
+ ///
+ /// All slots with index less than `value` must be uninitialized until write index, all slots with index equal or greater - must be initialized.
  unsafe fn set_read_index(&self, value: usize);
 
  /// Moves `read` pointer by `count` places forward.
@@ -33,7 +40,7 @@ pub trait Consumer: Observer {
  /// All items are initialized. Elements must be removed starting from the beginning of first slice.
  /// When all items are removed from the first slice then items must be removed from the beginning of the second slice.
  ///
- /// *This method must be followed by [`Self::advance_read`] call with the number of items being removed previously as argument.*
+ /// *This method must be followed by [`Self::advance_read_index`] call with the number of items being removed previously as argument.*
  /// *No other mutating calls allowed before that.*
  fn occupied_slices(&self) -> (&[MaybeUninit<Self::Item>], &[MaybeUninit<Self::Item>]) {
  let (first, second) = unsafe { self.unsafe_slices(self.read_index(), self.write_index()) };
@@ -286,6 +293,7 @@ pub type Iter<'a, C: Consumer> = Chain<slice::Iter<'a, C::Item>, slice::Iter<'a,
 #[allow(type_alias_bounds)]
 pub type IterMut<'a, C: Consumer> = Chain<slice::IterMut<'a, C::Item>, slice::IterMut<'a, C::Item>>;
 
+/// Trait used for delegating producer methods.
 pub trait DelegateConsumer: DelegateObserver
 where
  Self::Base: Consumer,

src/traits/mod.rs

@@ -1,6 +1,10 @@
+/// Consumer functionality.
 pub mod consumer;
+/// Observer functionality.
 pub mod observer;
+/// Producer functionality.
 pub mod producer;
+/// Owning ring buffer functionality.
 pub mod ring_buffer;
 mod split;
 mod utils;

src/traits/observer.rs

@@ -1,6 +1,9 @@
 use super::{utils::modulus, Based};
 use core::{mem::MaybeUninit, num::NonZeroUsize};
 
+/// Ring buffer observer.
+///
+/// Can observe ring buffer state but cannot safely access its data.
 pub trait Observer: Sized {
  type Item: Sized;
 
@@ -9,9 +12,20 @@ pub trait Observer: Sized {
  /// It is constant during the whole ring buffer lifetime.
  fn capacity(&self) -> NonZeroUsize;
 
+ /// Index of the last item in the ring buffer.
+ ///
+ /// Index value is in range `0..(2 * capacity)`.
  fn read_index(&self) -> usize;
+ /// Index of the next empty slot in the ring buffer.
+ ///
+ /// Index value is in range `0..(2 * capacity)`.
  fn write_index(&self) -> usize;
 
+ /// Get mutable slice between `start` and `end` indices.
+ ///
+ /// # Safety
+ ///
+ /// There must not exist overlapping slices at the same time.
  unsafe fn unsafe_slices(&self, start: usize, end: usize) -> (&mut [MaybeUninit<Self::Item>], &mut [MaybeUninit<Self::Item>]);
 
  /// Whether read end is held by consumer.
@@ -52,6 +66,7 @@ pub trait Observer: Sized {
  }
 }
 
+/// Trait used for delegating observer methods.
 pub trait DelegateObserver: Based
 where
  Self::Base: Observer,

src/traits/producer.rs

@@ -14,6 +14,13 @@ use std::{
 
 /// Producer part of ring buffer.
 pub trait Producer: Observer {
+ /// Set read index.
+ ///
+ /// # Safety
+ ///
+ /// Index must go only forward, never backward. It is recommended to use [`Self::advance_write_index`] instead.
+ ///
+ /// All slots with index less than `value` must be initialized until write index, all slots with index equal or greater - must be uninitialized.
  unsafe fn set_write_index(&self, value: usize);
 
  /// Moves `write` pointer by `count` places forward.
@@ -40,8 +47,10 @@ pub trait Producer: Observer {
  /// Vacant memory is uninitialized. Initialized items must be put starting from the beginning of first slice.
  /// When first slice is fully filled then items must be put to the beginning of the second slice.
  ///
- /// *This method must be followed by [`Self::advance_write`] call with the number of items being put previously as argument.*
+ /// *This method must be followed by [`Self::advance_write_index`] call with the number of items being put previously as argument.*
  /// *No other mutating calls allowed before that.*
+ ///
+ /// *Vacant slices must not be used to store any data because their contents aren't synchronized properly.*
  fn vacant_slices_mut(&mut self) -> (&mut [MaybeUninit<Self::Item>], &mut [MaybeUninit<Self::Item>]) {
  unsafe { self.unsafe_slices(self.write_index(), self.read_index() + self.capacity().get()) }
  }
@@ -139,6 +148,7 @@ pub trait Producer: Observer {
  }
 }
 
+/// Trait used for delegating consumer methods.
 pub trait DelegateProducer: DelegateObserver
 where
  Self::Base: Producer,

src/traits/ring_buffer.rs

@@ -4,7 +4,7 @@ use super::{
  Observer,
 };
 
-/// An abstract ring buffer.
+/// An abstract ring buffer that exclusively owns its data.
 ///
 /// # Details
 ///
@@ -17,7 +17,17 @@ use super::{
 /// without using the space for an extra element in container.
 /// And obviously we cannot store more than `capacity` items in the buffer, so `write - read` modulo `2 * capacity` is not allowed to be greater than `capacity`.
 pub trait RingBuffer: Observer + Consumer + Producer {
+ /// Tell whether read end of the ring buffer is held by consumer or not.
+ ///
+ /// # Safety
+ ///
+ /// Must not be set to `false` while consumer exists.
  unsafe fn hold_read(&self, flag: bool);
+ /// Tell whether write end of the ring buffer is held by producer or not.
+ ///
+ /// # Safety
+ ///
+ /// Must not be set to `false` while producer exists.
  unsafe fn hold_write(&self, flag: bool);
 
  /// Pushes an item to the ring buffer overwriting the latest item if the buffer is full.
@@ -57,6 +67,7 @@ pub trait RingBuffer: Observer + Consumer + Producer {
  }
 }
 
+/// Trait used for delegating owning ring buffer methods.
 pub trait DelegateRingBuffer: DelegateProducer + DelegateConsumer
 where
  Self::Base: RingBuffer,

src/traits/split.rs

@@ -1,19 +1,27 @@
 use crate::traits::{Consumer, Producer, RingBuffer};
 
+/// Split the ring buffer onto producer and consumer.
 pub trait Split: RingBuffer {
+ /// Producer type.
  type Prod: Producer;
+ /// Consumer type.
  type Cons: Consumer;
 
+ /// Perform splitting.
  fn split(self) -> (Self::Prod, Self::Cons);
 }
 
+/// Split the ring buffer by reference onto producer and consumer.
 pub trait SplitRef: RingBuffer {
+ /// Ref producer type.
  type RefProd<'a>: Producer + 'a
  where
  Self: 'a;
+ /// Ref consumer type.
  type RefCons<'a>: Consumer + 'a
  where
  Self: 'a;
 
+ /// Perform splitting by reference.
  fn split_ref(&mut self) -> (Self::RefProd<'_>, Self::RefCons<'_>);
 }

src/traits/utils.rs

@@ -1,9 +1,15 @@
 use super::Observer;
 use core::num::NonZeroUsize;
 
+/// Trait that should be implemented by ring buffer wrappers.
+///
+/// Used for automatically delegating methods.
 pub trait Based {
+ /// Type the wrapper based on.
  type Base;
+ /// Reference to base.
  fn base(&self) -> &Self::Base;
+ /// Mutable reference to base.
  fn base_mut(&mut self) -> &mut Self::Base;
 }