triple_buf_64 0.1.0

A cheap lock-free triple buffer data structure that stores 64 bits of data
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

//! # triple_buf_64
//!
//! A cheap realtime-safe lock-free triple buffer data structure that stores 64
//! bits of data
//!
//! On platforms which natively support 64 bit atomics, this is implemented with
//! a single cheap [`AtomicU64`](core::sync::atomic::AtomicU64) load/store operation
//! (this can optionally use [portable_atomic](https://crates.io/crates/portable-atomic)
//! for maximum compatibility).
//!
//! On platforms which do NOT natively support 64 bit atomics, this is implemented
//! using a more expensive triple buffer implementation (using
//! [triple_buffer](https://crates.io/crates/triple_buffer)).
//!
//! This can be useful when you want to pass a small amount of data between
//! realtime threads (i.e. audio threads) very cheaply on most platforms, but
//! also have a realtime-safe fallback for platforms which do not have 64 bit
//! atomics (i.e. PowerPC).
//!
//! This crate is `no_std` compatible and is implemented with zero unsafe code.
//!
//! ## Data Types
//!
//! This triple buffer accepts any data type that implements the [`Data64Bit`]
//! trait. Implementations for the following primitives are provided:
//! * [`u64`]
//! * [`i64`]
//! * [`f64`]
//! * [[`u32`]; 2]
//! * [[`i32`]; 2]
//! * [[`f32`]; 2]
//! * [[`u16`]; 4]
//! * [[`i16`]; 4]
//! * [[`u8`]; 8]
//! * [[`i8`]; 8]
//! * [[`bool`]; 8]
//!
//! ## Example
//! ```
//! # use triple_buf_64::triple_buffer_64;
//! // Construct an input/output pair with the given 64 bit type.
//! let (mut input, mut output) = triple_buffer_64::<i64>(-3);
//!
//! // The output will read the initial value.
//! assert_eq!(output.read(), -3);
//! assert_eq!(output.read(), -3);
//!
//! // Write new data into the buffer.
//! input.write(-9845);
//!
//! assert_eq!(output.read(), -9845);
//! assert_eq!(output.read(), -9845);
//!
//! input.write(69);
//! input.write(68);
//! input.write(67);
//!
//! // The output always reads the latest value that was pushed to the buffer.
//! assert_eq!(output.read(), 67);
//! assert_eq!(output.read(), 67);
//! ```

#![no_std]
#![forbid(unsafe_code)]
extern crate alloc;

mod data;
pub use data::Data64Bit;

#[cfg(not(feature = "portable-atomic"))]
mod core_library;
#[cfg(not(feature = "portable-atomic"))]
pub use crate::core_library::*;

#[cfg(feature = "portable-atomic")]
mod portable_atomic;
#[cfg(feature = "portable-atomic")]
pub use crate::portable_atomic::*;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_triple_buffer_64() {
        // Construct an output/input pair with the given 64 bit type.
        let (mut input, mut output) = triple_buffer_64::<i64>(-3);

        // The output will read the initial value.
        assert_eq!(output.read(), -3);
        assert_eq!(output.read(), -3);

        // Write new data into the buffer.
        input.write(-9845);

        assert_eq!(output.read(), -9845);
        assert_eq!(output.read(), -9845);

        input.write(69);
        input.write(68);
        input.write(67);

        // The output always reads the latest value that was pushed to the buffer.
        assert_eq!(output.read(), 67);
        assert_eq!(output.read(), 67);
    }
}