picoring 0.6.0

High-performance, zero-copy circular buffer for Rust using hardware memory mirroring.
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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

use crate::ring::PicoRing;
use std::io::{self, Read, Write};

// implements Read and Write traits for seamless integration with std::io
pub struct PicoByteStream<const N: usize = 0> {
    ring: PicoRing<u8, N>,
}

impl<const N: usize> PicoByteStream<N> {
    // creates a new PicoByteStream with a capacity determined by the const generic N.
    pub fn new_static() -> Result<Self, String> {
        Ok(Self {
            ring: PicoRing::new()?,
        })
    }
}

impl PicoByteStream<0> {
    // creates a new byte stream with specified capacity
    pub fn new(capacity: usize) -> Result<Self, String> {
        Ok(Self {
            ring: PicoRing::with_capacity(capacity)?,
        })
    }
}

impl<const N: usize> PicoByteStream<N> {
    // helper to get how many bytes are available to read
    pub fn available_to_read(&self) -> usize {
        self.ring.len()
    }

    // helper to get how much space is left to write
    pub fn available_to_write(&self) -> usize {
        self.ring.available_space()
    }
}

impl<const N: usize> Read for PicoByteStream<N> {
    #[inline]
    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
        let n = self.available_to_read().min(buf.len());

        if n == 0 {
            return Ok(0);
        }

        unsafe {
            let src = self.ring.as_mut_ptr().add(self.ring.tail());
            core::ptr::copy_nonoverlapping(src, buf.as_mut_ptr(), n);
        }

        self.ring.advance_tail(n);
        Ok(n)
    }
}

impl<const N: usize> Write for PicoByteStream<N> {
    #[inline]
    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
        let n = self.available_to_write().min(buf.len());

        if n == 0 {
            return Ok(0);
        }

        unsafe {
            let dest = self.ring.as_mut_ptr().add(self.ring.head());
            core::ptr::copy_nonoverlapping(buf.as_ptr(), dest, n);
        }

        self.ring.advance_head(n);
        Ok(n)
    }

    #[inline]
    fn flush(&mut self) -> io::Result<()> {
        Ok(())
    }
}

// Extra methods for zero-copy I/O operations (e.g., with TCP sockets)
impl<const N: usize> PicoByteStream<N> {
    // returns a direct slice of data to be read from
    pub fn as_read_slice(&self) -> &[u8] {
        self.ring.readable_slice()
    }

    // returns a direct mutable slice where data can be written to
    pub fn as_write_slice(&mut self) -> &mut [u8] {
        self.ring.writable_slice()
    }

    // manually advance markers after using as_read_slice or as_write_slice
    pub fn consume(&mut self, n: usize) {
        self.ring.advance_tail(n);
    }

    pub fn produce(&mut self, n: usize) {
        self.ring.advance_head(n);
    }

    // returns an iterator over the available bytes
    #[inline]
    pub fn iter(&self) -> core::slice::Iter<'_, u8> {
        self.as_read_slice().iter()
    }

    // returns a mutable iterator over the available bytes
    #[inline]
    pub fn iter_mut(&mut self) -> core::slice::IterMut<'_, u8> {
        unsafe {
            let ptr = self.ring.as_mut_ptr().add(self.ring.tail());
            core::slice::from_raw_parts_mut(ptr, self.ring.len()).iter_mut()
        }
    }
}

// -- Ergonomics: Indexing and Iteration --

impl<const N: usize> core::ops::Index<usize> for PicoByteStream<N> {
    type Output = u8;
    #[inline]
    fn index(&self, index: usize) -> &Self::Output {
        &self.as_read_slice()[index]
    }
}

impl<const N: usize> core::ops::IndexMut<usize> for PicoByteStream<N> {
    #[inline]
    fn index_mut(&mut self, index: usize) -> &mut Self::Output {
        unsafe {
            let ptr = self.ring.as_mut_ptr().add(self.ring.tail());
            let slice = core::slice::from_raw_parts_mut(ptr, self.ring.len());
            &mut slice[index]
        }
    }
}

impl<'a, const N: usize> IntoIterator for &'a PicoByteStream<N> {
    type Item = &'a u8;
    type IntoIter = core::slice::Iter<'a, u8>;
    #[inline]
    fn into_iter(self) -> Self::IntoIter {
        self.iter()
    }
}

impl<'a, const N: usize> IntoIterator for &'a mut PicoByteStream<N> {
    type Item = &'a mut u8;
    type IntoIter = core::slice::IterMut<'a, u8>;
    #[inline]
    fn into_iter(self) -> Self::IntoIter {
        self.iter_mut()
    }
}