Struct nebari::tree::TreeFile

pub struct TreeFile<Root: Root, File: ManagedFile> {
    pub state: State<Root>,
    /* private fields */
}

An append-only tree file.

Generics

• File: An ManagedFile implementor.

Fields

state: State<Root>

The state of the file.

Implementations

impl<Root: Root, File: ManagedFile> TreeFile<Root, File>

pub fn new(
    file: <File::Manager as FileManager>::FileHandle,
    state: State<Root>,
    vault: Option<Arc<dyn AnyVault>>,
    cache: Option<ChunkCache>
) -> Result<Self, Error>

Returns a tree as contained in file.

state should already be initialized using Self::initialize_state if the file exists.

pub fn read(
    path: impl AsRef<Path>,
    state: State<Root>,
    context: &Context<File::Manager>,
    transactions: Option<&TransactionManager<File::Manager>>
) -> Result<Self, Error>

Opens a tree file with read-only permissions.

pub fn write(
    path: impl AsRef<Path>,
    state: State<Root>,
    context: &Context<File::Manager>,
    transactions: Option<&TransactionManager<File::Manager>>
) -> Result<Self, Error>

Opens a tree file with the ability to read and write.

pub fn initialize_state(
    state: &State<Root>,
    file_path: &Path,
    file_id: Option<u64>,
    context: &Context<File::Manager>,
    transaction_manager: Option<&TransactionManager<File::Manager>>
) -> Result<(), Error>

Attempts to load the last saved state of this tree into state.

pub fn set(
    &mut self,
    persistence_mode: impl Into<PersistenceMode>,
    key: impl Into<ArcBytes<'static>>,
    value: impl Into<ArcBytes<'static>>
) -> Result<Root::Index, Error>

Sets a key/value pair. Replaces any previous value if set. If you wish to retrieve the previously stored value, use replace() instead.

Returns the new/updated index for this key.

pub fn modify(
    &mut self,
    modification: Modification<'_, ArcBytes<'static>, Root::Index>
) -> Result<Vec<ModificationResult<Root::Index>>, Error>

Executes a modification. Returns a list of modified keys and their updated indexes, if the keys are still present.

pub fn compare_and_swap(
    &mut self,
    key: &[u8],
    old: Option<&[u8]>,
    new: Option<ArcBytes<'_>>,
    persistence_mode: impl Into<PersistenceMode>
) -> Result<(), CompareAndSwapError>

Compares the value of key against old. If the values match, key will be set to the new value if new is Some or removed if new is None.

pub fn remove(
    &mut self,
    key: &[u8],
    persistence_mode: impl Into<PersistenceMode>
) -> Result<Option<(ArcBytes<'static>, Root::Index)>, Error>

Removes key and returns the existing value and index, if present.

pub fn replace(
    &mut self,
    key: impl Into<ArcBytes<'static>>,
    value: impl Into<ArcBytes<'static>>,
    persistence_mode: impl Into<PersistenceMode>
) -> Result<(Option<ArcBytes<'static>>, Root::Index), Error>

Sets key to value. Returns a tuple containing two elements:

• The previously stored value, if a value was already present.
• The new/updated index for this key.

pub fn get(
    &mut self,
    key: &[u8],
    in_transaction: bool
) -> Result<Option<ArcBytes<'static>>, Error>

Gets the value stored for key.

pub fn get_index(
    &mut self,
    key: &[u8],
    in_transaction: bool
) -> Result<Option<Root::Index>, Error>

Gets the index stored for key.

pub fn get_with_index(
    &mut self,
    key: &[u8],
    in_transaction: bool
) -> Result<Option<(ArcBytes<'static>, Root::Index)>, Error>

Gets the value and index stored for key.

pub fn get_multiple<'keys, KeysIntoIter, KeysIter>(
    &mut self,
    keys: KeysIntoIter,
    in_transaction: bool
) -> Result<Vec<(ArcBytes<'static>, ArcBytes<'static>)>, Error> where
    KeysIntoIter: IntoIterator<Item = &'keys [u8], IntoIter = KeysIter>,
    KeysIter: Iterator<Item = &'keys [u8]> + ExactSizeIterator, 

Gets the values stored in keys. Does not error if a key is missing. Returns key/value pairs in an unspecified order. Keys are required to be pre-sorted.

pub fn get_multiple_indexes<'keys, KeysIntoIter, KeysIter>(
    &mut self,
    keys: KeysIntoIter,
    in_transaction: bool
) -> Result<Vec<(ArcBytes<'static>, Root::Index)>, Error> where
    KeysIntoIter: IntoIterator<Item = &'keys [u8], IntoIter = KeysIter>,
    KeysIter: Iterator<Item = &'keys [u8]> + ExactSizeIterator, 

Gets the indexes stored in keys. Does not error if a key is missing. Returns key/value pairs in an unspecified order. Keys are required to be pre-sorted.

pub fn get_multiple_with_indexes<'keys, KeysIntoIter, KeysIter>(
    &mut self,
    keys: KeysIntoIter,
    in_transaction: bool
) -> Result<Vec<(ArcBytes<'static>, ArcBytes<'static>, Root::Index)>, Error> where
    KeysIntoIter: IntoIterator<Item = &'keys [u8], IntoIter = KeysIter>,
    KeysIter: Iterator<Item = &'keys [u8]> + ExactSizeIterator, 

Gets the values and indexes stored in keys. Does not error if a key is missing. Returns key/value pairs in an unspecified order. Keys are required to be pre-sorted.

pub fn get_range<'keys, KeyRangeBounds>(
    &mut self,
    range: &'keys KeyRangeBounds,
    in_transaction: bool
) -> Result<Vec<(ArcBytes<'static>, ArcBytes<'static>)>, Error> where
    KeyRangeBounds: RangeBounds<&'keys [u8]> + Debug + ?Sized, 

Retrieves all keys and values for keys that are contained by range.

pub fn get_range_indexes<'keys, KeyRangeBounds>(
    &mut self,
    range: &'keys KeyRangeBounds,
    in_transaction: bool
) -> Result<Vec<(ArcBytes<'static>, Root::Index)>, Error> where
    KeyRangeBounds: RangeBounds<&'keys [u8]> + Debug + ?Sized, 

Retrieves all keys and indexes for keys that are contained by range.

pub fn get_range_with_indexes<'keys, KeyRangeBounds>(
    &mut self,
    range: &'keys KeyRangeBounds,
    in_transaction: bool
) -> Result<Vec<(ArcBytes<'static>, ArcBytes<'static>, Root::Index)>, Error> where
    KeyRangeBounds: RangeBounds<&'keys [u8]> + Debug + ?Sized, 

Retrieves all keys and values and indexes for keys that are contained by range.

pub fn scan<'keys, CallerError, KeyRangeBounds, NodeEvaluator, KeyEvaluator, DataCallback>(
    &mut self,
    range: &'keys KeyRangeBounds,
    forwards: bool,
    in_transaction: bool,
    node_evaluator: &mut NodeEvaluator,
    key_evaluator: &mut KeyEvaluator,
    key_reader: &mut DataCallback
) -> Result<(), AbortError<CallerError>> where
    KeyRangeBounds: RangeBounds<&'keys [u8]> + Debug + ?Sized,
    NodeEvaluator: FnMut(&ArcBytes<'static>, &Root::ReducedIndex, usize) -> ScanEvaluation,
    KeyEvaluator: FnMut(&ArcBytes<'static>, &Root::Index) -> ScanEvaluation,
    DataCallback: FnMut(ArcBytes<'static>, &Root::Index, ArcBytes<'static>) -> Result<(), AbortError<CallerError>>,
    CallerError: Display + Debug, 

Scans the tree across all nodes that might contain nodes within range.

If forwards is true, the tree is scanned in ascending order. Otherwise, the tree is scanned in descending order.

node_evaluator is invoked for each Interior node to determine if the node should be traversed. The parameters to the callback are:

• &ArcBytes<'static>: The maximum key stored within the all children nodes.
• &Root::ReducedIndex: The reduced index value stored within the node.
• usize: The depth of the node. The root nodes are depth 0.

The result of the callback is a ScanEvaluation. To read children nodes, return ScanEvaluation::ReadData.

key_evaluator is invoked for each key encountered that is contained within range. For all ScanEvaluation::ReadData results returned, callback will be invoked with the key and values. callback may not be invoked in the same order as the keys are scanned.

pub fn reduce<'keys, KeyRangeBounds>(
    &mut self,
    range: &'keys KeyRangeBounds,
    in_transaction: bool
) -> Result<Option<Root::ReducedIndex>, Error> where
    KeyRangeBounds: RangeBounds<&'keys [u8]> + Debug + ?Sized,
    Root::Index: Clone, 

Returns the reduced index over the provided range. This is an aggregation function that builds atop the scan() operation which calls Reducer::reduce() and Reducer::rereduce() on all matching indexes stored within the nodes of this tree, producing a single aggregated Root::ReducedIndex value.

If no keys match, the returned result is what Reducer::rereduce() returns when an empty slice is provided.

pub fn first_key(
    &mut self,
    in_transaction: bool
) -> Result<Option<ArcBytes<'static>>, Error>

Returns the first key of the tree.

pub fn first(
    &mut self,
    in_transaction: bool
) -> Result<Option<(ArcBytes<'static>, ArcBytes<'static>)>, Error>

Returns the first key and value of the tree.

pub fn last_key(
    &mut self,
    in_transaction: bool
) -> Result<Option<ArcBytes<'static>>, Error>

Returns the last key of the tree.

pub fn last(
    &mut self,
    in_transaction: bool
) -> Result<Option<(ArcBytes<'static>, ArcBytes<'static>)>, Error>

Returns the last key and value of the tree.

pub fn commit(&mut self) -> Result<(), Error>

Commits the tree. This is only needed if writes were done with a transaction id. This will fully flush the tree and publish the transactional state to be available to readers.

pub fn compact(
    self,
    file_manager: &File::Manager,
    transactions: Option<TransactableCompaction<'_, File::Manager>>
) -> Result<Self, Error>

Rewrites the database, removing all unused data in the process. For a VersionedTreeRoot, this will remove old version information.

This process is done atomically by creating a new file containing the active data. Once the new file has all the current file’s data, the file contents are swapped using atomic file operations.

impl<File: ManagedFile, Index> TreeFile<VersionedTreeRoot<Index>, File> where
    Index: EmbeddedIndex + Clone + Debug + 'static, 

pub fn scan_sequences<CallerError, Range, KeyEvaluator, DataCallback>(
    &mut self,
    range: Range,
    forwards: bool,
    in_transaction: bool,
    key_evaluator: &mut KeyEvaluator,
    data_callback: &mut DataCallback
) -> Result<(), AbortError<CallerError>> where
    Range: RangeBounds<SequenceId> + Debug + 'static,
    KeyEvaluator: FnMut(KeySequence<Index>) -> ScanEvaluation,
    DataCallback: FnMut(KeySequence<Index>, ArcBytes<'static>) -> Result<(), AbortError<CallerError>>,
    CallerError: Display + Debug, 

Scans the tree for keys that are contained within range. If forwards is true, scanning starts at the lowest sort-order key and scans forward. Otherwise, scanning starts at the highest sort-order key and scans backwards. key_evaluator is invoked for each key as it is encountered. For all ScanEvaluation::ReadData results returned, callback will be invoked with the key and values. The callback may not be invoked in the same order as the keys are scanned.

pub fn get_multiple_by_sequence<Sequences>(
    &mut self,
    sequences: Sequences,
    in_transaction: bool
) -> Result<HashMap<SequenceId, (ArcBytes<'static>, Option<ArcBytes<'static>>)>, Error> where
    Sequences: Iterator<Item = SequenceId>, 

Retrieves the keys and values associated with one or more sequences. The value retrieved is the value of the key at the given SequenceId. If a sequence is not found, it will not appear in the result map. If the value was removed, None is returned for the value.

pub fn get_multiple_indexes_by_sequence<Sequences>(
    &mut self,
    sequences: Sequences,
    in_transaction: bool
) -> Result<Vec<SequenceIndex<Index>>, Error> where
    Sequences: Iterator<Item = SequenceId>, 

Retrieves the keys and indexes associated with one or more sequences. The value retrieved is the value of the key at the given SequenceId. If a sequence is not found, it will not appear in the result list.

pub fn get_multiple_with_indexes_by_sequence<Sequences>(
    &mut self,
    sequences: Sequences,
    in_transaction: bool
) -> Result<HashMap<SequenceId, SequenceEntry<Index>>, Error> where
    Sequences: Iterator<Item = SequenceId>, 

Retrieves the keys, values, and indexes associated with one or more sequences. The value retrieved is the value of the key at the given SequenceId. If a sequence is not found, it will not appear in the result list.

Trait Implementations

impl<Root: Debug + Root, File: Debug + ManagedFile> Debug for TreeFile<Root, File> where
    File::Manager: Debug, 

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

Formats the value using the given formatter.

impl<Root: Root, File: ManagedFile> Deref for TreeFile<Root, File>

type Target = <File::Manager as FileManager>::FileHandle

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<Root: Root, File: ManagedFile> DerefMut for TreeFile<Root, File>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.