2017-02-13 01:17:09 +08:00
|
|
|
|
//! Abstract definition of a matrix data storage allocator.
|
|
|
|
|
|
2021-08-03 00:41:46 +08:00
|
|
|
|
use std::any::Any;
|
2016-12-05 05:44:42 +08:00
|
|
|
|
|
2019-03-23 21:29:07 +08:00
|
|
|
|
use crate::base::constraint::{SameNumberOfColumns, SameNumberOfRows, ShapeConstraint};
|
|
|
|
|
use crate::base::dimension::{Dim, U1};
|
2021-08-03 00:41:46 +08:00
|
|
|
|
use crate::base::{DefaultAllocator, Scalar};
|
|
|
|
|
use crate::storage::{IsContiguous, RawStorageMut};
|
|
|
|
|
use crate::StorageMut;
|
|
|
|
|
use std::fmt::Debug;
|
|
|
|
|
use std::mem::MaybeUninit;
|
2016-12-05 05:44:42 +08:00
|
|
|
|
|
|
|
|
|
/// A matrix allocator of a memory buffer that may contain `R::to_usize() * C::to_usize()`
|
2021-04-11 17:00:38 +08:00
|
|
|
|
/// elements of type `T`.
|
2016-12-05 05:44:42 +08:00
|
|
|
|
///
|
|
|
|
|
/// An allocator is said to be:
|
|
|
|
|
/// − static: if `R` and `C` both implement `DimName`.
|
2023-01-14 23:22:27 +08:00
|
|
|
|
/// − dynamic: if either one (or both) of `R` or `C` is equal to `Dyn`.
|
2016-12-05 05:44:42 +08:00
|
|
|
|
///
|
|
|
|
|
/// Every allocator must be both static and dynamic. Though not all implementations may share the
|
|
|
|
|
/// same `Buffer` type.
|
2021-08-03 00:41:46 +08:00
|
|
|
|
pub trait Allocator<T, R: Dim, C: Dim = U1>: Any + Sized {
|
2023-02-01 14:48:06 +08:00
|
|
|
|
/// The type of buffer this allocator can instantiate.
|
2021-08-03 00:41:46 +08:00
|
|
|
|
type Buffer: StorageMut<T, R, C> + IsContiguous + Clone + Debug;
|
2023-02-01 14:48:06 +08:00
|
|
|
|
/// The type of buffer with uninitialized components this allocator can instantiate.
|
2021-08-03 00:41:46 +08:00
|
|
|
|
type BufferUninit: RawStorageMut<MaybeUninit<T>, R, C> + IsContiguous;
|
2016-12-05 05:44:42 +08:00
|
|
|
|
|
2021-08-03 00:41:46 +08:00
|
|
|
|
/// Allocates a buffer with the given number of rows and columns without initializing its content.
|
|
|
|
|
fn allocate_uninit(nrows: R, ncols: C) -> Self::BufferUninit;
|
2021-07-15 06:21:22 +08:00
|
|
|
|
|
2021-08-03 00:41:46 +08:00
|
|
|
|
/// Assumes a data buffer to be initialized.
|
2021-07-18 09:19:20 +08:00
|
|
|
|
///
|
|
|
|
|
/// # Safety
|
|
|
|
|
/// The user must make sure that every single entry of the buffer has been initialized,
|
|
|
|
|
/// or Undefined Behavior will immediately occur.
|
2021-08-03 00:41:46 +08:00
|
|
|
|
unsafe fn assume_init(uninit: Self::BufferUninit) -> Self::Buffer;
|
2021-07-18 02:01:03 +08:00
|
|
|
|
|
2021-08-03 00:41:46 +08:00
|
|
|
|
/// Allocates a buffer initialized with the content of the given iterator.
|
|
|
|
|
fn allocate_from_iterator<I: IntoIterator<Item = T>>(
|
|
|
|
|
nrows: R,
|
|
|
|
|
ncols: C,
|
|
|
|
|
iter: I,
|
|
|
|
|
) -> Self::Buffer;
|
2021-05-04 21:23:49 +08:00
|
|
|
|
|
2022-07-31 00:06:47 +08:00
|
|
|
|
#[inline]
|
2021-05-04 21:23:49 +08:00
|
|
|
|
/// Allocates a buffer initialized with the content of the given row-major order iterator.
|
|
|
|
|
fn allocate_from_row_iterator<I: IntoIterator<Item = T>>(
|
|
|
|
|
nrows: R,
|
|
|
|
|
ncols: C,
|
|
|
|
|
iter: I,
|
2022-07-31 00:06:47 +08:00
|
|
|
|
) -> Self::Buffer {
|
|
|
|
|
let mut res = Self::allocate_uninit(nrows, ncols);
|
|
|
|
|
let mut count = 0;
|
|
|
|
|
|
|
|
|
|
unsafe {
|
|
|
|
|
// OK because the allocated buffer is guaranteed to be contiguous.
|
|
|
|
|
let res_ptr = res.as_mut_slice_unchecked();
|
|
|
|
|
|
|
|
|
|
for (k, e) in iter
|
|
|
|
|
.into_iter()
|
|
|
|
|
.take(ncols.value() * nrows.value())
|
|
|
|
|
.enumerate()
|
|
|
|
|
{
|
|
|
|
|
let i = k / ncols.value();
|
|
|
|
|
let j = k % ncols.value();
|
|
|
|
|
// result[(i, j)] = e;
|
|
|
|
|
*res_ptr.get_unchecked_mut(i + j * nrows.value()) = MaybeUninit::new(e);
|
|
|
|
|
count += 1;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
assert!(
|
|
|
|
|
count == nrows.value() * ncols.value(),
|
|
|
|
|
"Matrix init. from row iterator: iterator not long enough."
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
<Self as Allocator<T, R, C>>::assume_init(res)
|
|
|
|
|
}
|
|
|
|
|
}
|
2021-07-15 06:21:22 +08:00
|
|
|
|
}
|
|
|
|
|
|
2021-08-03 00:41:46 +08:00
|
|
|
|
/// A matrix reallocator. Changes the size of the memory buffer that initially contains (`RFrom` ×
|
|
|
|
|
/// `CFrom`) elements to a smaller or larger size (`RTo`, `CTo`).
|
|
|
|
|
pub trait Reallocator<T: Scalar, RFrom: Dim, CFrom: Dim, RTo: Dim, CTo: Dim>:
|
2021-07-16 12:56:58 +08:00
|
|
|
|
Allocator<T, RFrom, CFrom> + Allocator<T, RTo, CTo>
|
2018-10-22 13:00:10 +08:00
|
|
|
|
{
|
2017-08-03 01:37:44 +08:00
|
|
|
|
/// Reallocates a buffer of shape `(RTo, CTo)`, possibly reusing a previously allocated buffer
|
|
|
|
|
/// `buf`. Data stored by `buf` are linearly copied to the output:
|
|
|
|
|
///
|
2021-07-04 11:19:07 +08:00
|
|
|
|
/// # Safety
|
2021-08-03 16:59:03 +08:00
|
|
|
|
/// The following invariants must be respected by the implementors of this method:
|
2021-08-03 23:02:42 +08:00
|
|
|
|
/// * The copy is performed as if both were just arrays (without taking into account the matrix structure).
|
|
|
|
|
/// * If the underlying buffer is being shrunk, the removed elements must **not** be dropped
|
|
|
|
|
/// by this method. Dropping them is the responsibility of the caller.
|
2018-02-02 19:26:35 +08:00
|
|
|
|
unsafe fn reallocate_copy(
|
|
|
|
|
nrows: RTo,
|
|
|
|
|
ncols: CTo,
|
2021-08-03 00:41:46 +08:00
|
|
|
|
buf: <Self as Allocator<T, RFrom, CFrom>>::Buffer,
|
2021-08-03 16:59:03 +08:00
|
|
|
|
) -> <Self as Allocator<T, RTo, CTo>>::BufferUninit;
|
2016-12-05 05:44:42 +08:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// The number of rows of the result of a componentwise operation on two matrices.
|
|
|
|
|
pub type SameShapeR<R1, R2> = <ShapeConstraint as SameNumberOfRows<R1, R2>>::Representative;
|
|
|
|
|
|
|
|
|
|
/// The number of columns of the result of a componentwise operation on two matrices.
|
|
|
|
|
pub type SameShapeC<C1, C2> = <ShapeConstraint as SameNumberOfColumns<C1, C2>>::Representative;
|
|
|
|
|
|
2020-11-15 23:57:49 +08:00
|
|
|
|
// TODO: Bad name.
|
2017-08-03 01:37:44 +08:00
|
|
|
|
/// Restricts the given number of rows and columns to be respectively the same.
|
2021-08-03 00:41:46 +08:00
|
|
|
|
pub trait SameShapeAllocator<T, R1, C1, R2, C2>:
|
2021-07-16 12:56:58 +08:00
|
|
|
|
Allocator<T, R1, C1> + Allocator<T, SameShapeR<R1, R2>, SameShapeC<C1, C2>>
|
2018-02-02 19:26:35 +08:00
|
|
|
|
where
|
2021-08-03 00:41:46 +08:00
|
|
|
|
R1: Dim,
|
|
|
|
|
R2: Dim,
|
|
|
|
|
C1: Dim,
|
|
|
|
|
C2: Dim,
|
2018-02-02 19:26:35 +08:00
|
|
|
|
ShapeConstraint: SameNumberOfRows<R1, R2> + SameNumberOfColumns<C1, C2>,
|
|
|
|
|
{
|
2016-12-05 05:44:42 +08:00
|
|
|
|
}
|
|
|
|
|
|
2021-08-03 00:41:46 +08:00
|
|
|
|
impl<T, R1, R2, C1, C2> SameShapeAllocator<T, R1, C1, R2, C2> for DefaultAllocator
|
2018-02-02 19:26:35 +08:00
|
|
|
|
where
|
2021-08-03 00:41:46 +08:00
|
|
|
|
R1: Dim,
|
|
|
|
|
R2: Dim,
|
|
|
|
|
C1: Dim,
|
|
|
|
|
C2: Dim,
|
2021-07-18 02:01:03 +08:00
|
|
|
|
DefaultAllocator: Allocator<T, R1, C1> + Allocator<T, SameShapeR<R1, R2>, SameShapeC<C1, C2>>,
|
2018-02-02 19:26:35 +08:00
|
|
|
|
ShapeConstraint: SameNumberOfRows<R1, R2> + SameNumberOfColumns<C1, C2>,
|
2020-04-06 00:49:48 +08:00
|
|
|
|
{
|
|
|
|
|
}
|
2016-12-05 05:44:42 +08:00
|
|
|
|
|
|
|
|
|
// XXX: Bad name.
|
2017-08-03 01:37:44 +08:00
|
|
|
|
/// Restricts the given number of rows to be equal.
|
2021-08-03 00:41:46 +08:00
|
|
|
|
pub trait SameShapeVectorAllocator<T, R1, R2>:
|
2021-07-18 02:01:03 +08:00
|
|
|
|
Allocator<T, R1> + Allocator<T, SameShapeR<R1, R2>> + SameShapeAllocator<T, R1, U1, R2, U1>
|
2018-02-02 19:26:35 +08:00
|
|
|
|
where
|
2021-08-03 00:41:46 +08:00
|
|
|
|
R1: Dim,
|
|
|
|
|
R2: Dim,
|
2018-02-02 19:26:35 +08:00
|
|
|
|
ShapeConstraint: SameNumberOfRows<R1, R2>,
|
|
|
|
|
{
|
2016-12-05 05:44:42 +08:00
|
|
|
|
}
|
|
|
|
|
|
2021-08-03 00:41:46 +08:00
|
|
|
|
impl<T, R1, R2> SameShapeVectorAllocator<T, R1, R2> for DefaultAllocator
|
2018-02-02 19:26:35 +08:00
|
|
|
|
where
|
2021-08-03 00:41:46 +08:00
|
|
|
|
R1: Dim,
|
|
|
|
|
R2: Dim,
|
2021-07-16 12:56:58 +08:00
|
|
|
|
DefaultAllocator: Allocator<T, R1, U1> + Allocator<T, SameShapeR<R1, R2>>,
|
2018-02-02 19:26:35 +08:00
|
|
|
|
ShapeConstraint: SameNumberOfRows<R1, R2>,
|
2020-04-06 00:49:48 +08:00
|
|
|
|
{
|
|
|
|
|
}
|