1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

//! Types used across this module and, possibly, externally (see if exports are done in mod.rs)


use std::fmt::Debug;

/// Dictates how data slots should be acquired and returned for future reuse.\
/// Two APIs are available:
///   - by ref: offers mutable references upon allocation and requiring them for deallocation
///   - by id:  offers u32 ids, which should be translated to mutable references before usage... from there, freeing might either be done from the id or the mut ref
pub trait OgreAllocator<SlotType: Debug>: Debug {

    /// Instantiates a new allocator
    fn new() -> Self;

    /// Returns a (mutable reference, slot_id) to the newly allocated slot or `None` if the allocator is, currently, out of space
    /// -- in which case, a [dealloc_ref()] would remedy the situation.\
    /// IMPLEMENTORS: #[inline(always)]
    fn alloc_ref(&self) -> Option<(/*ref:*/ &mut SlotType, /*slot_id:*/ u32)>;

    /// Allocates & sets the data with the provided callback `f`, which should return a `DataType`.\
    /// Returns a (mutable reference, slot_id) to the newly allocated slot or `None` if the allocator is, currently, out of space
    /// -- in which case, a [dealloc_ref()] would remedy the situation.\
    /// IMPLEMENTORS: #[inline(always)]
    fn alloc_with<F: FnOnce(&mut SlotType)>
                 (&self, setter: F)
                 -> Option<(/*ref:*/ &mut SlotType, /*slot_id:*/ u32)>;

    /// Returns the slot for reuse by a subsequent call of [alloc_ref()]\
    /// IMPLEMENTORS: #[inline(always)]
    fn dealloc_ref(&self, slot: &SlotType);

    /// IMPLEMENTORS: #[inline(always)]
    fn dealloc_id(&self, slot_id: u32);

    /// returns the position (within the allocator's pool) that the given `slot` reference occupies\
    /// IMPLEMENTORS: #[inline(always)]
    fn id_from_ref(&self, slot: &SlotType) -> u32;

    /// returns a reference to the slot position pointed to by `slot_id`
    /// IMPLEMENTORS: #[inline(always)]
    fn ref_from_id(&self, slot_id: u32) -> &mut SlotType;
}