Struct AppendOnlyVec 

pub struct AppendOnlyVec<T, const INLINE: usize = 0, const BIN_OFFSET: u32 = 3> { /* private fields */ }

Append only vec of items T.

This vec never moves and never removes items. As long as this vec is around, references to all the data it stores stay valid, and items can be added without a mutable reference to it.

The first INLINE items are stored in the vec itself, so a vec that never outgrows them allocates nothing. Further items go to bins that are allocated on demand, each double the size of the one before, starting at 2^BIN_OFFSET items. The directory of these bins is itself only allocated once the inline items are used up. Capacity is bounded by memory and by Self::MAX_LEN: INLINE + 2^BIN_OFFSET * (2^32 - 1) items, or what a usize counts on smaller targets.

Pushes are not lock-free: items are published in index order, so a push suspended between reserving and publishing its slot delays later pushes until it resumes. Never push from a signal or interrupt handler.

Every push can carry a tag: Self::tags is the bitwise or of the tags of all pushed items, which lets a reader skip a vec that cannot hold what it looks for (see Self::push_tagged).

Implementations

impl<T, const INLINE: usize, const BIN_OFFSET: u32> AppendOnlyVec<T, INLINE, BIN_OFFSET>

pub const MAX_LEN: usize

Available on crate features grpc and http and std only.

The most items it holds: what its bins have room for, at most half a usize, so every index and the count past the last fit, and pushes past the limit, however many at once, undo their reservation without wrapping it.

pub fn new() -> AppendOnlyVec<T, INLINE, BIN_OFFSET>

Available on crate features grpc and http and std only.

Create a new, empty AppendOnlyVec of T items. Allocates nothing.

use rama_utils::collections::AppendOnlyVec;
// This should fail because the first bin is too large for usize
_ = AppendOnlyVec::<usize, 0, 40>::new();

pub unsafe fn init_in_place(slot: *mut AppendOnlyVec<T, INLINE, BIN_OFFSET>)

Available on crate features grpc and http and std only.

Write an empty vec to slot, without touching its inline item storage.

Same as writing Self::new there, minus moving the (uninitialized) inline storage: for a vec inside a larger allocation that copy is most of the cost of creating it.

Safety

slot must be valid for writes and aligned. Whatever it held is overwritten without being dropped.

pub fn push(&self, element: T) -> usize

Available on crate features grpc and http and std only.

Pushes an element and returns its index.

Panics

Once it holds Self::MAX_LEN items, as a Vec past its capacity, leaving the vec as it was: see Self::try_push.

pub fn try_push(&self, element: T) -> Result<usize, T>

Available on crate features grpc and http and std only.

Pushes an element and returns its index, or gives it back once it holds Self::MAX_LEN items.

pub fn push_tagged(&self, element: T, tag: usize) -> usize

Available on crate features grpc and http and std only.

Pushes an element tagged with tag, and returns its index.

The tag is added to Self::tags before the element is published, so a reader that sees the element also sees its tag: a reader that finds a tag missing from Self::tags can skip this vec for it, as no item with that tag was published before.

pub fn tags(&self) -> usize

Available on crate features grpc and http and std only.

The bitwise or of the tags of all items pushed so far, see Self::push_tagged.

pub fn get(&self, idx: usize) -> Option<&T>

Available on crate features grpc and http and std only.

pub fn is_empty(&self) -> bool

Available on crate features grpc and http and std only.

pub fn len(&self) -> usize

Available on crate features grpc and http and std only.

pub fn iter(&self) -> Iter<'_, T, INLINE, BIN_OFFSET>

Available on crate features grpc and http and std only.

Returns an iterator over the elements currently in the vector. The iterator snapshots the length at creation time.

pub fn chunks(&self) -> Chunks<'_, T, INLINE, BIN_OFFSET>

Available on crate features grpc and http and std only.

Returns the elements currently in the vector as contiguous slices, oldest first.

The inline items are one slice and every bin is one more, so walking the elements with two nested loops does the bin arithmetic once per bin instead of once per element like Self::iter. Like Self::iter this snapshots the length at creation time. The iterator is double ended: .rev() yields the newest slice first.

pub unsafe fn get_unchecked(&self, idx: usize) -> &T

Available on crate features grpc and http and std only.

Get item with idx from this vec

Safety

This function is safe if idx < self.len()

Trait Implementations

impl<T, const INLINE: usize, const BIN_OFFSET: u32> Debug for AppendOnlyVec<T, INLINE, BIN_OFFSET>

where T: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T, const INLINE: usize, const BIN_OFFSET: u32> Default for AppendOnlyVec<T, INLINE, BIN_OFFSET>

fn default() -> AppendOnlyVec<T, INLINE, BIN_OFFSET>

Returns the “default value” for a type.

impl<T, const INLINE: usize, const BIN_OFFSET: u32> Drop for AppendOnlyVec<T, INLINE, BIN_OFFSET>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<T, const INLINE: usize, const BIN_OFFSET: u32> Extend<T> for AppendOnlyVec<T, INLINE, BIN_OFFSET>

fn extend<I>(&mut self, iter: I)

where I: IntoIterator<Item = T>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: T)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T, const INLINE: usize, const BIN_OFFSET: u32> Extend<T> for &AppendOnlyVec<T, INLINE, BIN_OFFSET>

fn extend<I>(&mut self, iter: I)

where I: IntoIterator<Item = T>,

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: T)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T, const INLINE: usize, const BIN_OFFSET: u32> FromIterator<T> for AppendOnlyVec<T, INLINE, BIN_OFFSET>

fn from_iter<I>(iter: I) -> AppendOnlyVec<T, INLINE, BIN_OFFSET>

where I: IntoIterator<Item = T>,

Creates a value from an iterator.

impl<T, const INLINE: usize, const BIN_OFFSET: u32> Index<usize> for AppendOnlyVec<T, INLINE, BIN_OFFSET>

type Output = T

The returned type after indexing.

fn index( &self, idx: usize, ) -> &<AppendOnlyVec<T, INLINE, BIN_OFFSET> as Index<usize>>::Output

Performs the indexing (container[index]) operation.

impl<'a, T, const INLINE: usize, const BIN_OFFSET: u32> IntoIterator for &'a AppendOnlyVec<T, INLINE, BIN_OFFSET>

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = Iter<'a, T, INLINE, BIN_OFFSET>

Which kind of iterator are we turning this into?

fn into_iter( self, ) -> <&'a AppendOnlyVec<T, INLINE, BIN_OFFSET> as IntoIterator>::IntoIter

Creates an iterator from a value.

impl<T, const INLINE: usize, const BIN_OFFSET: u32> IntoIterator for AppendOnlyVec<T, INLINE, BIN_OFFSET>

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIterOwned<T, INLINE, BIN_OFFSET>

Which kind of iterator are we turning this into?

fn into_iter( self, ) -> <AppendOnlyVec<T, INLINE, BIN_OFFSET> as IntoIterator>::IntoIter

Creates an iterator from a value.

impl<T, const INLINE: usize, const BIN_OFFSET: u32> Send for AppendOnlyVec<T, INLINE, BIN_OFFSET>

where T: Send,

impl<T, const INLINE: usize, const BIN_OFFSET: u32> Sync for AppendOnlyVec<T, INLINE, BIN_OFFSET>

where T: Send + Sync,