Struct matterdb::Fork[][src]

pub struct Fork { /* fields omitted */ }
Expand description

A combination of a database snapshot and changes on top of it.

A Fork provides both immutable and mutable operations over the database by implementing the RawAccessMut trait. Like Snapshot, Fork provides read isolation. When mutable operations are applied to a fork, the subsequent reads act as if the changes are applied to the database; in reality, these changes are accumulated in memory.

To apply the changes to the database, you need to convert a Fork into a Patch using into_patch and then atomically merge it into the database. If two conflicting forks are merged into a database, this can lead to an inconsistent state. If you need to consistently apply several sets of changes to the same data, the next fork should be created after the previous fork has been merged.

Fork also supports checkpoints (flush and rollback methods), which allows rolling back the latest changes. A checkpoint is created automatically after calling the flush method.

let db = TemporaryDB::new();
let mut fork = db.fork();
fork.get_list("list").extend(vec![1_u32, 2]);
fork.flush();
fork.get_list("list").push(3_u32);
fork.rollback();
// The changes after the latest `flush()` are now forgotten.
let list = fork.get_list::<_, u32>("list");
assert_eq!(list.len(), 2);

In order to convert a fork into &dyn Snapshot presentation, convert it into a Patch and use a reference to it (Patch implements Snapshot). Using <Fork as RawAccess>::snapshot for this purpose is logically incorrect and may lead to hard-to-debug errors.

Borrow checking

It is possible to create only one instance of index with the specified IndexAddress based on a single fork. If an additional instance is requested, the code will panic in runtime. Hence, obtaining indexes from a Fork functions similarly to RefCell::borrow_mut().

For example the code below will panic at runtime.

let db = TemporaryDB::new();
let fork = db.fork();
let index = fork.get_list::<_, u8>("index");
// This code will panic at runtime.
let index2 = fork.get_list::<_, u8>("index");

To enable immutable / shared references to indexes, you may use readonly method:

let db = TemporaryDB::new();
let fork = db.fork();
fork.get_list::<_, u8>("index").extend(vec![1, 2, 3]);

let readonly = fork.readonly();
let index = readonly.get_list::<_, u8>("index");
// Works fine.
let index2 = readonly.get_list::<_, u8>("index");

It is impossible to mutate index contents having a readonly access to the fork; this is checked by the Rust type system.

Shared references work like RefCell::borrow(); it is a runtime error to try to obtain a shared reference to an index if there is an exclusive reference to the same index, and vice versa.

Implementations

Finalizes all changes that were made after previous execution of the flush method. If no flush method had been called before, finalizes all changes that were made after creation of Fork.

Rolls back all changes that were made after the latest execution of the flush method.

Converts the fork into Patch consuming the fork instance.

Returns a readonly wrapper around the fork. Indexes created based on the readonly version cannot be modified; on the other hand, it is possible to have multiple copies of an index at the same time.

Trait Implementations

Readonly version of the access.

Performs the conversion.

Formats the value using the given formatter. Read more

Performs the conversion.

Performs the conversion.

Creates a fork based on the provided patch and snapshot.

Note: using created fork to modify data already present in patch may lead to an inconsistent database state. Hence, this method is useful only if you are sure that the fork and patch interacted with different indexes.

Performs the conversion.

Type of the changes() that will be applied to the database.

Reference to a Snapshot. This is the base relative to which the changes are defined.

Returns changes related to specific address compared to the snapshot().

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Performs the conversion.

The alignment of pointer.

The type for initializers.

Initializes a with the given initializer. Read more

Dereferences the given pointer. Read more

Mutably dereferences the given pointer. Read more

Drops the object pointed to by the given pointer. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.