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
//! `IonaBuffer` is a high-performance, virtual memory-mirror implementation of a circular buffer,
//! which guarantees slices up to the capacity of the buffer are contiguous in memory. Wrapped reads
//! wrap to the same physical memory seamlessly.
//!
//! ```
//! use iona::IonaBuffer;
//!
//! let mut buffer: IonaBuffer<usize> = match IonaBuffer::with_capacity(512) {
//! Ok(buffer) => buffer,
//! Err(_) => panic!("Unable to allocate the buffer"),
//! };
//!
//! buffer.fill(0);
//!
//! buffer.iter_mut().enumerate().for_each(|(i, value)| *value = i);
//!
//! buffer.push_back(512); // this is now at the physical address 0
//! buffer.push_back(513); // this is now at the physical address 1
//!
//! // No allocation/ concatenation needed when reading from the end of the physical buffer (the
//! // value `511`) to the next two values that were pushed to the back!
//! assert_eq!(buffer.get_from(509).to(3), Some([511,512,513].as_slice()));
//! ```
//!
//! ```text
//! VIRTUAL ADDRESS SPACE
//! ┌─────────────────────────────────┐
//! │ │
//! │ Page A [0x0000 - 0x0FFF] │──────────┐
//! │ │ │
//! ├─────────────────────────────────┤ ▼
//! │ │ ┌──────────────────┐
//! │ Page B [0x1000 - 0x1FFF] │──►│ PHYSICAL MEMORY │
//! │ (mirror) │ │ │
//! └─────────────────────────────────┘ │ [ 0 ] data[0] │
//! │ [ 1 ] data[1] │
//! │ [ 2 ] data[2] │
//! write ptr │ ... │
//! │ │ [ N ] data[N] │◄── write ptr
//! ▼ │ ... │
//! Page A: [ 0 | 1 | 2 | ... | N ] │ [ 0 ] data[0] │◄── read ptr
//! Page B: [ 0 | 1 | 2 | ... | N ] │ [ 1 ] data[1] │
//! ▲ │ ... │
//! │ └──────────────────┘
//! read ptr
//!
//!
//! KEY BENEFIT: A contiguous read/write spanning the page boundary
//! never needs to wrap — the mirror handles it transparently.
//!
//! read ptr write ptr
//! │ │
//! ▼ ▼
//! Page A: [ 6 | 7 | 8 | 9 | 10 | 11 | 0 | 1 | 2 | 3 | 4 | 5 ]
//! ╰──────────────────────────────────────╯
//! contiguous memcpy, no wrap logic!
//!
//! Page B: [ 6 | 7 | 8 | 9 | 10 | 11 | 0 | 1 | 2 | 3 | 4 | 5 ]
//! ^--- same physical bytes, just offset by one page
//! ```
//!
//! # Trade-Offs
//!
//! - **Increased memory use**: we double the used virtual memory space, but still only have a
//! single instance of physical memory backing the buffer. Moreover, this implementation
//! requires that the buffer is mapped to page size, which is typically 4KiB. So if
//! `size_of::<T>()` is small, the buffer will be relatively large and inefficient with memory
//! use. The buffer also grows in size by powers of 2, so if 4KiB isn't large enough, the next
//! buffer size, on most machines, will be 8KiB.
pub use IonaBuffer;