Struct Store

pub struct Store {
    pub max_byte_size: Option<u64>,
    pub byte_size: u64,
    pub group_defaults: BTreeMap<u16, GroupDefaults>,
    pub uuid_manager: UuidManager,
    pub id_to_group_map: BTreeMap<Arc<Uuid>, u16>,
    pub groups_map: BTreeMap<u16, Group>,
}

The base unit which stores information about inserted messages and priority groups to determine which messages should be forwarded or burned first.

The store can contain 65,535 priorities. Messages are forwarded on a highest priority then oldest status basis. Messages are burned/pruned on a lowest priority then oldest status basis. Messages are only burned once the store has reached the max bytesize limit. The store as a whole contains a max bytesize limit option as does each individule priority group. For example, a developer can limit the size of the store to 1,000 bytes, while restricting priority group 1 to only 500 bytes, and leave higher priorities free with no restriction (except that of the store.)

The store keeps track of basic statistics such as counting the messages that have been inserted, deleted, or burned. Messages that have been deleted have been so on instructions of the developer using the del method. Messages that have been burned have been so automatically on insert or store/group defaults update once the max bytesize limit has been reached.

Fields

max_byte_size: Option<u64>

byte_size: u64

group_defaults: BTreeMap<u16, GroupDefaults>

uuid_manager: UuidManager

id_to_group_map: BTreeMap<Arc<Uuid>, u16>

groups_map: BTreeMap<u16, Group>

Implementations

impl Store

pub fn new(node_id: Option<u16>) -> Result<Store, StoreError>

pub fn add( &mut self, priority: u16, msg_byte_size: u64, ) -> Result<AddResult, StoreError>

Adds a msg to the store when no uuid is provided see also: add_with_uuid

Example

use msg_store::{Store, DEFAULT_NODE_ID};
 
let mut store = Store::new(DEFAULT_NODE_ID).unwrap();
let uuid = store.add(1, "my message".len() as u64).unwrap().uuid;
 

pub fn add_with_uuid( &mut self, uuid: Arc<Uuid>, msg_byte_size: u64, ) -> Result<AddResult, StoreError>

Adds a msg to the store

The message itself is written to disk as well as metadata about the message such as its bytesize and priority. The priority and bytesize will also be held in memory for quick access. A unique uuid will be returned on success.

The store’s inserted message count will also be incremented by one.

Errors

The method will return an error when:

• the message byte size exceeds the store’s max byte size limit.
• the message byte size exceeds the priority group’s max byte size limit.
• the message byte size does not exceed either the store’s or group’s max limit, but where the the store does not have enough space for it after accounting for higher priority messages i.e., higher priority messages will not be removed to make space for lower priority ones.
• the database implimentation encounters an error. Please read the database plugin’s documentation for details.

The error wiil be returned as a string.

Example

use msg_store::{Store, DEFAULT_NODE_ID};
 
let mut store = Store::new(DEFAULT_NODE_ID).unwrap();
let uuid = store.uuid(1).unwrap();
let add_result = store.add_with_uuid(uuid, "my message".len() as u64).unwrap();
 

pub fn del(&mut self, uuid: Arc<Uuid>) -> Result<(), StoreError>

Deletes a message from the store

A message will be removed from the store and disk once given the the message’s uuid number.

The message store’s msgs_deleted member will also be incremented by one.

Errors

An error will be returned if the database encounters an error, read the database plugin documention for specifics.

Example

use msg_store::{Store, DEFAULT_NODE_ID};
 
let mut store = Store::new(DEFAULT_NODE_ID).unwrap();
let uuid = store.add(1, "my message".len() as u64).unwrap().uuid;
store.del(uuid).unwrap();
 

pub fn del_group(&mut self, priority: &u16) -> Result<(), StoreError>

Deletes a group and its messages from the store

A group’s metadata and messages will be removed from the store and disk once given the the group’s priority number.

The message store’s msgs_deleted member will also be incremented by one.

Errors

An error will be returned if the database encounters an error, read the database plugin documention for specifics.

Example

use msg_store::{Store, DEFAULT_NODE_ID};
 
let mut store = Store::new(DEFAULT_NODE_ID).unwrap();
store.add(1, "my message".len() as u64).unwrap();
store.del_group(&1).unwrap();
 
assert!(store.get(None, None, false).unwrap().is_none());
 

pub fn get( &self, uuid: Option<Arc<Uuid>>, priority: Option<u16>, reverse: bool, ) -> Result<Option<Arc<Uuid>>, StoreError>

Gets a message from the store, either the next in line, the next in a specified priority group, or a specific message specified by the uuid option.

If the uuid option is present, it will search for that uuid only. If the priority option is present, it will retrieve the next message in line for that priority only. If neither options are present, the store will retrieve the next message in line store wide. If no message is found, None is returned.

Errors

This method will return an error if the database encounters an error or if the store realizes that the state is out of sync.

Example

use msg_store::{Store, DEFAULT_NODE_ID};
 
let mut store = Store::new(DEFAULT_NODE_ID).unwrap();
let uuid = store.add(1, "my message".len() as u64).unwrap().uuid;
let my_message = store.get(Some(uuid), None, false).unwrap();
assert!(my_message.is_some());
 
let my_message = store.get(None, Some(1), false).unwrap();
assert!(my_message.is_some());
 
let my_message = store.get(None, None, false).unwrap();
assert!(my_message.is_some());
 

pub fn get_n( &self, n: usize, starting_priority: Option<u16>, after_uuid: Option<Arc<Uuid>>, reverse: bool, ) -> Vec<Arc<Uuid>>

pub fn get_metadata( &mut self, range: (u32, u32), priority: Option<u16>, ) -> Vec<PacketMetaData>

Get x number of message metadata within a given range and/or priority. This can be useful in a larger application context where more than one message retrieval may be required, like in a multithreaded app.

The range argument is a tulple consisting of two members. The first member is the starting index, and the second is the last index. As always, indexes start with zero. If the priority argument is passed a integer the function will only return a vec containing metadata from that priority.

Example

use msg_store::{Store, DEFAULT_NODE_ID};
let mut store = Store::new(DEFAULT_NODE_ID).unwrap();
let uuid1 = store.add(1, "my message".len() as u64).unwrap().uuid;
let uuid2 = store.add(1, "my second message".len() as u64).unwrap().uuid;
let uuid3 = store.add(1, "my thrid message".len() as u64).unwrap().uuid;
 
let range = (0,2);
let priority = Some(1);
let set = store.get_metadata(range, priority);
assert_eq!(uuid1, set[0].uuid);
assert_eq!(uuid2, set[1].uuid);
assert_eq!(uuid3, set[2].uuid);

pub fn update_group_defaults( &mut self, priority: u16, defaults: &GroupDefaults, ) -> Result<(u64, Vec<Arc<Uuid>>), StoreError>

Updates the defaults for a priority group

The method takes a GroupDefaults struct which contains a member: max_byte_size. The max_byte_size member type is Option. This method will auto prune the group if the group’s current bytesize is greater than the new max bytesize default.

Errors

The method will return an error if the database encounters an error

Example

use msg_store::{Store,GroupDefaults, DEFAULT_NODE_ID};
 
let mut store = Store::new(DEFAULT_NODE_ID).unwrap();
store.add(1, "foo".len() as u64).unwrap();
store.add(1, "bar".len() as u64).unwrap();
assert_eq!(6, store.byte_size); // The store should contain 6 bytes of data, 3 for each message.
 
store.update_group_defaults(1, &GroupDefaults{ max_byte_size: Some(3) });
 
// The store should have removed 3 bytes in order to abide by the new requirement
assert_eq!(3, store.byte_size); 
 

pub fn delete_group_defaults(&mut self, priority: u16)

Removes the defaults for a priority group

Example

use msg_store::{Store,GroupDefaults, DEFAULT_NODE_ID};
 
let mut store = Store::new(DEFAULT_NODE_ID).unwrap();
store.update_group_defaults(1, &GroupDefaults{ max_byte_size: Some(6) }).unwrap();
store.add(1, "foo".len() as u64).unwrap();
store.add(1, "bar".len() as u64).unwrap();
 
let group_1 = store.groups_map.get(&1).expect("Could not find group");
assert_eq!(Some(6), group_1.max_byte_size);
 
// Now for the removal of the defaults
store.delete_group_defaults(1);
 
let group_1 = store.groups_map.get(&1).expect("Could not find group");
 
assert_eq!(None, group_1.max_byte_size);
assert!(store.group_defaults.get(&1).is_none()); 
 

pub fn update_store_defaults( &mut self, defaults: &StoreDefaults, ) -> Result<(u64, Vec<u16>, Vec<Arc<Uuid>>), StoreError>

Updates the defaults for the store

The method takes a StoreDefaults struct which contains a member: max_byte_size. The max_byte_size member type is Option. This method will auto prune the store if the store’s current bytesize is greater than the new max bytesize default.

Errors

The method will return an error if the database encounters an error

Example

use msg_store::{Store, StoreDefaults, DEFAULT_NODE_ID};
 
let mut store = Store::new(DEFAULT_NODE_ID).unwrap( );
store.add(1, "foo".len() as u64).unwrap();
store.add(1, "bar".len() as u64).unwrap();
assert_eq!(6, store.byte_size); // The store should contain 6 bytes of data, 3 for each message.
 
store.update_store_defaults(&StoreDefaults{ max_byte_size: Some(3) }).unwrap();
 
// The store should have removed 3 bytes in order to abide by the new requirement
assert_eq!(3, store.byte_size); 
 

pub fn uuid(&mut self, priority: u16) -> Result<Arc<Uuid>, StoreError>

Trait Implementations

impl Debug for Store

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.