aboutsummaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorBrian Cully <bjc@kublai.com>2019-08-13 11:20:24 -0400
committerBrian Cully <bjc@kublai.com>2019-08-13 11:20:24 -0400
commit25bbfb332e0edcdc7f3c400d8fc1b83efa9ac6d0 (patch)
tree35401508aa3555247feab392c006b54c9b22457f /src
parenteb0a3c051cd52dbc3af44ade4c2afae10eba94ea (diff)
downloadstarb-25bbfb332e0edcdc7f3c400d8fc1b83efa9ac6d0.tar.gz
starb-25bbfb332e0edcdc7f3c400d8fc1b83efa9ac6d0.zip
Documentation.
Diffstat (limited to 'src')
-rwxr-xr-xsrc/lib.rs19
1 files changed, 19 insertions, 0 deletions
diff --git a/src/lib.rs b/src/lib.rs
index 4d0a96b..a4a5be8 100755
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -19,8 +19,12 @@ use core::{
/// This will disappear when const generics appear.
const CAPACITY: usize = 1024;
+/// Errors that can be made when interacting with the ring buffer.
#[derive(Debug, PartialEq)]
pub enum Error {
+ /// The buffer is at capacity and cannot fit any more
+ /// elements. You need to `unshift` at least once to make some
+ /// space.
BufferFull,
}
@@ -40,6 +44,9 @@ where
T: Copy,
{
/// Create a new RingBuffer.
+ ///
+ /// The `default` element isn't important, but is, unfortunately,
+ /// currently required to make stable rust happy.
pub const fn new(default: T) -> Self {
Self {
head: AtomicUsize::new(0),
@@ -48,6 +55,9 @@ where
}
}
+ /// Splits the ring buffer into a consumer/producer pair
+ /// (`Reader`/`Writer` respectively). These structures can be used
+ /// safely across threads.
// Honestly, this should consume `self` or at least be `mut`, but
// it needs to be available in const static contexts, which
// prevents that. Basically all the rest of the unsafe stuff in
@@ -68,6 +78,7 @@ where
}
}
+/// Consumer of `RingBuffer`.
pub struct Reader<'a, T> {
rb: *const RingBuffer<T>,
_marker: PhantomData<&'a ()>,
@@ -75,6 +86,7 @@ pub struct Reader<'a, T> {
unsafe impl<T> Send for Reader<'_, T> where T: Send {}
unsafe impl<T> Sync for Reader<'_, T> {}
+/// Producer for `Ringbuffer`.
pub struct Writer<'a, T> {
rb: *const RingBuffer<T>,
_marker: PhantomData<&'a ()>,
@@ -86,6 +98,12 @@ impl<T> Reader<'_, T>
where
T: Copy,
{
+ /// The number of elements currently available for reading.
+ ///
+ /// NB: Because the `Writer` half of the ring buffer may be adding
+ /// elements in another thread, the value read from `len` is a
+ /// *minimum* of what may actually be available by the time the
+ /// reading takes place.
pub fn len(&self) -> usize {
let rb: &mut RingBuffer<T> = unsafe { core::mem::transmute(self.rb) };
let h = rb.head.load(Ordering::SeqCst);
@@ -94,6 +112,7 @@ where
rc
}
+ /// Whether or not the ring buffer is empty.
pub fn is_empty(&self) -> bool {
self.len() == 0
}