Struct Infinitree

pub struct Infinitree<I, CustomData = ()>
where
    CustomData: Serialize + DeserializeOwned + Send + Sync + 'static,
{ /* private fields */ }

An Infinitree root.

This is primarily a wrapper around an Index that manages versioning and key management.

Implementations

impl<I: Index + Default, CustomData> Infinitree<I, CustomData>

where CustomData: Serialize + DeserializeOwned + Send + Sync,

pub fn empty( backend: Arc<dyn Backend>, key: impl Into<Key>, ) -> Result<Infinitree<I, CustomData>>

Initialize an empty index and tree with no version history.

Examples

use infinitree::{*, crypto::UsernamePassword, fields::Serialized, backends::Directory};

#[derive(Index, Default)]
struct Measurements {
    list: Serialized<Vec<usize>>
}

let mut tree = Infinitree::<Measurements>::empty(
    Directory::new("/storage").unwrap(),
    UsernamePassword::with_credentials("username".to_string(),
                                       "password".to_string()).unwrap()
).unwrap();

pub fn open( backend: Arc<dyn Backend>, key: impl Into<Key>, ) -> Result<Infinitree<I, CustomData>>

Load all version information from the tree.

This method doesn’t load the index, only the associated metadata.

impl<I: Index, CustomData> Infinitree<I, CustomData>

where CustomData: Serialize + DeserializeOwned + Send + Sync + Default,

pub fn commit( &self, message: impl Into<Message>, ) -> Result<Option<Arc<Commit<CustomData>>>>

Create a commit if there are changes in the index.

This persists currently in-memory data, and also records the commit with message to the log.

Examples

Any commit message works that implements ToString.

use infinitree::{*, crypto::UsernamePassword, fields::Serialized, backends::Directory};

let mut tree = Infinitree::<infinitree::fields::VersionedMap<String, String>>::empty(
    Directory::new("/storage").unwrap(),
    UsernamePassword::with_credentials("username".to_string(), "password".to_string()).unwrap()
).unwrap();

// Commit message can be omitted using `None`
tree.commit(None);

// Otherwise a hardcoded &str also works
tree.commit("this is a message");

// Or even a String instance
let message = "this is a string".to_string();
tree.commit(message);

impl<I: Index, CustomData> Infinitree<I, CustomData>

where CustomData: Serialize + DeserializeOwned + Send + Sync,

pub fn with_key( backend: Arc<dyn Backend>, index: I, key: impl Into<Key>, ) -> Result<Infinitree<I, CustomData>>

Wraps the given index in an Infinitree.

This is primarily useful if you’re done writing an Index, and want to commit and persist it, or if you need extra initialization because Default is not viable.

pub fn reseal(&self) -> Result<()>

Change the current wrapping key and immediately commit to the backend.

Will return an error if the operation is not supported by either the new or the old key.

pub fn commit_list(&self) -> impl Deref<Target = CommitList<CustomData>> + '_

Return all generations in the tree.

pub fn filter_commits(&self, version: CommitFilter)

Only run persistence query operations (query, load, iter) on the selected generations.

pub fn commit_with_custom_data( &self, message: impl Into<Message>, mode: CommitMode, custom_data: CustomData, ) -> Result<Option<Arc<Commit<CustomData>>>>

Commit changes currently in the index.

For full documentation, please read Infinitree::commit.

pub fn commit_with_metadata( &self, metadata: CommitMetadata<CustomData>, mode: CommitMode, ) -> Result<Option<Arc<Commit<CustomData>>>>

Commit using manually prepared metadata

For full documentation, please read Infinitree::commit.

pub fn storage_writer(&self) -> Result<AEADWriter>

Return a handle for an object writer.

This can be used to manually write sparse data if you don’t want to store it in memory. Especially useful for e.g. files.

Note that currently there’s no fragmenting internally, so anything written using an ObjectWriter must be less than about 4MB.

pub fn storage_reader(&self) -> Result<PoolRef<AEADReader>>

Return a handle for an object reader

The object reader is for reading out those ChunkPointers that you get when using an AEADWriter stack manually.

You can obtain an AEADWriter using object_writer.

pub fn hasher(&self) -> Result<Hasher>

Get a hasher that produces hashes only usable with this stash’s keys

This internally is a keyed Blake3 instance.

impl<I: Index, CustomData> Infinitree<I, CustomData>

where CustomData: Serialize + DeserializeOwned + Send + Sync,

pub fn load_all(&self) -> Result<()>

Load into memory all fields for the selected version ranges

pub fn load(&self, field: impl Into<Intent<Box<dyn Load>>>) -> Result<()>

Load the field for the selected generation set

pub fn query<K>( &self, field: Intent<Box<impl Query<Key = K>>>, pred: impl Fn(&K) -> QueryAction, ) -> Result<()>

Load into memory all data from field where pred returns true

pub fn iter<'a, K, O, Q>( &'a self, field: Intent<Box<Q>>, pred: impl Fn(&K) -> QueryAction + Send + Sync + 'static, ) -> Result<impl Iterator<Item = O> + Send + Sync + '_>

where for<'de> Q::Serialized: Deserialize<'de>, Q: Collection<Key = K, Item = O> + Send + Sync + 'static, K: Eq + Hash + Clone + Send + Sync + 'a,

Same as query, but returns an Iterator

pub fn index(&self) -> impl Deref<Target = I> + '_

Return an immutable reference to the internal index.

By design this is read-only, as the index fields should use internal mutability and be thread-safe individually.

pub fn backend(&self) -> Arc<dyn Backend>

Return the backend

This allows synchronization of backends that queue upload jobs, or other background tasks.

pub fn index_object_count(&self) -> usize

Returns the number of index objects

impl<I, CustomData> Infinitree<I, CustomData>

where CustomData: Serialize + DeserializeOwned + Send + Sync, I: Index + Clone + Store,

pub fn root_intent(&self) -> Intent<Box<LocalField<I>>>

If the Index of the tree is a primitive field, retrieve a handle.

This is mostly useful when used in conjunction with [Tree::iter].

Trait Implementations

impl<I, CustomData> Drop for Infinitree<I, CustomData>

where CustomData: Serialize + DeserializeOwned + Send + Sync + 'static,

fn drop(&mut self)

Executes the destructor for this type.