Crate triple_buffer

Triple buffering in Rust

In this crate, we propose a Rust implementation of triple buffering. This is a non-blocking thread synchronization mechanism that can be used when a single producer thread is frequently updating a shared data block, and a single consumer thread wants to be able to read the latest available version of the shared data whenever it feels like it.

Examples

For many use cases, you can use the ergonomic write/read interface, where the producer moves values into the buffer and the consumer accesses the latest buffer by shared reference:

// Create a triple buffer
use triple_buffer::TripleBuffer;
let buf = TripleBuffer::new(0);

// Split it into an input and output interface, to be respectively sent to
// the producer thread and the consumer thread
let (mut buf_input, mut buf_output) = buf.split();

// The producer can move a value into the buffer at any time
buf_input.write(42);

// The consumer can access the latest value from the producer at any time
let latest_value_ref = buf_output.read();
assert_eq!(*latest_value_ref, 42);

In situations where moving the original value away and being unable to modify it on the consumer’s side is too costly, such as if creating a new value involves dynamic memory allocation, you can use a lower-level API which allows you to access the producer and consumer’s buffers in place and to precisely control when updates are propagated:

// Create and split a triple buffer
use triple_buffer::TripleBuffer;
let buf = TripleBuffer::new(String::with_capacity(42));
let (mut buf_input, mut buf_output) = buf.split();

// Mutate the input buffer in place
{
    // Acquire a reference to the input buffer
    let input = buf_input.input_buffer();

    // In general, you don't know what's inside of the buffer, so you should
    // always reset the value before use (this is a type-specific process).
    input.clear();

    // Perform an in-place update
    input.push_str("Hello, ");
}

// Publish the above input buffer update
buf_input.publish();

// Manually fetch the buffer update from the consumer interface
buf_output.update();

// Acquire a mutable reference to the output buffer
let output = buf_output.output_buffer();

// Post-process the output value before use
output.push_str("world!");

Structs

Input

Producer interface to the triple buffer

Output

Consumer interface to the triple buffer

TripleBuffer

A triple buffer, useful for nonblocking and thread-safe data sharing