Crate iona 

iona

iona → aion wrapped:

Aion (from Hellenistic Greek: αἰών, romanized: aión, lit. ‘long period of time’, [ai̯ˈɔːn]) is a Hellenistic deity associated with time, the orb or circle encompassing the universe, and the zodiac. The “time” which Aion represents is perpetual, unbounded, ritual, and cyclic: The future is a returning version of the past, later called aevum – wikipedia

---

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()));

VIRTUAL ADDRESS SPACE
┌─────────────────────────────────┐
│                                 │
│   Page A  [0x0000 - 0x0FFF]     │──────────┐
│                                 │          │
├─────────────────────────────────┤          ▼
│                                 │   ┌──────────────────┐
│   Page B  [0x1000 - 0x1FFF]     │──►│  PHYSICAL MEMORY │
│   (mirror)                      │   │                  │
└─────────────────────────────────┘   │  [ 0 ]  data[0]  │
                                      │  [ 1 ]  data[1]  │
                                      │  [ 2 ]  data[2]  │
                                      │  ...             │
                                      │  [ N ]  data[N]  │
                                      └──────────────────┘


KEY BENEFIT: A contiguous read/write spanning the page boundary
never needs to wrap — the mirror handles it transparently.
The following

  Page A                                            Page B
|                                                 |
| write ptr   read ptr                            | Read and write pointers never point to Page
|     │           │                               | B addresses, but slices span from Page A to
|     ▼           ▼                               | Page B.
[ 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 0 | 1 | 2 | .. ]
                  ╰─────────────────────────────────────╯
                   contiguous slice, no wrap logic!

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.

Indexing

IonaBuffer implements the Index trait, allowing you to access value by indexes:

let mut buffer = IonaBuffer::try_from([0,2,4,6])?;

assert_eq!(buffer[1], 2);

However, indexing into a location outside of the IonaBuffer will panic! i.e.:

let mut buffer = IonaBuffer::try_from([0,2,4,6])?;

println!("{}", buffer[5]); // This will panic!

Structs

IonaBuffer

High performance, fixed length circular buffer.