5 unstable releases
0.3.0 | Feb 4, 2024 |
---|---|
0.2.1 | Feb 4, 2024 |
0.2.0 | Feb 4, 2024 |
0.1.1 | Feb 3, 2024 |
0.1.0 | Feb 3, 2024 |
#235 in Memory management
47KB
812 lines
swap-pool
Do you need to store a large amount of data and it may not fit into your computer's RAM? Then this library is created for you!
Usage
use swap_pool::prelude::*;
// Create a new swap pool with 128 bytes of memory available
// and designate a "swap" folder for it
let mut pool = SwapPool::new(128, "swap");
// Spawn 3 entities in the pool
// Each entity must implement From and Into Vec<u8> traits
let a = pool.spawn(vec![0; 128]).unwrap();
let b = pool.spawn(vec![1; 128]).unwrap();
let c = pool.spawn(vec![2; 128]).unwrap();
// Check if spawned entities are hot (stored in the RAM)
// "b" and "c" will be saved to the "swap" folder because
// "a" will take all 128 available bytes (a bit more actually)
dbg!(a.is_hot()); // a.is_hot() = true
dbg!(b.is_hot()); // b.is_hot() = false
dbg!(c.is_hot()); // c.is_hot() = false
// Flush all the entities to the disk ("a" will become cold)
pool.handle().flush().unwrap();
// Read entities values. Note that this operation
// will always clone the value so use x2 amount of RAM
// due to some inner magic
// (I need to share ownership of the value if there's no memory available)
assert!(a.value().unwrap() == vec![0; 128]);
assert!(b.value().unwrap() == vec![1; 128]);
assert!(c.value().unwrap() == vec![2; 128]);
// Check entities status
// Since we can keep only one entity hot at a time
// the pool will free an old one and replace it by a new one
// so firstly we allocated "a", then it was replaced by "b",
// and finally it was replaced by "c"
dbg!(a.is_hot()); // a.is_hot() = false
dbg!(b.is_hot()); // b.is_hot() = false
dbg!(c.is_hot()); // c.is_hot() = true
// Update the value stored in entity "c"
// Second update will return "false" because we can't
// allocate at least 1024 bytes in the current swap pool
// (maximum 128 bytes available)
dbg!(c.update(vec![0; 64]).unwrap()); // c.update(vec![0 ; 64]).unwrap() = true
dbg!(c.update(vec![0; 1024]).unwrap()); // c.update(vec![0 ; 1024]).unwrap() = false
// Show some statistics about the memory use
// Note: "used" will report 0 because second "update"
// has flushed the entity and didn't update its value
// because it didn't have enough free space available
println!("Total: {}", pool.handle().allocated());
println!(" Used: {}", pool.handle().used());
println!(" Free: {}", pool.handle().available());
Notes:
- You can use
entity.value_allocate()
to ignore pool memory limitations and always make the entity hot. Call this method if you want to keep the entity in the RAM as long as possible. - On the contrary,
entity.value_unallocate()
will return stored value (or read it from the disk) and flush the entity, making it cold. Call this method if you don't need to access the entity often. - You can replace the entity's value using
entity.replace(value)
. It will not try to free the memory to store the new value. - You can free any amount of memory you need by calling
handle.free(memory)
. It will also say if it succeeded to free given amount of memory. - You can also call
handle.flush()
to flush all the entities. - Call
handle.collect_garbage()
to remove weak references to the dropped entities. Otherwise they will stack up in the pool's entities list.
Entities managers
Entities managers decide what entities should be flushed before the others. By default SwapPool
will use SwapLastUsedManager
which saves timestamps of last entities uses (calls of value()
or upgrade()
methods). There's also a SwapUpgradesCountManager
which counts upgrades and uses them as entities' ranks.
You can implement your own manager:
use std::collections::HashSet;
use std::cell::Cell;
use swap_pool::prelude::*;
pub struct ExampleManager {
entities: Cell<HashSet<u64>>
}
impl Default for ExampleManager {
#[inline]
fn default() -> Self {
Self {
entities: Cell::new(HashSet::new())
}
}
}
impl SwapManager for ExampleManager {
#[inline]
fn upgrade(&self, uuid: u64) -> u64 {
let mut entities = self.entities.take();
// Store the entity's unique id
entities.insert(uuid);
self.entities.set(entities);
self.rank(uuid)
}
#[inline]
fn rank(&self, uuid: u64) -> u64 {
let entities = self.entities.take();
// Get stored entity's position
// and return it as a rank
// Later an entity was used - later
// it will be unallocated
let rank = entities.iter()
.position(|entity| entity == &uuid)
.unwrap_or_default();
self.entities.set(entities);
u64::try_from(rank).unwrap()
}
}
Entities transformers
Transformers are used to mutate entities' values when reading or writing swap files. By default SwapIdentityTransformer
is used which does nothing to the original data.
Let's make a transformer which reverses input data:
use swap_pool::prelude::*;
struct ReverseDataTransformer;
impl SwapTransformer for ReverseDataTransformer {
// Called to change the value which will be saved to the swap file
fn forward(&self, data: Vec<u8>) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
Ok(data.into_iter().rev().collect())
}
// Called to change the value read from the swap file
fn backward(&self, data: Vec<u8>) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
Ok(data.into_iter().rev().collect())
}
}
Pool builder
use swap_pool::prelude::*;
let mut pool = SwapPoolBuilder::default()
.with_manager(ExampleManager::default())
.with_transformer(ReverseDataTransformer)
.with_thread_safe(false)
.build();
let entity = pool.spawn(b"Hello, World!".to_vec()).unwrap();
// Hello, World!
println!("{}", String::from_utf8_lossy(&entity.value().unwrap()));
Features
Name | Description |
---|---|
thiserror |
Implement Error trait for SwapError type from the thiserror crate. |
timestamp-uuid [1] |
Use SystemTime::now() to generate entities' UUIDs. Enabled by default. |
random-uuid [1] |
Use rand crate to generate random entities' UUIDs. |
crc32-uuid [2] |
Use crc32fast crate to generate random entities' UUIDs. |
xxhash-uuid [2] |
Use xxhash-rust crate (xxh3) to generate random entities' UUIDs. |
size-of-crate [3] |
Implement SizeOf trait for all the types supported by size-of crate. |
dyn-size-of-crate [3] |
Implement SizeOf trait for all the types supported by dyn_size_of crate. |
full |
thiserror , random-uuid , xxhash-uuid , dyn-size-of-crate |
default |
timestamp-uuid |
Notes:
- Enabling
random-uuid
will disabletimestamp-uuid
and use of values to generate UUID (result will be based on the randomly generated number only). When both disabled - UUID generation will be based on the entity's value only. - If both
crc32-uuid
andxxhash-uuid
enabled - the latest one will be prioritized. If none - defaultHashMap
's hasher is used. - You can't enable both
size-of-crate
anddyn-size-of-crate
features simultaneously because it would cause compatibility issues. Consider enabling only one of them.
Author: Nikita Podvirnyi
Licensed under MIT
Dependencies
~245KB