Struct FieldBuffer 

pub struct FieldBuffer<P: PackedField, Data: Deref<Target = [P]> = Vec<P>> { /* private fields */ }

A power-of-two-sized buffer containing field elements, stored in packed fields.

The backing store length is fully determined by log_len:

words.len() == 1 << log_len.saturating_sub(P::LOG_WIDTH)

A buffer shorter than one packed word still occupies a whole word. The lanes at and past the logical length are then not elements of the buffer:

WIDTH = 4, log_len = 1

word:  [ s_0, s_1, dead, dead ]
         ^^^^^^^^  live prefix

Nothing reads a dead lane as an element. Equality and the halving routines touch the live prefix only.

Truncation additionally zeros the dead lanes it creates. Other constructors may leave whatever the caller’s store held there.

Implementations

impl<P: PackedField, Data: Deref<Target = [P]>> FieldBuffer<P, Data>

pub fn chunk( &self, log_chunk_size: usize, chunk_index: usize, ) -> FieldSlice<'_, P>

Get an aligned chunk of size 2^log_chunk_size.

A chunk’s start offset is a multiple of its size. So this yields the same chunk that stepping the shared iterator to that index would.

Preconditions

• log_chunk_size must be at most log_len.
• chunk_index must be less than the chunk count.

pub fn chunks(&self, log_chunk_size: usize) -> Chunks<'_, P>

Split the buffer into chunks of size 2^log_chunk_size.

Any size up to the buffer’s length works, matching what the parallel iterator accepts. A chunk of at least one packed word borrows a run of the store. A smaller one arrives as a copy of its lanes, repacked to start at lane 0.

Preconditions

• log_chunk_size must be at most log_len.

pub fn par_chunks( &self, log_chunk_size: usize, ) -> impl IndexedParallelIterator<Item = FieldSlice<'_, P>>

Creates an iterator over chunks of size 2^log_chunk_size in parallel.

Preconditions

• log_chunk_size must be at most log_len.

pub fn par_chunk_scalars( &self, log_chunk_size: usize, ) -> impl IndexedParallelIterator<Item: Iterator<Item = P::Scalar> + Send + Clone + '_>

Creates a parallel iterator over the scalars of each chunk of 2^log_chunk_size elements.

The scalar-yielding counterpart to the parallel chunk iterator:

chunk i  ->  scalars [i * 2^log_chunk_size, (i+1) * 2^log_chunk_size)

A chunk takes one of two shapes, chosen once before any scalar is read:

chunk >= one packed word  ->  a run of whole words
chunk <  one packed word  ->  a lane range inside a single word

The buffer-yielding iterator instead repacks a sub-word chunk into an owned word. Prefer this method when the consumer only reads scalars, since it copies nothing.

Preconditions

• log_chunk_size must be at most log_len.

impl<P: PackedField, Data: DerefMut<Target = [P]>> FieldBuffer<P, Data>

pub fn chunks_mut(&mut self, log_chunk_size: usize) -> ChunksMut<'_, P>

Split the buffer into mutable chunks of size 2^log_chunk_size.

A chunk must span whole words, unlike the shared iterator, which takes any size. Chunks below the packing width share a word, so lending them out means lending copies. Each copy live at once would need its own write-back into that word.

WIDTH = 4, log_chunk_size = 1  ->  word 0 = [chunk 0 | chunk 1]

Reach for the single-chunk mutable accessor at such a size, which guards one copy.

Preconditions

• log_chunk_size must be at least P::LOG_WIDTH and at most log_len.

pub fn chunk_mut( &mut self, log_chunk_size: usize, chunk_index: usize, ) -> ChunkMut<'_, P>

Get a mutable aligned chunk of size 2^log_chunk_size.

Addresses the same chunk as the shared accessor, and lends it mutably.

A chunk of at least one packed word is lent straight from the store, so edits land at once. A smaller one shares a word with its neighbours, so it comes back behind a write-back guard. The guard hands out a copy of the chunk’s lanes and merges the edits back when it drops.

Unlike the mutable chunk iterator, this takes any chunk size up to the buffer’s length. Lending exactly one chunk is what makes a sub-word size safe. A second live copy of the same word would merge over the first.

Preconditions

• log_chunk_size must be at most log_len.
• chunk_index must be less than the chunk count.

impl<'a, P: PackedField> FieldBuffer<P, FieldSliceData<'a, P>>

pub fn from_slice(log_len: usize, slice: &'a [P]) -> Self

Create a new FieldSlice from a slice of packed words.

Preconditions

• slice.len() must equal the expected packed length for log_len.

impl<'a, P: PackedField> FieldBuffer<P, &'a mut [P]>

pub fn from_slice(log_len: usize, slice: &'a mut [P]) -> Self

Create a new FieldSliceMut from a mutable slice of packed words.

Preconditions

• slice.len() must equal the expected packed length for log_len.

impl<P: PackedField> FieldBuffer<P>

pub fn from_values(values: &[P::Scalar]) -> Self

Create a new FieldBuffer from a vector of values.

Preconditions

• values.len() must be a power of two.

pub fn zeros(log_len: usize) -> Self

Builds a buffer of 2^log_len zeros.

pub fn scalar_with_capacity(value: P::Scalar, log_capacity: usize) -> Self

Builds a one-element buffer holding value, with room reserved to grow.

The store is sized for 2^log_capacity elements up front. Growing the buffer to that many therefore never reallocates.

impl<P: PackedField, Data: VecLike<P>> FieldBuffer<P, Data>

pub fn zeros_in<A>(alloc: &A, log_len: usize) -> Self

where A: Allocator<Vec<P> = Data>,

Builds a zeroed buffer of 2^log_len elements, backed by memory drawn from alloc.

The allocator-aware counterpart to the plain zeroed constructor. Under a pool the result is a recyclable buffer rather than a fresh allocation.

pub fn from_view_in<A>(alloc: &A, src: FieldSlice<'_, P>) -> Self

where A: Allocator<Vec<P> = Data>,

Copies a borrowed buffer into memory drawn from alloc.

Whole packed words are copied, dead lanes and all, so the copy is bit-identical. A long source spreads across workers.

pub fn from_view_with_capacity_in<A>( alloc: &A, src: FieldSlice<'_, P>, log_capacity: usize, ) -> Self

where A: Allocator<Vec<P> = Data>,

Copies a borrowed buffer into memory drawn from alloc, with room reserved to grow.

The buffer spans src.log_len() elements and its store is sized for 2^log_capacity. Growing it to that many elements therefore never reallocates. Self::repeat_extend is the growth this reserves for.

Whole packed words are copied, dead lanes and all, so the copy is bit-identical. A long source spreads across workers.

Panics

Panics if log_capacity is shorter than what src spans.

pub fn repeat_extend(&mut self, log_len: usize)

Grows the buffer to span 2^log_len elements, repeating what it already holds.

    [x]  ->  [x | x | x | x]

This is the buffer’s Vec::extend_from_within, split across workers. Every copy is drawn from the live prefix, so one pass fills the whole buffer.

Returns the buffer untouched when it already spans that many elements.

Panics

Panics if log_len is shorter than what the buffer already spans. Panics if the store has no room reserved for 2^log_len elements.

pub fn from_values_in<A>(alloc: &A, values: &[P::Scalar]) -> Self

where A: Allocator<Vec<P> = Data>,

Builds a buffer from scalar values, directly into memory drawn from alloc.

The allocator-aware counterpart to building from a scalar slice. Packing happens straight into the allocator’s buffer, so no intermediate vector is copied. Under a pool the result is a recyclable buffer.

Preconditions

• values.len() must be a power of two.

pub fn zero_extend_in<A>(self, alloc: &A, log_len: usize) -> Self

where A: Allocator<Vec<P> = Data>,

Grows the buffer to span log_len variables, padding the new positions with zeros.

Returns the buffer untouched when it already spans that many. Padding the shorter of two buffers to match the longer hits that case when both are equal.

New memory comes from alloc. A pooled buffer therefore stays pooled, instead of escaping the pool on a reallocation.

Panics

Panics if log_len is shorter than what the buffer already spans. Shrinking is a separate operation. Silently returning a narrower buffer than asked for would hide the mistake.

impl<P: PackedField, Data: Deref<Target = [P]>> FieldBuffer<P, Data>

pub fn new(log_len: usize, words: Data) -> Self

Create a new FieldBuffer from a slice of packed words.

Preconditions

• words.len() must equal the expected packed length for log_len.

pub fn into_inner(self) -> Data

Consumes the buffer and returns its backing data store.

pub const fn log_len(&self) -> usize

Returns log2 the number of field elements.

pub const fn len(&self) -> usize

Returns the number of field elements.

pub fn as_view(&self) -> FieldSlice<'_, P>

Borrows the whole buffer as a shared view.

pub fn get(&self, index: usize) -> P::Scalar

Get a field element at the given index.

Preconditions

• the index is in the range 0..self.len()

pub fn iter_scalars( &self, ) -> impl Iterator<Item = P::Scalar> + Send + Clone + '_

Returns an iterator over the scalar elements in the buffer.

pub fn iter_packed(&self) -> Iter<'_, P>

Returns an iterator over the packed words the elements occupy.

The run covers the live words only, never a store’s spare room past them. A buffer shorter than one packed word yields that one word whole, dead lanes and all.

pub fn split_half(&self) -> (FieldSlice<'_, P>, FieldSlice<'_, P>)

Splits the buffer in half and returns a pair of borrowed slices.

Preconditions

• self.log_len() must be greater than 0.

impl<P: PackedField, Data: DerefMut<Target = [P]>> FieldBuffer<P, Data>

pub fn as_mut_view(&mut self) -> FieldSliceMut<'_, P>

Borrows the whole buffer as a mutable view.

pub fn set(&mut self, index: usize, value: P::Scalar)

Set a field element at the given index.

Preconditions

• the index is in the range 0..self.len()

pub fn iter_packed_mut(&mut self) -> IterMut<'_, P>

Returns a mutable iterator over the packed words the elements occupy.

The mutable counterpart of the shared word iterator, covering the same run of words. A final word below the packing width is lent out whole, dead lanes included.

pub fn into_split_half(self) -> SplitMut<P, Data>

Consumes the buffer and halves it, returning a guard that owns the store.

The guard lends out the two halves mutably.

When both halves live inside one packed word, the guard holds detached copies of them. Those are merged back into the original word when it drops.

Preconditions

• self.log_len() must be greater than 0.

pub fn split_half_mut(&mut self) -> SplitMut<P, &mut [P]>

Halves the buffer through a mutable borrow, rather than consuming it.

Equivalent to borrowing the buffer as a mutable view and halving that.

Preconditions

• self.log_len() must be greater than 0.

impl<P: PackedField, Data: BufferData<P>> FieldBuffer<P, Data>

pub fn truncate(&mut self, new_log_len: usize)

Truncates the buffer to a shorter length, shrinking the backing store to match.

Asking for a length at or above the current one does nothing.

A result shorter than one packed word has the dead lanes of its final word zeroed. That upholds the invariant that lanes past the logical length are zero.

Trait Implementations

impl<P: PackedField, Data: DerefMut<Target = [P]>> AsMut<[P]> for FieldBuffer<P, Data>

fn as_mut(&mut self) -> &mut [P]

Converts this type into a mutable reference of the (usually inferred) input type.

impl<P: PackedField, Data: Deref<Target = [P]>> AsRef<[P]> for FieldBuffer<P, Data>

fn as_ref(&self) -> &[P]

Converts this type into a shared reference of the (usually inferred) input type.

impl<P: Clone + PackedField, Data: Clone + Deref<Target = [P]>> Clone for FieldBuffer<P, Data>

fn clone(&self) -> FieldBuffer<P, Data>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<P: PackedField, Data: Deref<Target = [P]> + Copy> Copy for FieldBuffer<P, Data>

impl<P: Debug + PackedField, Data: Debug + Deref<Target = [P]>> Debug for FieldBuffer<P, Data>

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

Formats the value using the given formatter.

impl<P: Eq + PackedField, Data: Eq + Deref<Target = [P]>> Eq for FieldBuffer<P, Data>

impl<'a, P: PackedField, Data: Deref<Target = [P]>> From<&'a FieldBuffer<P, Data>> for FieldSlice<'a, P>

fn from(buffer: &'a FieldBuffer<P, Data>) -> Self

Converts to this type from the input type.

impl<'a, P: PackedField, Data: DerefMut<Target = [P]>> From<&'a mut FieldBuffer<P, Data>> for FieldSliceMut<'a, P>

fn from(buffer: &'a mut FieldBuffer<P, Data>) -> Self

Converts to this type from the input type.

impl<P: PackedField, Data: Deref<Target = [P]>> From<FieldBuffer<P, Data>> for StructuredBuffer<P, Data>

fn from(buffer: FieldBuffer<P, Data>) -> Self

Converts to this type from the input type.

impl<P: PackedField> FromIterator<<P as FieldOps>::Scalar> for FieldBuffer<P>

fn from_iter<I: IntoIterator<Item = P::Scalar>>(iter: I) -> Self

Builds a buffer over a fresh vector, packing the elements as they arrive.

Panics

Panics unless the number of elements is a power of two. An empty iterator panics too, matching what building from an empty scalar slice does. The count is known only once the iterator runs dry, so a bad one can only panic.

impl<P: PackedField, Data: Deref<Target = [P]>> PartialEq for FieldBuffer<P, Data>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.