Struct Prop

pub struct Prop { /* private fields */ }

The level-2 storage beneath Database

Implementations

impl Prop

pub fn new( db: &Db, name: PropTag, tick: impl TickFn, merge: impl MergeFn, ) -> Self

Create a new Prop.

Note that the merge method is necessary, if not used, just invoke an empty closure like |_,_,_|None.

impl Prop

pub fn name(&self) -> PropTag

Return the name of this Prop.

pub fn get(&self, eid: &EID) -> Option<Value>

Get a value for a eid in Prop.

Example

use retable::{Database, Config, basic::{EID, Value}};

// create a temporary database to avoid old disk file polution.
let mut db = Database::new(Config::default().temporary(true)).unwrap();
// create a prop with non-bound method.
let prop = db.create_prop("test_int".into(), |_, _, _| None, |_,_,_|None);

// Example eid is 1.
let eid = EID::new(1);

// Get a non-exist value, it's a None.
assert_eq!(prop.get(&eid), None);

// Set a Int(8) for eid(1) and get it.
prop.set(&eid, Value::Int(8), false);
assert_eq!(prop.get(&eid), Some(Value::Int(8)));

pub fn set(&self, eid: &EID, value: Value, retrieve: bool) -> Option<Value>

Set a value for a eid in Prop. If retrieve is true, return old value.

Example

use retable::{Database, Config, basic::{EID, Value}};


// create a temporary database to avoid old disk file polution.
let mut db = Database::new(Config::default().temporary(true)).unwrap();
// create a prop with non-bound method.
let prop = db.create_prop("test_int".into(), |_, _, _| None, |_,_,_|None);

let eid = EID::new(1);
// Set a Int(8) for eid(1) and get it.
let old = prop.set(&eid, Value::Int(42), true);
assert_eq!(old, None);
assert_eq!(prop.get(&eid), Some(Value::Int(42)));

// Return the old value if retrieve is true.
let old = prop.set(&eid, Value::Int(43), true);
assert_eq!(old, Some(Value::Int(42)));
assert_eq!(prop.get(&eid), Some(Value::Int(43)));

// Always return a None if retrieve is false.
let old = prop.set(&eid, Value::Int(2001), false);
assert_eq!(old, None);
assert_eq!(prop.get(&eid), Some(Value::Int(2001)));

pub fn remove(&self, eid: &EID, retrieve: bool) -> Option<Value>

Remove entry from Prop. If retrieve is true, return old value.

Example

use retable::{Database, Config, basic::{EID, Value}};

// create a temporary database to avoid old disk file polution.
let mut db = Database::new(Config::default().temporary(true)).unwrap();
// create a prop with non-bound method.
let prop = db.create_prop("test_int".into(), |_, _, _| None, |_,_,_| None);

// Set a value for eid(1) and eid(2) in prop.
prop.set(&EID::new(1), Value::Int(42), false);
prop.set(&EID::new(2), Value::Int(42), false);
// Let's remove it, and fetch the old value, just like "pop".
let value = prop.remove(&EID::new(1), true);
assert_eq!(value, Some(Value::Int(42)));

// Remove the value without retrieve will always return a None.
let value = prop.remove(&EID::new(2), false);
assert_eq!(value, None);

// Now we lost eid(1) and eid(2) forever.
assert!(prop.get(&EID::new(1)).is_none());
assert!(prop.get(&EID::new(2)).is_none());

pub fn register_merge(&mut self, f: impl MergeFn)

Register a merge function for Prop. See Prop::merge for more.

pub fn merge(&self, eid: &EID, delta: Delta)

Merge a delta to a value(index by given eid) in Prop.

Example

use retable::{Database, Config, basic::{EID, Value, Delta}};

// First define a merge function,
// which merge a delta value int into the old value by addition, and return the new value.
//
// the old one is called "old", the new one is called "delta".
//
// Return None if either value is not int. Return Some(Value) if both values are int.
// Do nothing if old value is None.
// Method signature is defined by [`crate::MergeFn`]
const fn int_add_merge(_: EID, old: Option<Value>, delta: Delta) -> Option<Value> {
    if let Some(old) = old {
        match (old, delta) {
            (Value::Int(v), Delta::Int(d)) => {
                Some(Value::Int(v + d))
            }
            _ => {
                None
            }
        }
    } else {
        None
    }
}

// create a temporary database to avoid old disk file polution.
let mut db = Database::new(Config::default().temporary(true)).unwrap();
// create a prop with int_add_merge and non-tick method.
let prop = db.create_prop("test_int".into(), int_add_merge, |_,_,_| None);

// Set some value first.
prop.set(&EID::new(1), Value::Int(42), false);
prop.set(&EID::new(2), Value::Int(2023), false);

// The delta that should be merged
let delta = Delta::Int(666);
// Merge it.
// Note that the prop is immutable, the Sync and Send traits is garenteed by inner design.
// So **DO NOT** use a Mutex (or any other lock) to protect the prop.
prop.merge(&EID::new(1), delta);
prop.merge(&EID::new(2), delta);

// Check the result.
assert_eq!(prop.get(&EID::new(1)), Some(Value::Int(708)));
assert_eq!(prop.get(&EID::new(2)), Some(Value::Int(2689)));

// The None value merged function is fully defined by the Merge Function
// In our scenery, it will do nothing. You can modify the merge method to implement more complex logic.
prop.merge(&EID::new(3), delta);
assert_eq!(prop.get(&EID::new(3)), None);

pub fn register_tick(&mut self, f: impl TickFn)

See more in crate::method::TickFn

pub fn tick(&self)

Tick all entity.

Tick actions is launched in parellar, by calling tick method using (&EID, Value, &Self) The result delta of every tick is auto merged.

See more in crate::method::TickFn