| lib.rs |
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!");
``` |
39175 |