Skip to main content

astrs_data/buffer/
mod.rs

1//! Aligned memory: owned buffers, shared zero-copy windows, typed views and
2//! validity bitmaps.
3//!
4//! The buffer stack has four layers, each one a thin wrapper over the last:
5//!
6//! | Type | Owns | Shareable | Purpose |
7//! |---|---|---|---|
8//! | [`AlignedBuf`] | yes | no | growable 64-byte aligned allocation; builders write here |
9//! | [`Buffer`] | shared | `Arc` | immutable `(Arc<AlignedBuf>, offset, len)` window; slicing is free |
10//! | [`ScalarBuffer<T>`] | shared | `Arc` | a [`Buffer`] reinterpreted as `[T]` |
11//! | [`Bitmap`] | shared | `Arc` | a [`Buffer`] reinterpreted as LSB-numbered bits |
12//!
13//! Freezing an [`AlignedBuf`] into a [`Buffer`] is the one-way door between
14//! the mutable and the shared world:
15//!
16//! ```
17//! use astrs_data::{AlignedBuf, Buffer};
18//!
19//! let mut owned = AlignedBuf::new();
20//! owned.extend_from_slice(b"payload");
21//! let shared = Buffer::from(owned);
22//!
23//! // Every slice is a refcount bump — no bytes move.
24//! let tail = shared.slice(3, 4);
25//! assert_eq!(tail.as_slice(), b"load");
26//! assert_eq!(shared.as_slice(), b"payload");
27//! ```
28
29pub mod aligned;
30pub mod bitmap;
31pub mod scalar;
32
33use std::fmt;
34use std::sync::Arc;
35
36pub use crate::buffer::aligned::{ALIGNMENT, AlignedBuf, pad_to_alignment, padding_for};
37pub use crate::buffer::bitmap::{
38    Bitmap, BitmapBuilder, BitmapIter, count_set_bits, get_bit, set_bit,
39};
40pub use crate::buffer::scalar::ScalarBuffer;
41
42use crate::datatype::ArrowNativeType;
43use crate::error::{DataError, Result};
44
45/// An immutable, reference-counted window over an [`AlignedBuf`].
46///
47/// `Buffer` is what arrays actually hold. Cloning it and slicing it are both
48/// `O(1)` and allocation-free, which is what makes array slicing zero-copy all
49/// the way down to the shared-memory ring (blueprint §6.2).
50///
51/// The window's start address inherits the backing allocation's alignment only
52/// when `offset` is itself a multiple of the alignment; use
53/// [`Buffer::address_alignment`] or [`ScalarBuffer::try_new`] when that matters.
54///
55/// ```
56/// use astrs_data::Buffer;
57///
58/// let buffer = Buffer::from_slice(&[1, 2, 3, 4, 5]);
59/// let middle = buffer.slice(1, 3);
60/// assert_eq!(middle.as_slice(), &[2, 3, 4]);
61/// assert_eq!(middle.slice(1, 99).as_slice(), &[3, 4], "slices clamp, never panic");
62/// ```
63#[derive(Clone)]
64pub struct Buffer {
65    /// The shared allocation.
66    data: Arc<AlignedBuf>,
67    /// Byte offset of the window inside `data`.
68    offset: usize,
69    /// Length of the window in bytes. `offset + len <= data.len()` always.
70    len: usize,
71}
72
73impl Buffer {
74    /// An empty buffer. Allocates nothing.
75    #[must_use]
76    pub fn new() -> Self {
77        Self::from(AlignedBuf::new())
78    }
79
80    /// Copies `bytes` into a fresh aligned allocation.
81    ///
82    /// ```
83    /// use astrs_data::Buffer;
84    ///
85    /// assert_eq!(Buffer::from_slice(b"abc").as_slice(), b"abc");
86    /// ```
87    #[must_use]
88    pub fn from_slice(bytes: &[u8]) -> Self {
89        Self::from(AlignedBuf::from_slice(bytes))
90    }
91
92    /// A buffer of `len` zero bytes.
93    #[must_use]
94    pub fn zeroed(len: usize) -> Self {
95        Self::from(AlignedBuf::zeroed(len))
96    }
97
98    /// Copies a typed slice into a fresh aligned allocation.
99    ///
100    /// The bytes are the host's native representation, which is the
101    /// little-endian layout Arrow specifies on every platform AstRS targets.
102    ///
103    /// ```
104    /// use astrs_data::Buffer;
105    ///
106    /// let buffer = Buffer::from_scalars(&[1i32, 2, 3]);
107    /// assert_eq!(buffer.len(), 12);
108    /// ```
109    #[must_use]
110    pub fn from_scalars<T: ArrowNativeType>(values: &[T]) -> Self {
111        Self::from_slice(scalar::as_bytes(values))
112    }
113
114    /// Wraps an existing shared allocation without copying.
115    #[must_use]
116    pub fn from_arc(data: Arc<AlignedBuf>) -> Self {
117        let len = data.len();
118        Self {
119            data,
120            offset: 0,
121            len,
122        }
123    }
124
125    /// Length of the window in bytes.
126    #[inline]
127    #[must_use]
128    pub const fn len(&self) -> usize {
129        self.len
130    }
131
132    /// Returns `true` when the window covers no bytes.
133    #[inline]
134    #[must_use]
135    pub const fn is_empty(&self) -> bool {
136        self.len == 0
137    }
138
139    /// Byte offset of this window inside the backing allocation.
140    #[inline]
141    #[must_use]
142    pub const fn offset(&self) -> usize {
143        self.offset
144    }
145
146    /// Total size of the backing allocation, in bytes.
147    ///
148    /// A sliced buffer keeps the whole allocation alive; this is how much
149    /// memory the window is really pinning.
150    #[inline]
151    #[must_use]
152    pub fn backing_len(&self) -> usize {
153        self.data.len()
154    }
155
156    /// The bytes in the window.
157    #[inline]
158    #[must_use]
159    pub fn as_slice(&self) -> &[u8] {
160        let all = self.data.as_slice();
161        let end = self.offset.saturating_add(self.len);
162        debug_assert!(end <= all.len(), "window invariant");
163        match all.get(self.offset..end) {
164            Some(window) => window,
165            // Unreachable while the window invariant holds; keeps the accessor
166            // total instead of panicking if a future refactor breaks it.
167            None => &[],
168        }
169    }
170
171    /// Pointer to the first byte of the window.
172    #[inline]
173    #[must_use]
174    pub fn as_ptr(&self) -> *const u8 {
175        self.data.as_ptr().wrapping_add(self.offset)
176    }
177
178    /// Largest power-of-two alignment the window's start address satisfies.
179    ///
180    /// ```
181    /// use astrs_data::{ALIGNMENT, Buffer};
182    ///
183    /// let buffer = Buffer::from_slice(&[0; 128]);
184    /// assert!(buffer.address_alignment() >= ALIGNMENT);
185    /// assert!(buffer.slice(1, 4).address_alignment() < ALIGNMENT);
186    /// ```
187    #[must_use]
188    pub fn address_alignment(&self) -> usize {
189        let addr = self.as_ptr() as usize;
190        if addr == 0 {
191            return ALIGNMENT;
192        }
193        1usize << addr.trailing_zeros().min(usize::BITS - 1)
194    }
195
196    /// Returns `true` when the window's start address is a multiple of `align`.
197    #[inline]
198    #[must_use]
199    pub fn is_aligned_to(&self, align: usize) -> bool {
200        align == 0 || (self.as_ptr() as usize).is_multiple_of(align)
201    }
202
203    /// A zero-copy sub-window, clamped to the available range.
204    ///
205    /// The crate-wide convention: an out-of-range request yields the largest
206    /// valid window rather than panicking (see [`crate::array::Array::slice`]).
207    /// Use [`Buffer::try_slice`] when a request outside the range is a bug.
208    #[must_use]
209    pub fn slice(&self, offset: usize, len: usize) -> Self {
210        let offset = offset.min(self.len);
211        let len = len.min(self.len - offset);
212        Self {
213            data: Arc::clone(&self.data),
214            offset: self.offset + offset,
215            len,
216        }
217    }
218
219    /// Checked [`Buffer::slice`].
220    ///
221    /// ```
222    /// use astrs_data::{Buffer, DataError};
223    ///
224    /// let buffer = Buffer::from_slice(&[1, 2, 3]);
225    /// assert!(buffer.try_slice(1, 2).is_ok());
226    /// assert_eq!(
227    ///     buffer.try_slice(2, 2).unwrap_err(),
228    ///     DataError::SliceOutOfBounds { offset: 2, len: 2, available: 3 }
229    /// );
230    /// ```
231    pub fn try_slice(&self, offset: usize, len: usize) -> Result<Self> {
232        if offset.saturating_add(len) > self.len {
233            return Err(DataError::SliceOutOfBounds {
234                offset,
235                len,
236                available: self.len,
237            });
238        }
239        Ok(self.slice(offset, len))
240    }
241
242    /// Number of `Buffer`/`Arc` handles sharing the backing allocation.
243    #[must_use]
244    pub fn share_count(&self) -> usize {
245        Arc::strong_count(&self.data)
246    }
247
248    /// Reinterprets the window as a typed slice.
249    ///
250    /// Fails when the window is not aligned for `T` or its length is not a
251    /// whole number of elements. See [`ScalarBuffer`].
252    pub fn typed<T: ArrowNativeType>(&self) -> Result<ScalarBuffer<T>> {
253        ScalarBuffer::try_new(self.clone())
254    }
255
256    /// Recovers the unique owner when this is the only handle and the window
257    /// covers the whole allocation; otherwise gives the buffer back.
258    ///
259    /// Builders use this to reuse an allocation instead of copying.
260    ///
261    /// ```
262    /// use astrs_data::{AlignedBuf, Buffer};
263    ///
264    /// let buffer = Buffer::from(AlignedBuf::from_slice(b"own"));
265    /// let owned = buffer.into_aligned().expect("sole owner of the full window");
266    /// assert_eq!(owned.as_slice(), b"own");
267    ///
268    /// let shared = Buffer::from_slice(b"shared");
269    /// let _clone = shared.clone();
270    /// assert!(shared.into_aligned().is_err(), "a second handle blocks recovery");
271    /// ```
272    ///
273    /// # Errors
274    ///
275    /// Returns the original buffer when it is shared or is a partial window.
276    pub fn into_aligned(self) -> core::result::Result<AlignedBuf, Self> {
277        let Self { data, offset, len } = self;
278        if offset != 0 || len != data.len() {
279            return Err(Self { data, offset, len });
280        }
281        Arc::try_unwrap(data).map_err(|data| Self { data, offset, len })
282    }
283
284    /// Copies the window into a fresh allocation whose start address satisfies
285    /// [`ALIGNMENT`], returning `self` untouched when it already does.
286    ///
287    /// Stage 2 uses this on the decode path: a buffer carved out of a mapped
288    /// IPC body may start at an arbitrary offset, and the typed views require
289    /// element alignment.
290    ///
291    /// ```
292    /// use astrs_data::{ALIGNMENT, Buffer};
293    ///
294    /// let unaligned = Buffer::from_slice(&[0u8; 128]).slice(1, 8);
295    /// let fixed = unaligned.realigned();
296    /// assert!(fixed.is_aligned_to(ALIGNMENT));
297    /// assert_eq!(fixed.as_slice(), unaligned.as_slice());
298    /// ```
299    #[must_use]
300    pub fn realigned(&self) -> Self {
301        if self.is_aligned_to(ALIGNMENT) {
302            return self.clone();
303        }
304        Self::from_slice(self.as_slice())
305    }
306}
307
308impl Default for Buffer {
309    #[inline]
310    fn default() -> Self {
311        Self::new()
312    }
313}
314
315impl From<AlignedBuf> for Buffer {
316    #[inline]
317    fn from(buf: AlignedBuf) -> Self {
318        Self::from_arc(Arc::new(buf))
319    }
320}
321
322impl From<&[u8]> for Buffer {
323    #[inline]
324    fn from(bytes: &[u8]) -> Self {
325        Self::from_slice(bytes)
326    }
327}
328
329impl From<Vec<u8>> for Buffer {
330    #[inline]
331    fn from(bytes: Vec<u8>) -> Self {
332        Self::from_slice(&bytes)
333    }
334}
335
336impl AsRef<[u8]> for Buffer {
337    #[inline]
338    fn as_ref(&self) -> &[u8] {
339        self.as_slice()
340    }
341}
342
343impl std::ops::Deref for Buffer {
344    type Target = [u8];
345
346    #[inline]
347    fn deref(&self) -> &[u8] {
348        self.as_slice()
349    }
350}
351
352impl PartialEq for Buffer {
353    /// Compares window *contents*, not identity: two buffers backed by
354    /// different allocations are equal when their bytes are.
355    #[inline]
356    fn eq(&self, other: &Self) -> bool {
357        self.as_slice() == other.as_slice()
358    }
359}
360
361impl Eq for Buffer {}
362
363impl std::hash::Hash for Buffer {
364    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
365        self.as_slice().hash(state);
366    }
367}
368
369impl fmt::Debug for Buffer {
370    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
371        const PREVIEW: usize = 16;
372        let bytes = self.as_slice();
373        f.debug_struct("Buffer")
374            .field("len", &self.len)
375            .field("offset", &self.offset)
376            .field("shared", &self.share_count())
377            .field("head", &&bytes[..bytes.len().min(PREVIEW)])
378            .finish_non_exhaustive()
379    }
380}
381
382impl FromIterator<u8> for Buffer {
383    fn from_iter<I: IntoIterator<Item = u8>>(iter: I) -> Self {
384        Self::from(AlignedBuf::from_iter(iter))
385    }
386}
387
388#[cfg(test)]
389mod tests {
390    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
391
392    use super::*;
393
394    const fn assert_send_sync<T: Send + Sync>() {}
395
396    #[test]
397    fn buffer_is_send_and_sync() {
398        assert_send_sync::<Buffer>();
399    }
400
401    #[test]
402    fn empty_buffer() {
403        let buffer = Buffer::new();
404        assert!(buffer.is_empty());
405        assert_eq!(buffer.len(), 0);
406        assert_eq!(buffer.as_slice(), &[] as &[u8]);
407        assert_eq!(buffer, Buffer::default());
408    }
409
410    #[test]
411    fn slicing_is_zero_copy() {
412        let buffer = Buffer::from_slice(&[0, 1, 2, 3, 4, 5, 6, 7]);
413        let base = buffer.as_ptr();
414        let mid = buffer.slice(2, 4);
415        assert_eq!(mid.as_slice(), &[2, 3, 4, 5]);
416        assert_eq!(mid.as_ptr(), base.wrapping_add(2));
417        assert_eq!(mid.offset(), 2);
418        assert_eq!(mid.backing_len(), 8);
419        assert_eq!(buffer.share_count(), 2);
420    }
421
422    #[test]
423    fn nested_slices_compose() {
424        let buffer = Buffer::from_slice(&(0u8..20).collect::<Vec<_>>());
425        let a = buffer.slice(5, 10);
426        let b = a.slice(2, 3);
427        assert_eq!(b.as_slice(), &[7, 8, 9]);
428        assert_eq!(b.offset(), 7);
429    }
430
431    #[test]
432    fn slices_clamp_instead_of_panicking() {
433        let buffer = Buffer::from_slice(&[1, 2, 3]);
434        assert_eq!(buffer.slice(0, 99).as_slice(), &[1, 2, 3]);
435        assert_eq!(buffer.slice(2, 99).as_slice(), &[3]);
436        assert!(buffer.slice(99, 1).is_empty());
437        assert!(buffer.slice(usize::MAX, usize::MAX).is_empty());
438    }
439
440    #[test]
441    fn try_slice_reports_out_of_range() {
442        let buffer = Buffer::from_slice(&[1, 2, 3]);
443        assert_eq!(buffer.try_slice(0, 3).unwrap().as_slice(), &[1, 2, 3]);
444        assert_eq!(buffer.try_slice(3, 0).unwrap().len(), 0);
445        assert_eq!(
446            buffer.try_slice(1, 3).unwrap_err(),
447            DataError::SliceOutOfBounds {
448                offset: 1,
449                len: 3,
450                available: 3
451            }
452        );
453        assert!(buffer.try_slice(usize::MAX, usize::MAX).is_err());
454    }
455
456    #[test]
457    fn alignment_reporting() {
458        let buffer = Buffer::from_slice(&[0; 256]);
459        assert!(buffer.is_aligned_to(ALIGNMENT));
460        assert!(buffer.address_alignment() >= ALIGNMENT);
461        let odd = buffer.slice(1, 8);
462        assert!(!odd.is_aligned_to(ALIGNMENT));
463        assert_eq!(odd.address_alignment(), 1);
464        assert!(buffer.slice(64, 8).is_aligned_to(ALIGNMENT));
465        assert!(buffer.is_aligned_to(0));
466    }
467
468    #[test]
469    fn realigned_copies_only_when_needed() {
470        let buffer = Buffer::from_slice(&[7u8; 128]);
471        let same = buffer.realigned();
472        assert_eq!(same.as_ptr(), buffer.as_ptr(), "already aligned: no copy");
473
474        let odd = buffer.slice(3, 10);
475        let fixed = odd.realigned();
476        assert!(fixed.is_aligned_to(ALIGNMENT));
477        assert_ne!(fixed.as_ptr(), odd.as_ptr());
478        assert_eq!(fixed.as_slice(), odd.as_slice());
479    }
480
481    #[test]
482    fn into_aligned_recovers_sole_ownership() {
483        let buffer = Buffer::from_slice(b"recover");
484        let owned = buffer.into_aligned().expect("sole owner");
485        assert_eq!(owned.as_slice(), b"recover");
486
487        let shared = Buffer::from_slice(b"shared");
488        let keep = shared.clone();
489        let err = shared.into_aligned().expect_err("two handles");
490        assert_eq!(err.as_slice(), b"shared");
491        drop(keep);
492
493        let windowed = Buffer::from_slice(b"window").slice(1, 3);
494        assert!(windowed.into_aligned().is_err(), "partial window");
495    }
496
497    #[test]
498    fn equality_is_by_content() {
499        let a = Buffer::from_slice(&[1, 2, 3]);
500        let b = Buffer::from_slice(&[0, 1, 2, 3]).slice(1, 3);
501        assert_eq!(a, b);
502        assert_ne!(a, Buffer::from_slice(&[1, 2]));
503    }
504
505    #[test]
506    fn conversions_and_collect() {
507        assert_eq!(Buffer::from(vec![1u8, 2]).as_slice(), &[1, 2]);
508        assert_eq!(Buffer::from(&b"hi"[..]).as_slice(), b"hi");
509        let collected: Buffer = (0u8..4).collect();
510        assert_eq!(collected.as_slice(), &[0, 1, 2, 3]);
511        assert_eq!(Buffer::zeroed(3).as_slice(), &[0, 0, 0]);
512        assert_eq!(&*Buffer::from_slice(b"deref"), b"deref");
513    }
514
515    #[test]
516    fn from_scalars_packs_native_bytes() {
517        let buffer = Buffer::from_scalars(&[1u16, 0x0201]);
518        assert_eq!(buffer.len(), 4);
519        let typed = buffer.typed::<u16>().unwrap();
520        assert_eq!(typed.as_slice(), &[1, 0x0201]);
521    }
522
523    #[test]
524    fn debug_shows_sharing() {
525        let buffer = Buffer::from_slice(&[1, 2, 3]);
526        let rendered = format!("{buffer:?}");
527        assert!(rendered.contains("len: 3"), "{rendered}");
528        assert!(rendered.contains("shared: 1"), "{rendered}");
529    }
530
531    #[test]
532    fn from_arc_shares_without_copying() {
533        let arc = Arc::new(AlignedBuf::from_slice(b"arc"));
534        let a = Buffer::from_arc(Arc::clone(&arc));
535        let b = Buffer::from_arc(arc);
536        assert_eq!(a.as_ptr(), b.as_ptr());
537        assert_eq!(a.as_slice(), b"arc");
538    }
539}