Crate dubble

A generic double-buffer.

Description

A generic double-buffer for anything that implements Clone.

Usage

DoubleBuffered implements Default so long as the type being double-buffered does.

use dubble::DoubleBuffered;
let mut my_buf = DoubleBuffered::<i32>::default();

Otherwise, you can use a Fn() -> T to construct the value in each buffer.

let mut my_buf = DoubleBuffered::construct_with(Vec::<i32>::new);

A longer example usage is shown below.

// creating a buffer using a closure to initialise the buffers
let mut my_buf = DoubleBuffered::construct_with(||
{
    let mut s = String::new();
    s.push_str("hello,");
    s
});

// writing to the buffer
{
    // creates a mutable reference to the write buffer
    let mut wb = my_buf.write();
    wb.push_str(" world!");
}

// NB: DoubleBuffer implements DerefMut, so we could also use the
// `push_str` method of `String` directly, like so.
my_buf.push_str(" Hello again!");

// reading from the buffer
// note: the read half of the buffer should not have updated yet
assert!(my_buf.read() == "hello,");

// updating the buffer
// other half of the buffer has been updated
// NB: DoubleBuffer implements Deref, so we could use the dereference operator
// here as well
my_buf.update();
assert!(*my_buf == "hello, world! Hello again!");

Notes

Default

DoubleBuffered implements Default so long as the type being buffered implements it. For example, if you needed a double-buffered i32:

use dubble::DoubleBuffered;
let my_buf: DoubleBuffered<i32> = DoubleBuffered::default();

Deref and DerefMut

An important note on the impls for each of these is that Deref will dereference to the read buffer while DerefMut will dereference to the write buffer. So, if you did *my_buf = 3 followed by assert(*my_buf == 3), you'd find that the assertion would fail.

*my_buf = 3;
assert!(*my_buf == 3);

In other words, Deref behaves as if you had called my_buf.read(), and DerefMut behaves as if you had called my_buf.write().

Structs

DoubleBuffered

Represents something that is double-buffered. The type being buffered must be Clone, so that the read buffer can be updated with the contents of the write buffer during the update.