Trait orx_split_vec::Growth

pub trait Growth: Clone + PseudoDefault {
    // Required method
    fn new_fragment_capacity_from(
        &self,
        fragment_capacities: impl ExactSizeIterator<Item = usize>,
    ) -> usize;

    // Provided methods
    fn first_fragment_capacity(&self) -> usize { ... }
    fn new_fragment_capacity<T>(&self, fragments: &[Fragment<T>]) -> usize { ... }
    fn get_fragment_and_inner_indices<T>(
        &self,
        _vec_len: usize,
        fragments: &[Fragment<T>],
        element_index: usize,
    ) -> Option<(usize, usize)> { ... }
    fn get_ptr<T>(
        &self,
        fragments: &[Fragment<T>],
        index: usize,
    ) -> Option<*const T> { ... }
    fn get_ptr_mut<T>(
        &self,
        fragments: &mut [Fragment<T>],
        index: usize,
    ) -> Option<*mut T> { ... }
    fn get_ptr_and_indices<T>(
        &self,
        fragments: &[Fragment<T>],
        index: usize,
    ) -> Option<(*const T, usize, usize)> { ... }
    fn get_ptr_mut_and_indices<T>(
        &self,
        fragments: &mut [Fragment<T>],
        index: usize,
    ) -> Option<(*mut T, usize, usize)> { ... }
    fn maximum_concurrent_capacity<T>(
        &self,
        fragments: &[Fragment<T>],
        fragments_capacity: usize,
    ) -> usize { ... }
    fn required_fragments_len<T>(
        &self,
        fragments: &[Fragment<T>],
        maximum_capacity: usize,
    ) -> Result<usize, String> { ... }
}

Growth strategy of a split vector.

Required Methods

fn new_fragment_capacity_from( &self, fragment_capacities: impl ExactSizeIterator<Item = usize>, ) -> usize

Given that the split vector contains fragments with the given fragment_capacities, returns the capacity of the next fragment.

Provided Methods

fn first_fragment_capacity(&self) -> usize

Given that the split vector has no fragments yet, returns the capacity of the first fragment.

fn new_fragment_capacity<T>(&self, fragments: &[Fragment<T>]) -> usize

Given that the split vector contains the given fragments, returns the capacity of the next fragment.

fn get_fragment_and_inner_indices<T>( &self, _vec_len: usize, fragments: &[Fragment<T>], element_index: usize, ) -> Option<(usize, usize)>

O(fragments.len()) Returns the location of the element with the given element_index on the split vector as a tuple of (fragment-index, index-within-fragment).

Returns None if the element index is out of bounds.

fn get_ptr<T>( &self, fragments: &[Fragment<T>], index: usize, ) -> Option<*const T>

O(fragments.len()) Returns a mutable reference to the index-th element of the split vector of the fragments.

Returns None if index-th position does not belong to the split vector; i.e., if index is out of cumulative capacity of fragments.

Safety

This method allows to write to a memory which is greater than the vector’s length. On the other hand, it will never return a pointer to a memory location that the vector does not own.

fn get_ptr_mut<T>( &self, fragments: &mut [Fragment<T>], index: usize, ) -> Option<*mut T>

O(fragments.len()) Returns a mutable reference to the index-th element of the split vector of the fragments.

Returns None if index-th position does not belong to the split vector; i.e., if index is out of cumulative capacity of fragments.

Safety

This method allows to write to a memory which is greater than the vector’s length. On the other hand, it will never return a pointer to a memory location that the vector does not own.

fn get_ptr_and_indices<T>( &self, fragments: &[Fragment<T>], index: usize, ) -> Option<(*const T, usize, usize)>

O(fragments.len()) Returns a mutable reference to the index-th element of the split vector of the fragments together with the index of the fragment that the element belongs to and index of the element withing the respective fragment.

Returns None if index-th position does not belong to the split vector; i.e., if index is out of cumulative capacity of fragments.

Safety

This method allows to write to a memory which is greater than the vector’s length. On the other hand, it will never return a pointer to a memory location that the vector does not own.

fn get_ptr_mut_and_indices<T>( &self, fragments: &mut [Fragment<T>], index: usize, ) -> Option<(*mut T, usize, usize)>

O(fragments.len()) Returns a mutable reference to the index-th element of the split vector of the fragments together with the index of the fragment that the element belongs to and index of the element withing the respective fragment.

Returns None if index-th position does not belong to the split vector; i.e., if index is out of cumulative capacity of fragments.

Safety

This method allows to write to a memory which is greater than the vector’s length. On the other hand, it will never return a pointer to a memory location that the vector does not own.

fn maximum_concurrent_capacity<T>( &self, fragments: &[Fragment<T>], fragments_capacity: usize, ) -> usize

Returns the maximum number of elements that can safely be stored in a concurrent program.

Note that pinned vectors already keep the elements pinned to their memory locations. Therefore, concurrently safe growth here corresponds to growth without requiring fragments collection to allocate. Recall that fragments contains meta information about the splits of the SplitVec, such as the capacity of each split.

This default implementation is not the most efficient as it allocates a small vector to compute the capacity. However, it is almost always possible to provide a non-allocating implementation provided that the concurrency is relevant. Doubling, Recursive and Linear growth strategies introduced in this crate all override this method.

Panics

Panics if fragments.len() < fragments_capacity, which must not hold.

fn required_fragments_len<T>( &self, fragments: &[Fragment<T>], maximum_capacity: usize, ) -> Result<usize, String>

Returns the number of fragments with this growth strategy in order to be able to reach a capacity of maximum_capacity of elements. Returns the error if it the growth strategy does not allow the required number of fragments.

This method is relevant and useful for concurrent programs, which helps in avoiding the fragments to allocate.

Object Safety

This trait is not object safe.

Implementors

impl Growth for Doubling

impl Growth for Linear

impl Growth for Recursive