Crate arc_slice 

A utility library for working with shared slices of memory.

This crate provides efficient shared buffer implementations ArcSlice and ArcSliceMut.

Examples

use arc_slice::{ArcSlice, ArcSliceMut};

let mut bytes_mut: ArcSliceMut<[u8]> = ArcSliceMut::new();
bytes_mut.extend_from_slice(b"Hello world");

let mut bytes: ArcSlice<[u8]> = bytes_mut.freeze();

let a: ArcSlice<[u8]> = bytes.subslice(0..5);
assert_eq!(a, b"Hello");

let b: ArcSlice<[u8]> = bytes.split_to(6);
assert_eq!(bytes, b"world");
assert_eq!(b, b"Hello ");

Depending on its layout, ArcSlice can also support arbitrary buffers, e.g. shared memory, and provides optional metadata that can be attached to the buffer.

use std::{
    fs::File,
    path::{Path, PathBuf},
};

use arc_slice::{buffer::AsRefBuffer, layout::ArcLayout, ArcBytes};
use memmap2::Mmap;

let path = Path::new("README.md").to_owned();
let file = File::open(&path)?;
let mmap = unsafe { Mmap::map(&file)? };

let buffer = AsRefBuffer(mmap);
let bytes: ArcBytes<ArcLayout<true>> = ArcBytes::from_buffer_with_metadata(buffer, path);
assert!(bytes.starts_with(b"# arc-slice"));
assert_eq!(bytes.metadata::<PathBuf>().unwrap(), Path::new("README.md"));

Features

The crate provides the following optional features:

• abort-on-refcount-overflow (default): abort on refcount overflow; when disabled, the refcount saturates on overflow, leaking allocated memory (as in Linux kernel refcounting).
• bstr: implement slice traits for bstr crate, allowing usage of ArcSlice<BStr>.
• bytemuck: use bytemuck::Zeroable as a bound for zero-initialization with ArcSliceMut::zeroed.
• bytes: implement Buf and BufMut traits for ArcSlice and ArcSliceMut.
• inlined: enable Small String Optimization for ArcSlice via inlined::SmallArcSlice.
• oom-handling (default): enable global out-of-memory handling with infallible allocation methods.
• portable-atomic: use portable_atomic instead of core::sync::atomic.
• portable-atomic-util: implement traits for portable_atomic_util::Arc instead of alloc::sync::Arc.
• raw-buffer: enable RawBuffer and RawLayout.
• serde: implement Serialize and Deserialize for ArcSlice and ArcSliceMut.
• std: enable various std trait implementations and link to the standard library crate.

Additionally, the default layout can be overridden with these features:

• default-layout-any-buffer: set ArcLayout ANY_BUFFER to true.
• default-layout-static: set ArcLayout STATIC to true.
• default-layout-boxed-slice: override default layout to BoxedSliceLayout.
• default-layout-vec: override default layout to VecLayout.
• default-layout-raw: override default layout to RawLayout.
• default-layout-mut-any-buffer: set ArcLayout ANY_BUFFER to true for ArcSliceMut.
• default-layout-mut-vec: override default layout to VecLayout for ArcSliceMut.

Modules

buffer

Generic slice and buffer abstractions used by ArcSlice and ArcSliceMut.

error

Error types used in fallible allocation and buffer resizing.

inlinedinlined

Small String Optimization support for ArcSlice.

layout

The different layouts used by ArcSlice and ArcSliceMut.

Structs

ArcSlice

A thread-safe, cheaply cloneable and sliceable container.

ArcSliceBorrow

A borrowed view of an ArcSlice.

ArcSliceMut

A thread-safe, mutable and growable container.

Type Aliases

ArcBytes

An alias for ArcSlice<[u8], L>.

ArcBytesBorrow

An alias for ArcSliceBorrow<[u8], L>.

ArcBytesMut

An alias for ArcSliceMut<[u8], L>.

ArcStr

An alias for ArcSlice<str, L>.

ArcStrBorrow

An alias for ArcSliceBorrow<str, L>.

ArcStrMut

An alias for ArcSliceMut<str, L>.