Struct framering::FramedRing

pub struct FramedRing<T, Cap: Capacity> { /* fields omitted */ }

A ring buffer which exposes operations via 'frames'.

Implementations

impl<T, Cap: Capacity> FramedRing<T, Cap>

pub fn new() -> Self

Creates a new FramedRing with the default Cap size

Example

let mut ring = FramedRing::<(), LinearCapacity>::new();

pub fn with_capacity(c: Cap) -> Self

Creates a new FramedRing with the given capacity

Example

let mut ring = FramedRing::<i32, LinearCapacity>::with_capacity(LinearCapacity{cap: 32});
assert_eq!(ring.capacity(), 32);

pub fn frame<'ring>(&'ring self) -> RingFrameMut<'ring, T, Cap>

Creates a new root frame. Panics if this is called when another frame is still in scope

Example

let mut ring = FramedRing::<i32, LinearCapacity>::new();
let mut frame = ring.frame();
frame.push(1);

pub fn frame_reserve<'ring>(
    &'ring self,
    frame_capacity: usize
) -> RingFrameMut<'ring, T, Cap>

Creates a new root frame with the given capacity for inserting elements. Panics if this is called when another frame is still in scope

Example

let mut ring = FramedRing::<i32, LinearCapacity>::new();
let mut frame = ring.frame_reserve(4);
assert_eq!(ring.capacity(), 5);
frame.push(1);

pub fn try_promote<'ring>(
    &'ring self,
    frame: RingFrame<'ring, T, Cap>
) -> Result<RingFrameMut<'ring, T, Cap>, RingFrame<'ring, T, Cap>>

Tries to promote a given frame to a mutable frame which can be appended to. Returns Ok with the new mutable frame if the passed frame could be promoted or returns Err with the passed frame if unable.

Example

let mut ring = FramedRing::<i32, LinearCapacity>::new();
let mut frame = ring.frame();
let (frame_ro, frame2) = frame.next();
let (frame2_ro, frame3) = frame2.next();
drop(frame3);
assert!(ring.try_promote(frame_ro).is_err());
assert!(ring.try_promote(frame2_ro).is_ok());

pub fn promote<'ring>(
    &'ring self,
    frame: RingFrame<'ring, T, Cap>
) -> RingFrameMut<'ring, T, Cap>

Promotes a given frame, or panics if passed frame is not able to be promoted

Errors

Panics if the passed frame ring is unable to be promoted for whatever reason.

Example

let mut ring = FramedRing::<i32, LinearCapacity>::new();
let mut frame = ring.frame();
let (frame_ro, frame2) = frame.next();
drop(frame2);
ring.promote(frame_ro);

pub fn capacity(&self) -> usize

Returns the current capacity of the entire ring

Example

let mut ring = FramedRing::<i32, LinearCapacity>::with_capacity(LinearCapacity{cap: 32});
assert_eq!(ring.capacity(), 32);

pub fn size(&self) -> usize

Returns the used capacity of the entire ring. Counts headers as well as elements which may have been dropped but not free to be used again yet.

About the only use for this is for understanding used capacity.

Examples

let mut ring = FramedRing::<i32, LinearCapacity>::new();
let mut frame = ring.frame();
frame.push(1);
// Header + element
assert_eq!(ring.size(), 2);

let mut ring = FramedRing::<i32, LinearCapacity>::new();
let mut frame = ring.frame();
frame.push(1);
let (frame_ro, mut frame2) = frame.next();
frame2.push(1);
let (frame2_ro, mut frame3) = frame2.next();
frame3.push(1);
assert_eq!(ring.size(), 6);
drop(frame2_ro);
assert_eq!(ring.size(), 6);
drop(frame_ro);
assert_eq!(ring.size(), 2);

Trait Implementations

impl<T, Cap: Capacity> Drop for FramedRing<T, Cap>

pub fn drop(&mut self)

Executes the destructor for this type.