Struct persy::Persy

pub struct Persy { /* fields omitted */ }

Main structure to operate persy storage files

Methods

impl Persy

pub fn create<P: AsRef<Path>>(path: P) -> PRes<()>

Create a new database file.

Errors

Fails if the file already exists.

pub fn create_from_file(file: File) -> PRes<()>

Create a new database file.

Errors

Fails if the file already exists.

pub fn open<P: AsRef<Path>>(path: P, config: Config) -> PRes<Persy>

Open a database file.

The file should have been created with Persy::create

Errors

Fails if the file does not exist.

pub fn open_with_recover<P: AsRef<Path>, C>(
    path: P,
    config: Config,
    recover: C
) -> PRes<Persy> where
    C: Fn(&TransactionId) -> bool, 

Open a database file from a path with a recover function.

The file should have been created with Persy::create

Errors

Fails if the file does not exist.

pub fn open_from_file(path: File, config: Config) -> PRes<Persy>

Open a database file from a direct file handle.

The file should have been created with Persy::create

Errors

Fails if the file does not exist.

pub fn open_from_file_with_recover<C>(
    path: File,
    config: Config,
    recover: C
) -> PRes<Persy> where
    C: Fn(&TransactionId) -> bool, 

Open a database file, from a direct file handle and a transaction recover function.

The file should have been created with Persy::create

Errors

Fails if the file does not exist.

pub fn open_or_create_with<P, F>(
    path: P,
    config: Config,
    prepare: F
) -> PRes<Persy> where
    P: AsRef<Path>,
    F: FnOnce(&Persy) -> PRes<()>, 

Open an existing database or create it if it does not exist yet, calling the prepare function just after the creation.

Example

use std::path::Path;
use persy::{Persy, Config, PersyId, ValueMode};

let path = Path::new("target/open_or_create.db");
let config = Config::new();

let persy = Persy::open_or_create_with(path, config, |persy| {
    // this closure is only called on database creation
    let mut tx = persy.begin()?;
    tx.create_segment("data")?;
    tx.create_index::<u64, PersyId>("index", ValueMode::REPLACE)?;
    let prepared = tx.prepare_commit()?;
    prepared.commit()?;
    println!("Segment and Index successfully created");
    Ok(())
})?;

pub fn begin(&self) -> PRes<Transaction>

Begin a new transaction.

The transaction isolation level is 'read_commited'. for commit call prepare_commit and commit

Example

let mut tx = persy.begin()?;
// ...
tx.prepare_commit()?.commit()?;

pub fn begin_id(&self, meta_id: TransactionId) -> PRes<Transaction>

Begin a new transaction specifying and id usable for crash recover.

The transaction isolation level is 'read_commited'. for commit call prepare_commit and commit

Example

let tx_id = vec![2;2];
let mut tx = persy.begin_id(tx_id)?;
// ...
tx.prepare_commit()?.commit()?;

pub fn create_segment(
    &self,
    tx: &mut Transaction,
    segment: &str
) -> PRes<SegmentId>

Deprecated since 0.8.0:

please use Transaction.create_segment instead

Create a new segment with the provided name

Example

let mut tx = persy.begin()?;
persy.create_segment(&mut tx, "my_new_segment")?;
let prepared = persy.prepare_commit(tx)?;
persy.commit(prepared)?;

pub fn drop_segment(&self, tx: &mut Transaction, segment: &str) -> PRes<()>

Deprecated since 0.8.0:

please use Transaction.drop_segment instead

Drop a existing segment

Example

let mut tx = persy.begin()?;
persy.drop_segment(&mut tx, "existing_segment_name")?;
let prepared = persy.prepare_commit(tx)?;
persy.commit(prepared)?;

pub fn exists_segment(&self, segment: &str) -> PRes<bool>

Check if a segment already exist in the storage

Example

let mut tx = persy.begin()?;
tx.create_segment("my_new_segment")?;
let prepared = tx.prepare_commit()?;
prepared.commit()?;
assert!(persy.exists_segment("my_new_segment")?);

pub fn exists_segment_tx(&self, tx: &Transaction, segment: &str) -> PRes<bool>

Deprecated since 0.8.0:

please use Transaction.exists_segment instead

Check if a segment already exist in the storage considering the transaction

Example

let mut tx = persy.begin()?;
persy.create_segment(&mut tx, "my_new_segment")?;
assert!(persy.exists_segment_tx(&tx, "my_new_segment")?);

pub fn solve_segment_id(&self, segment: impl ToSegmentId) -> PRes<SegmentId>

Resolves the segment to a SegmentId

Example

let mut tx = persy.begin()?;
tx.create_segment("my_new_segment")?;
let prepared = tx.prepare_commit()?;
prepared.commit()?;
let segment_id = persy.solve_segment_id("my_new_segment")?;

pub fn solve_index_id(&self, index: impl ToIndexId) -> PRes<IndexId>

Resolves the index to a IndexId

Example

let mut tx = persy.begin()?;
tx.create_index::<u8,u8>("my_new_index", ValueMode::CLUSTER)?;
let prepared = tx.prepare_commit()?;
prepared.commit()?;
let segment_id = persy.solve_index_id("my_new_index")?;

pub fn insert_record(
    &self,
    tx: &mut Transaction,
    segment: impl ToSegmentId,
    rec: &[u8]
) -> PRes<PersyId>

Deprecated since 0.8.0:

please use Transaction.insert_record instead

create a new record

This function return an id that can be used by read_record and read_record_tx, the record content can be read only with the read_record_tx till the transaction is committed.

Example

let mut tx = persy.begin()?;
let data = vec![1;20];
persy.insert_record(&mut tx, "seg", &data)?;
let prepared = persy.prepare_commit(tx)?;
persy.commit(prepared)?;

pub fn read_record_tx(
    &self,
    tx: &mut Transaction,
    segment: impl ToSegmentId,
    id: &PersyId
) -> PRes<Option<Vec<u8>>>

Deprecated since 0.8.0:

please use Transaction.read_record instead

Read the record content considering eventual in transaction changes.

Example

let mut tx = persy.begin()?;
let data = vec![1;20];
let id = persy.insert_record(&mut tx, "seg", &data)?;
let read = persy.read_record_tx(&mut tx, "seg", &id)?.expect("record exists");
assert_eq!(data,read);

pub fn read_record(
    &self,
    segment: impl ToSegmentId,
    id: &PersyId
) -> PRes<Option<Vec<u8>>>

Read the record content from persistent data.

Example

let mut tx = persy.begin()?;
let data = vec![1;20];
let id = tx.insert_record("seg", &data)?;
let prepared = tx.prepare_commit()?;
prepared.commit()?;
let read = persy.read_record("seg", &id)?.expect("record exits");
assert_eq!(data,read);

pub fn scan_records_tx<'a>(
    &self,
    tx: &'a mut Transaction,
    segment: impl ToSegmentId
) -> PRes<RecordScannerTx<'a>>

Deprecated since 0.5.0:

please use Transaction.scan instead

Scan for persistent and in transaction records

Example

let mut tx = persy.begin()?;
let data = vec![1;20];
let id = persy.insert_record(&mut tx, "seg", &data)?;
let mut count = 0;
for found in persy.scan_records_tx(&mut tx, "seg")? {
    println!("record size:{}",found.content.len());
    count+=1;
}
assert_eq!(count,1);

pub fn scan_tx<'a>(
    &self,
    tx: &'a mut Transaction,
    segment: impl ToSegmentId
) -> PRes<TxSegmentIter<'a>>

Deprecated since 0.8.0:

please use Transaction.scan instead

Scan for persistent and in transaction records

Example

let mut tx = persy.begin()?;
let data = vec![1;20];
let id = persy.insert_record(&mut tx, "seg", &data)?;
let mut count = 0;
for (id,content) in persy.scan_tx(&mut tx, "seg")? {
    println!("record size:{}",content.len());
    count+=1;
}
assert_eq!(count,1);

pub fn scan_records(&self, segment: impl ToSegmentId) -> PRes<RecordScanner>

Deprecated since 0.5.0:

please use scan instead

Scan a segment for persistent records

Example

let mut tx = persy.begin()?;
let data = vec![1;20];
let id = persy.insert_record(&mut tx, "seg", &data)?;
let prepared = persy.prepare_commit(tx)?;
persy.commit(prepared)?;
let mut count = 0;
for found in persy.scan_records("seg")? {
    println!("record size:{}",found.content.len());
    count+=1;
}
assert_eq!(count,1);

pub fn scan(&self, segment: impl ToSegmentId) -> PRes<SegmentIter>

Scan a segment for persistent records

Example

let mut tx = persy.begin()?;
let data = vec![1;20];
let id = tx.insert_record("seg", &data)?;
let prepared = tx.prepare_commit()?;
prepared.commit()?;
let mut count = 0;
for (id,content) in persy.scan("seg")? {
    println!("record size:{}",content.len());
    count+=1;
}
assert_eq!(count,1);

pub fn update_record(
    &self,
    tx: &mut Transaction,
    segment: impl ToSegmentId,
    id: &PersyId,
    rec: &[u8]
) -> PRes<()>

Deprecated since 0.8.0:

please use Transaction.update_record instead

update the record content.

This updated content can be read only with the read_record_tx till the transaction is committed.

Example

let mut tx = persy.begin()?;
let data = vec![1;20];
let id = persy.insert_record(&mut tx, "seg", &data)?;
let new_data = vec![2;20];
persy.update_record(&mut tx, "seg", &id, &new_data)?;
let prepared = persy.prepare_commit(tx)?;
persy.commit(prepared)?;

pub fn delete_record(
    &self,
    tx: &mut Transaction,
    segment: impl ToSegmentId,
    id: &PersyId
) -> PRes<()>

Deprecated since 0.8.0:

please use Transaction.delete_record instead

delete a record.

The record will result deleted only reading it whit read_record_tx till the transaction is committed.

Example

let mut tx = persy.begin()?;
let data = vec![1;20];
let id = persy.insert_record(&mut tx, "seg", &data)?;
persy.delete_record(&mut tx, "seg", &id)?;
let prepared = persy.prepare_commit(tx)?;
persy.commit(prepared)?;

pub fn create_index<K, V>(
    &self,
    tx: &mut Transaction,
    index_name: &str,
    value_mode: ValueMode
) -> PRes<()> where
    K: IndexType,
    V: IndexType, 

Deprecated since 0.8.0:

please use Transaction.create_index instead

Create a new index with the name and the value management mode.

The create operation require two template arguments that are the types as keys and values of the index this have to match the following operation on the indexes.

Example

let mut tx = persy.begin()?;
persy.create_index::<u8,u8>(&mut tx, "my_new_index", ValueMode::CLUSTER)?;
let prepared = persy.prepare_commit(tx)?;
persy.commit(prepared)?;

pub fn drop_index(&self, tx: &mut Transaction, index_name: &str) -> PRes<()>

Deprecated since 0.8.0:

please use Transaction.drop_index instead

Drop an existing index.

Example

let mut tx = persy.begin()?;
persy.drop_index(&mut tx, "my_new_index")?;
let prepared = persy.prepare_commit(tx)?;
persy.commit(prepared)?;

pub fn exists_index(&self, segment: &str) -> PRes<bool>

Check if a segment already exist in the storage

Example

let mut tx = persy.begin()?;
tx.create_index::<u8,u8>("my_new_index", ValueMode::REPLACE)?;
let prepared = tx.prepare_commit()?;
prepared.commit()?;
assert!(persy.exists_index("my_new_index")?);

pub fn exists_index_tx(&self, tx: &Transaction, segment: &str) -> PRes<bool>

Deprecated since 0.8.0:

please use Transaction.exists_index instead

Check if a segment already exist in the storage considering the transaction

Example

let mut tx = persy.begin()?;
persy.create_index::<u8,u8>(&mut tx, "my_new_index", ValueMode::REPLACE)?;
assert!(persy.exists_index_tx(&mut tx, "my_new_index")?);

pub fn put<K, V>(
    &self,
    tx: &mut Transaction,
    index_name: &str,
    k: K,
    v: V
) -> PRes<()> where
    K: IndexType,
    V: IndexType, 

Deprecated since 0.8.0:

please use Transaction.put instead

Put a key value in an index following the value mode strategy.

Example

let mut tx = persy.begin()?;
persy.create_index::<u8,u8>(&mut tx, "my_new_index", ValueMode::CLUSTER)?;
persy.put::<u8,u8>(&mut tx, "my_new_index",10,10)?;
let prepared = persy.prepare_commit(tx)?;
persy.commit(prepared)?;

pub fn remove<K, V>(
    &self,
    tx: &mut Transaction,
    index_name: &str,
    k: K,
    v: Option<V>
) -> PRes<()> where
    K: IndexType,
    V: IndexType, 

Deprecated since 0.8.0:

please use Transaction.remove instead

Remove a key and optionally a specific value from an index following the value mode strategy.

Example

let mut tx = persy.begin()?;
persy.create_index::<u8,u8>(&mut tx, "my_new_index", ValueMode::CLUSTER)?;
persy.put::<u8,u8>(&mut tx, "my_new_index",10,10)?;
persy.remove::<u8,u8>(&mut tx, "my_new_index",10,Some(10))?;
let prepared = persy.prepare_commit(tx)?;
persy.commit(prepared)?;

pub fn get<K, V>(&self, index_name: &str, k: &K) -> PRes<Option<Value<V>>> where
    K: IndexType,
    V: IndexType, 

Get a value or a group of values from a key.

Example

let val = persy.get::<u8,u8>("my_new_index",&10)?;
if let Some(is_there) = val {
    // A value is actually there
    match is_there {
        Value::SINGLE(actual_value) => {
        },
        Value::CLUSTER(actual_value) => {
        },
    }
}

pub fn get_tx<K, V>(
    &self,
    tx: &mut Transaction,
    index_name: &str,
    k: &K
) -> PRes<Option<Value<V>>> where
    K: IndexType,
    V: IndexType, 

Deprecated since 0.8.0:

please use Transaction.get instead

Get a value or a group of values from a key considering changes in transaction.

Example

persy.put::<u8,u8>(&mut tx, "my_new_index",10,10)?;
let val = persy.get_tx::<u8,u8>(&mut tx,"my_new_index",&10)?;
if let Some(is_there) = val {
    // A value is actually there
    match is_there {
        Value::SINGLE(actual_value) => {
        },
        Value::CLUSTER(actual_value) => {
        },
    }
}

pub fn range<K, V, R>(
    &self,
    index_name: &str,
    range: R
) -> PRes<IndexIter<K, V>> where
    K: IndexType,
    V: IndexType,
    R: RangeBounds<K>, 

Browse a range of keys and values from and index.

Example

let iter:IndexIter<u8,u8> = persy.range("my_new_index",10..12)?;
for (k,val) in iter  {
    // A value is actually there
    match val {
        Value::SINGLE(actual_value) => {
        },
        Value::CLUSTER(actual_value) => {
        },
    }
}

pub fn range_tx<'a, K, V, R>(
    &self,
    tx: &'a mut Transaction,
    index_name: &str,
    range: R
) -> PRes<TxIndexIter<'a, K, V>> where
    K: IndexType,
    V: IndexType,
    R: RangeBounds<K>, 

Deprecated since 0.8.0:

please use Transaction.range instead

Browse a range of keys and values from and index including the transaction changes

Example

let persy = Persy::open("./data.persy",Config::new())?;
let mut tx = persy.begin()?;
persy.put::<u8,u8>(&mut tx, "my_new_index",10,10)?;
{
    let iter:TxIndexIter<u8,u8> = persy.range_tx(&mut tx,"my_new_index",10..12)?;
    for (k,val) in iter  {
        // A value is actually there
        match val {
            Value::SINGLE(actual_value) => {
            },
            Value::CLUSTER(actual_value) => {
            },
        }
    }
}
let prepared = persy.prepare_commit(tx)?;
persy.commit(prepared)?;

pub fn rollback(&self, tx: Transaction) -> PRes<()>

Deprecated since 0.8.0:

please use Transaction.rollback instead

Rollback a not yet prepared transaction.

All the resources used for eventual insert or update are released.

Example

let mut tx = persy.begin()?;
let data = vec![1;20];
persy.insert_record(&mut tx, "seg", &data)?;
persy.rollback(tx)?;

pub fn prepare_commit(&self, tx: Transaction) -> PRes<TransactionFinalize>

Deprecated since 0.8.0:

please use Transaction.prepare_commit instead

Prepare to commit a transaction, it will lock all the records involved in the transaction till a commit or rollback_prepared is called.

Example

let mut tx = persy.begin()?;
//Do what ever operations on the records
let data = vec![1;20];
persy.insert_record(&mut tx, "seg", &data)?;
let _= persy.prepare_commit(tx)?;

pub fn rollback_prepared(&self, finalizer: TransactionFinalize) -> PRes<()>

Deprecated since 0.8.0:

please use TransactionFinalize.rollback instead

Rollback a prepared commit.

All the modification are rolled back and all the used resources are put released

Example

let mut tx = persy.begin()?;
//Do what ever operations on the records
let data = vec![1;20];
persy.insert_record(&mut tx, "seg", &data)?;
let prepared = persy.prepare_commit(tx)?;
persy.rollback_prepared(prepared)?;

pub fn commit(&self, finalizer: TransactionFinalize) -> PRes<()>

Deprecated since 0.8.0:

please use TransactionFinalize.commit instead

Finalize the commit result of a prepared commit.

All the operation done on the transaction are finalized all the lock released, all the old resources are released for reuse.

Example

let mut tx = persy.begin()?;
let prepared = persy.prepare_commit(tx)?;
persy.commit(prepared);

pub fn list_segments(&self) -> PRes<Vec<(String, SegmentId)>>

List all the existing segments.

Example

let mut tx = persy.begin()?;
tx.create_segment("seg")?;
let prepared = tx.prepare_commit()?;
prepared.commit()?;
let segments = persy.list_segments()?;
let names = segments.into_iter().map(|(name,_id)|name).collect::<Vec<String>>();
assert!(names.contains(&"seg".to_string()));

pub fn list_indexes(&self) -> PRes<Vec<(String, IndexInfo)>>

List all the existing segments.

Example

let mut tx = persy.begin()?;
tx.create_index::<u8,u8>("index", ValueMode::CLUSTER)?;
let prepared = tx.prepare_commit()?;
prepared.commit()?;
let indexes = persy.list_indexes()?;
let names = indexes.into_iter().map(|(name,_info)|name).collect::<Vec<String>>();
assert!(names.contains(&"seg".to_string()));

pub fn list_segments_tx(
    &self,
    tx: &Transaction
) -> PRes<Vec<(String, SegmentId)>>

Deprecated since 0.8.0:

please use Transaction.list_segments instead

List all the existing segments, considering all the changes in transaction.

Example

let mut tx = persy.begin()?;
persy.create_segment(&mut tx, "seg")?;
let segments = persy.list_segments_tx(&mut tx)?;
let names = segments.into_iter().map(|(name,_id)|name).collect::<Vec<String>>();
assert!(names.contains(&"seg".to_string()));
let prepared = persy.prepare_commit(tx)?;
persy.commit(prepared)?;

pub fn list_indexes_tx(
    &self,
    tx: &Transaction
) -> PRes<Vec<(String, IndexInfo)>>

Deprecated since 0.8.0:

please use Transaction.list_indexes instead

List all the existing indexes, considering changes in the transaction.

Example

let mut tx = persy.begin()?;
persy.create_index::<u8, u8>(&mut tx, "idx", ValueMode::REPLACE)?;
let indexes = persy.list_indexes_tx(&mut tx)?;
let names = indexes.into_iter().map(|(name,_id)|name).collect::<Vec<String>>();
assert!(names.contains(&"idx".to_string()));
let prepared = persy.prepare_commit(tx)?;
persy.commit(prepared)?;

Trait Implementations

impl Clone for Persy

fn clone(&self) -> Persy

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.