nalgebra/base/
allocator.rs

Help
1//! Abstract definition of a matrix data storage allocator.
2
3use std::any::Any;
4
5use crate::base::constraint::{SameNumberOfColumns, SameNumberOfRows, ShapeConstraint};
6use crate::base::dimension::{Dim, U1};
7use crate::base::{DefaultAllocator, Scalar};
8use crate::storage::{IsContiguous, RawStorageMut};
9use crate::StorageMut;
10use std::fmt::Debug;
11use std::mem::MaybeUninit;
12
13/// A matrix allocator of a memory buffer that may contain `R::to_usize() * C::to_usize()`
14/// elements of type `T`.
15///
16/// An allocator is said to be:
17///   − static:  if `R` and `C` both implement `DimName`.
18///   − dynamic: if either one (or both) of `R` or `C` is equal to `Dynamic`.
19///
20/// Every allocator must be both static and dynamic. Though not all implementations may share the
21/// same `Buffer` type.
22pub trait Allocator<T, R: Dim, C: Dim = U1>: Any + Sized {
23    /// The type of buffer this allocator can instanciate.
24    type Buffer: StorageMut<T, R, C> + IsContiguous + Clone + Debug;
25    /// The type of buffer with uninitialized components this allocator can instanciate.
26    type BufferUninit: RawStorageMut<MaybeUninit<T>, R, C> + IsContiguous;
27
28    /// Allocates a buffer with the given number of rows and columns without initializing its content.
29    fn allocate_uninit(nrows: R, ncols: C) -> Self::BufferUninit;
30
31    /// Assumes a data buffer to be initialized.
32    ///
33    /// # Safety
34    /// The user must make sure that every single entry of the buffer has been initialized,
35    /// or Undefined Behavior will immediately occur.    
36    unsafe fn assume_init(uninit: Self::BufferUninit) -> Self::Buffer;
37
38    /// Allocates a buffer initialized with the content of the given iterator.
39    fn allocate_from_iterator<I: IntoIterator<Item = T>>(
40        nrows: R,
41        ncols: C,
42        iter: I,
43    ) -> Self::Buffer;
44}
45
46/// A matrix reallocator. Changes the size of the memory buffer that initially contains (`RFrom` ×
47/// `CFrom`) elements to a smaller or larger size (`RTo`, `CTo`).
48pub trait Reallocator<T: Scalar, RFrom: Dim, CFrom: Dim, RTo: Dim, CTo: Dim>:
49    Allocator<T, RFrom, CFrom> + Allocator<T, RTo, CTo>
50{
51    /// Reallocates a buffer of shape `(RTo, CTo)`, possibly reusing a previously allocated buffer
52    /// `buf`. Data stored by `buf` are linearly copied to the output:
53    ///
54    /// # Safety
55    /// The following invariants must be respected by the implementors of this method:
56    /// * The copy is performed as if both were just arrays (without taking into account the matrix structure).
57    /// * If the underlying buffer is being shrunk, the removed elements must **not** be dropped
58    ///   by this method. Dropping them is the responsibility of the caller.
59    unsafe fn reallocate_copy(
60        nrows: RTo,
61        ncols: CTo,
62        buf: <Self as Allocator<T, RFrom, CFrom>>::Buffer,
63    ) -> <Self as Allocator<T, RTo, CTo>>::BufferUninit;
64}
65
66/// The number of rows of the result of a componentwise operation on two matrices.
67pub type SameShapeR<R1, R2> = <ShapeConstraint as SameNumberOfRows<R1, R2>>::Representative;
68
69/// The number of columns of the result of a componentwise operation on two matrices.
70pub type SameShapeC<C1, C2> = <ShapeConstraint as SameNumberOfColumns<C1, C2>>::Representative;
71
72// TODO: Bad name.
73/// Restricts the given number of rows and columns to be respectively the same.
74pub trait SameShapeAllocator<T, R1, C1, R2, C2>:
75    Allocator<T, R1, C1> + Allocator<T, SameShapeR<R1, R2>, SameShapeC<C1, C2>>
76where
77    R1: Dim,
78    R2: Dim,
79    C1: Dim,
80    C2: Dim,
81    ShapeConstraint: SameNumberOfRows<R1, R2> + SameNumberOfColumns<C1, C2>,
82{
83}
84
85impl<T, R1, R2, C1, C2> SameShapeAllocator<T, R1, C1, R2, C2> for DefaultAllocator
86where
87    R1: Dim,
88    R2: Dim,
89    C1: Dim,
90    C2: Dim,
91    DefaultAllocator: Allocator<T, R1, C1> + Allocator<T, SameShapeR<R1, R2>, SameShapeC<C1, C2>>,
92    ShapeConstraint: SameNumberOfRows<R1, R2> + SameNumberOfColumns<C1, C2>,
93{
94}
95
96// XXX: Bad name.
97/// Restricts the given number of rows to be equal.
98pub trait SameShapeVectorAllocator<T, R1, R2>:
99    Allocator<T, R1> + Allocator<T, SameShapeR<R1, R2>> + SameShapeAllocator<T, R1, U1, R2, U1>
100where
101    R1: Dim,
102    R2: Dim,
103    ShapeConstraint: SameNumberOfRows<R1, R2>,
104{
105}
106
107impl<T, R1, R2> SameShapeVectorAllocator<T, R1, R2> for DefaultAllocator
108where
109    R1: Dim,
110    R2: Dim,
111    DefaultAllocator: Allocator<T, R1, U1> + Allocator<T, SameShapeR<R1, R2>>,
112    ShapeConstraint: SameNumberOfRows<R1, R2>,
113{
114}
nalgebra/base/allocator.rs

nalgebra/base/
allocator.rs
