memur 0.3.4

Arena storage with bells and whistles.
Documentation 
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
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

use std::collections::VecDeque;

struct ArenaMemoryInstance {
    free_blocks: VecDeque<Box<[u8]>>,
    max_free_blocks_to_initialize_or_cleanup_to: i32,
    min_free_blocks_before_allocating_new: i32,
    new_block_size: usize,
}

impl ArenaMemoryInstance {
    pub fn new(options: &MemoryBuilder) -> ArenaMemoryInstance {
        let mut i = ArenaMemoryInstance {
            free_blocks: VecDeque::with_capacity(1024),
            max_free_blocks_to_initialize_or_cleanup_to: options.max_free_blocks_to_initialize_or_cleanup_to,
            min_free_blocks_before_allocating_new: options.min_free_blocks_before_allocating_new,
            new_block_size: options.new_block_size,
        };
        i.check_if_not_enough_blocks_and_initialize();
        i
    }

    fn check_if_not_enough_blocks_and_initialize(&mut self) {
        if self.free_blocks.len() < self.min_free_blocks_before_allocating_new as usize {
            while self.free_blocks.len() < self.max_free_blocks_to_initialize_or_cleanup_to as usize {
                debug!("-- init   block of size {}", self.new_block_size);
                self.free_blocks.push_front(vec![0u8; self.new_block_size as usize].into_boxed_slice());
            }
        }
    }

    /// Cleans up the memory and returns cleaned-up memory size.
    pub fn cleanup(&mut self) -> usize {
        let mut cleaned_up_size = 0;
        while self.free_blocks.len() > self.max_free_blocks_to_initialize_or_cleanup_to as usize {
            if let Some(block) = self.free_blocks.pop_front() {
                cleaned_up_size += block.len();
                debug!("-- clean  block of size {}", block.len());
            }
        }
        cleaned_up_size
    }

    pub fn take_block(&mut self) -> Box<[u8]> {
        self.check_if_not_enough_blocks_and_initialize();
        let block = self.free_blocks.pop_back().expect("no allocated memory");

        debug!("-- take   block of size {}", block.len());

        block
    }

    pub fn return_block(&mut self, block: Box<[u8]>) {

        debug!("-- return block of size {}", block.len());

        self.free_blocks.push_back(block);
    }
}

/// Memory options builder.
pub struct MemoryBuilder {
    max_free_blocks_to_initialize_or_cleanup_to: i32,
    min_free_blocks_before_allocating_new: i32,
    new_block_size: usize,
}

impl MemoryBuilder {
    /// Specify the amount of blocks to keep around.
    ///
    /// Memory immediately allocates the `max` blocks when created.
    ///
    /// If the amount of unused allocated blocks reaches `min`, new block allocation kicks in
    /// and allocates up to `max` blocks again.
    ///
    /// Memory blocks returned back to memory can increase count above `max`, because blocks are
    /// not deallocated automatically. Use `cleanup` function for that.
    pub fn with_min_max_blocks(mut self, min: i32, max: i32) -> MemoryBuilder {
        self.min_free_blocks_before_allocating_new = min;
        self.max_free_blocks_to_initialize_or_cleanup_to = max;
        self
    }

    /// Specify the size of a new block.
    ///
    /// Make sure it is considerably bigger than any structures you want to keep in it.
    pub fn with_block_size(mut self, size: usize) -> MemoryBuilder {
        self.new_block_size = size;
        self
    }

    pub fn build(self) -> Memory {
        Memory {
            shared: std::sync::Arc::new(std::sync::Mutex::new(ArenaMemoryInstance::new(&self)))
        }
    }
}

/// Container of shared memory blocks.
/// Does not automatically de-allocate memory!
/// Call `cleanup` method to de-allocate when it is the most convenient.
#[derive(Clone)]
pub struct Memory {
    shared: std::sync::Arc<std::sync::Mutex<ArenaMemoryInstance>>,
}

impl Memory {
    pub fn builder() -> MemoryBuilder {
        MemoryBuilder {
            max_free_blocks_to_initialize_or_cleanup_to: 4,
            min_free_blocks_before_allocating_new: 2,
            new_block_size: 1024*64,
        }
    }

    pub fn new() -> Memory {
        let builder = MemoryBuilder {
            max_free_blocks_to_initialize_or_cleanup_to: 4,
            min_free_blocks_before_allocating_new: 2,
            new_block_size: 1024*64,
        };

        Memory {
            shared: std::sync::Arc::new(std::sync::Mutex::new(ArenaMemoryInstance::new(&builder)))
        }
    }

    /// Cleans up the memory and returns cleaned-up memory size if the amount of free blocks is
    /// above `max`.
    #[inline(always)]
    pub fn cleanup(&self) -> usize {
        self.shared.lock().expect("lock").cleanup()
    }

    #[inline(always)]
    pub fn take_block(&mut self) -> Box<[u8]> {
        self.shared.lock().expect("lock").take_block()
    }

    #[inline(always)]
    pub fn return_block(&mut self, block: Box<[u8]>) {
        self.shared.lock().expect("lock").return_block(block)
    }
}