orx_pinned_vec/
capacity.rs

1/// Provides detailed information of capacity state of the pinned vector.
2///
3/// This information contains the current capacity which can be obtained by `capacity()` method and extends with additional useful information.
4///
5/// * `FixedCapacity` variant only provides the current capacity.
6///   However, its additional tag informs that this capacity is a hard constraint and the vector cannot grow beyond it.
7/// * `DynamicCapacity` variant informs that the vector is capable of allocating and growing its capacity.
8///   It provides `current_capacity` representing the current internal state of the vector.
9///   Additionally, `maximum_concurrent_capacity` is provided.
10///   This number represents the maximum number of elements that can safely be pushed to the vector in a concurrent program.
11#[derive(PartialEq, Eq, Clone, Copy, Debug)]
12pub enum CapacityState {
13    /// `FixedCapacity` variant only provides the current capacity.
14    /// However, its additional tag informs that this capacity is a hard constraint and the vector cannot grow beyond it.
15    FixedCapacity(usize),
16    /// `DynamicCapacity` variant informs that the vector is capable of allocating and growing its capacity.
17    /// It provides `current_capacity` representing the current internal state of the vector.
18    /// Additionally, `maximum_concurrent_capacity` is provided.
19    /// This number represents the maximum number of elements that can safely be pushed to the vector in a concurrent program.
20    /// This value is often related with the capacity of the container holding meta information about allocations.
21    /// Note that the dynamic vector can naturally grow beyond this number, this bound is only relevant when the vector is `Sync`ed among threads.
22    DynamicCapacity {
23        /// Capacity of current allocations owned by the vector.
24        current_capacity: usize,
25        /// Maximum capacity that can safely be reached by the vector in a concurrent program.
26        /// This value is often related with the capacity of the container holding meta information about allocations.
27        /// Note that the dynamic vector can naturally grow beyond this number, this bound is only relevant when the vector is `Sync`ed among threads.
28        maximum_concurrent_capacity: usize,
29    },
30}
31
32impl CapacityState {
33    /// Capacity of current allocations owned by the vector.
34    pub fn current_capacity(&self) -> usize {
35        match self {
36            Self::FixedCapacity(x) => *x,
37            Self::DynamicCapacity {
38                current_capacity,
39                maximum_concurrent_capacity: _,
40            } => *current_capacity,
41        }
42    }
43
44    /// Maximum capacity that can safely be reached by the vector in a concurrent program.
45    /// This value is often related with the capacity of the container holding meta information about allocations.
46    /// Note that the dynamic vector can naturally grow beyond this number, this bound is only relevant when the vector is `Sync`ed among threads.
47    pub fn maximum_concurrent_capacity(&self) -> usize {
48        match self {
49            Self::FixedCapacity(x) => *x,
50            Self::DynamicCapacity {
51                current_capacity: _,
52                maximum_concurrent_capacity,
53            } => *maximum_concurrent_capacity,
54        }
55    }
56}
57
58#[cfg(test)]
59mod tests {
60    use super::*;
61
62    #[test]
63    fn current_capacity() {
64        assert_eq!(42, CapacityState::FixedCapacity(42).current_capacity());
65        assert_eq!(
66            7,
67            CapacityState::DynamicCapacity {
68                current_capacity: 7,
69                maximum_concurrent_capacity: 42
70            }
71            .current_capacity()
72        );
73    }
74
75    #[test]
76    fn maximum_concurrent_capacity() {
77        assert_eq!(
78            42,
79            CapacityState::FixedCapacity(42).maximum_concurrent_capacity()
80        );
81        assert_eq!(
82            42,
83            CapacityState::DynamicCapacity {
84                current_capacity: 7,
85                maximum_concurrent_capacity: 42
86            }
87            .maximum_concurrent_capacity()
88        );
89    }
90}
orx_pinned_vec/capacity.rs

orx_pinned_vec/
capacity.rs
