Struct Poly 

pub struct Poly<T, A = GlobalAllocator>
where
    T: ?Sized,
    A: AllocatorCore,
{ /* private fields */ }

An owning pointer type like std::Box that supports custom allocators.

Examples

Creating and Mutating a Simple Type

This example demonstrates that Poly behaves pretty much like a Box with allocator support for simple types.

use diskann_quantization::alloc::{Poly, GlobalAllocator};

// `Poly` constructors can fail due to allocator errors, so return `Results`.
let mut x = Poly::new(10usize, GlobalAllocator).unwrap();
assert_eq!(*x, 10);

*x = 50;
assert_eq!(*x, 50);

Creating and Mutating a Slice

The standard library trait FromIterator is not implemented for Poly because an allocator is required for all construction operations. Instead, the inherent method Poly::from_iter can be used, provided the iterator is one of the select few for which TrustedIter is implemented, indicating that the length of the iterator can be relied on in unsafe code.

use diskann_quantization::alloc::{Poly, GlobalAllocator};
let v = vec![
    "foo".to_string(),
    "bar".to_string(),
    "baz".to_string(),
];

let poly = Poly::from_iter(v.into_iter(), GlobalAllocator).unwrap();
assert_eq!(poly.len(), 3);
assert_eq!(poly[0], "foo");
assert_eq!(poly[1], "bar");
assert_eq!(poly[2], "baz");

Using a Custom Allocator

This crate provides a handful of custom allocators, including the super::BumpAllocator. It can be used to group together allocations into a single arena.

use diskann_quantization::{
    alloc::{Poly, BumpAllocator},
    num::PowerOfTwo
};

let dim = 10;

// Estimate how many bytes are needed to create two such slices. We can control the
// alignment of the base pointer for the `BumpAllocator` to avoid extra memory used
// to satisfy alignment.
let alloc = BumpAllocator::new(
    dim * (std::mem::size_of::<f64>() + std::mem::size_of::<u8>()),
    PowerOfTwo::new(64).unwrap(),
).unwrap();

let foo = Poly::<[f64], _>::from_iter(
   (0..dim).map(|i| i as f64),
   alloc.clone(),
).unwrap();

let bar = Poly::<[u8], _>::from_iter(
   (0..dim).map(|i| i as u8),
   alloc.clone(),
).unwrap();

// The base pointer for the allocated object in `foo` is the base pointer of the arena
// owned by the BumpAllocator.
assert_eq!(alloc.as_ptr(), Poly::as_ptr(&foo).cast::<u8>());

// The base pointer for the allocated object in `bar` is also within the arena owned
// by the BumpAllocator as well.
assert_eq!(
    unsafe { alloc.as_ptr().add(std::mem::size_of_val(&*foo)) },
    Poly::as_ptr(&bar).cast::<u8>(),
);

// The allocator is now full - so further allocations will fail.
assert!(Poly::new(10usize, alloc.clone()).is_err());

// If we drop the allocator, the clones inside the `Poly` containers will keep the
// backing memory alive.
std::mem::forget(alloc);
assert!(foo.iter().enumerate().all(|(i, v)| i as f64 == *v));
assert!(bar.iter().enumerate().all(|(i, v)| i as u8 == *v));

Using Trait Object

Poly is compatible with trait objects as well using the crate::poly! macro. A macro is needed because traits such as Unsize and CoerceUnsized are unstable.

use diskann_quantization::{
    poly,
    alloc::BumpAllocator,
    num::PowerOfTwo,
};
use std::fmt::Display;

let message = "hello world";

let alloc = BumpAllocator::new(512, PowerOfTwo::new(64).unwrap()).unwrap();

// Create a new `Poly` trait object for `std::fmt::Display`. Due to limitations in the
// macro matching rules, identifiers are needed for the object and allocator.
let clone = alloc.clone();
let poly = poly!(std::fmt::Display, message, clone).unwrap();
assert_eq!(poly.to_string(), "hello world");

// Here - we demonstrate the full type of the returned `Poly`.
let clone = alloc.clone();
let _: diskann_quantization::alloc::Poly<dyn Display, _> = poly!(
    Display,
    message,
    clone
).unwrap();

// If additional auto traits are needed like `Send`, the brace-style syntax can be used
let clone = alloc.clone();
let poly = poly!({ std::fmt::Display + Send + Sync }, message, clone).unwrap();

// Existing `Poly` objects can be converted using the same macro.
let poly = diskann_quantization::alloc::Poly::new(message, alloc.clone()).unwrap();
let poly = poly!(std::fmt::Display, poly);
assert_eq!(poly.to_string(), "hello world");

Naturally, the implementation of the trait is checked for validity.

Implementations

impl<T, A> Poly<T, A>

where A: AllocatorCore,

pub fn new(value: T, allocator: A) -> Result<Self, AllocatorError>

Allocate memory from allocator and place value into that location.

pub fn new_with<F, E>(f: F, allocator: A) -> Result<Self, CompoundError<E>>

where F: FnOnce(A) -> Result<T, E>, A: Clone,

Allocate memory from allocator for T, then run the provided closure, moving the result into the allocated memory.

Because this allocates the storage for the object first, it can be used in situations where the object to be allocated will use the same allocator, but should be allocated after the base.

pub fn new_uninit( allocator: A, ) -> Result<Poly<MaybeUninit<T>, A>, AllocatorError>

Construct a new Poly with uninitialized contents in allocator.

impl<T, A> Poly<T, A>

where T: ?Sized, A: AllocatorCore,

pub fn into_raw(this: Self) -> (NonNull<T>, A)

Consume Self, returning the wrapped pointer and allocator.

This function does not trigger any drop logic nor deallocation.

pub unsafe fn from_raw(ptr: NonNull<T>, allocator: A) -> Self

Construct a Poly from a raw pointer and allocator.

After calling this function, the returned Poly will assume ownership of the provided pointer.

Safety

The value of ptr must have runtime alignment compatible with

std::mem::Layout::for_value(&*ptr.as_ptr())

and point to a valid object of type T.

The pointer must point to memory currently allocated in allocator.

pub fn as_ptr(this: &Self) -> *const T

Return a pointer to the object managed by this Poly.

pub fn allocator(&self) -> &A

Return a reference to the underlying allocator.

impl<T, A> Poly<MaybeUninit<T>, A>

where A: AllocatorCore,

pub unsafe fn assume_init(self) -> Poly<T, A>

Converts to Poly<T, A>.

Safety

The caller must ensure that the value has truly been initialized.

impl<T, A> Poly<[T], A>

where A: AllocatorCore,

pub fn new_uninit_slice( len: usize, allocator: A, ) -> Result<Poly<[MaybeUninit<T>], A>, AllocatorError>

Construct a new Poly containing an uninitialized slice of length len with memory allocated from allocator.

pub fn from_iter<I>(iter: I, allocator: A) -> Result<Self, AllocatorError>

where I: TrustedIter<Item = T>,

Construct a new Poly from the iterator.

impl<T, A> Poly<[MaybeUninit<T>], A>

where A: AllocatorCore,

pub unsafe fn assume_init(self) -> Poly<[T], A>

Converts to Poly<[T], A>.

Safety

The caller must ensure that the value has truly been initialized.

impl<T, A> Poly<[T], A>

where A: AllocatorCore, T: Clone,

pub fn broadcast( value: T, len: usize, allocator: A, ) -> Result<Self, AllocatorError>

Construct a new Poly slice with each entry initialized to value.

Trait Implementations

impl<A> Allocator for Poly<[u8], A>

where A: Allocator,

Available on crate feature flatbuffers only.

type Error = AllocatorError

A type describing allocation failures

fn grow_downwards(&mut self) -> Result<(), Self::Error>

Grows the buffer, with the old contents being moved to the end.

fn len(&self) -> usize

Returns the size of the internal buffer in bytes.

impl<T, A> AsMutPtr for Poly<[T], A>

where A: AllocatorCore,

Safety: Slices never return a null pointer. A mutable reference to self signals an exclusive borrow - so the underlying pointer is indeed mutable.

fn as_mut_ptr(&mut self) -> *mut T

impl<T, A> AsPtr for Poly<[T], A>

where A: AllocatorCore,

Safety: Slices never return a null pointer.

type Type = T

fn as_ptr(&self) -> *const T

impl<T, A> Debug for Poly<T, A>

where T: ?Sized + Debug, A: AllocatorCore + Debug,

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

Formats the value using the given formatter.

impl<T, A> Deref for Poly<T, A>

where T: ?Sized, A: AllocatorCore,

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T, A> DerefMut for Poly<T, A>

where T: ?Sized, A: AllocatorCore,

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T, A> Drop for Poly<T, A>

where T: ?Sized, A: AllocatorCore,

fn drop(&mut self)

Executes the destructor for this type.

impl<T> From<Box<[T]>> for Poly<[T], GlobalAllocator>

fn from(value: Box<[T]>) -> Self

Converts to this type from the input type.

impl<T, A> PartialEq for Poly<T, A>

where T: ?Sized + PartialEq, A: AllocatorCore,

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.

impl<T, A> Send for Poly<T, A>

where T: ?Sized + Send, A: AllocatorCore + Send,

impl<T, A> Sync for Poly<T, A>

where T: ?Sized + Sync, A: AllocatorCore + Sync,