Struct Index

pub struct Index { /* private fields */ }

Main Index Insertion-only mapping from bytes to a list of u64s.

An Index is backed by an append-only file in the filesystem. Internally, it uses base16 radix trees for keys and linked list for u64 values. The file format was designed to be able to support other types of indexes (ex. non-radix-trees). Though none of them are implemented.

Implementations

impl Index

pub fn try_clone(&self) -> Result<Self>

Return a cloned Index with pending in-memory changes.

pub fn try_clone_without_dirty(&self) -> Result<Self>

Return a cloned Index without pending in-memory changes.

This is logically equivalent to calling clear_dirty immediately on the result after try_clone, but potentially cheaper.

pub fn get_meta(&self) -> &[u8]

Get metadata attached to the root node. This is what previously set by Index::set_meta.

pub fn get_original_meta(&self) -> &[u8]

Get metadata attached to the root node at file open time. This is what stored on the filesystem at the index open time, not affected by Index::set_meta.

pub fn set_meta<B: AsRef<[u8]>>(&mut self, meta: B)

Set metadata attached to the root node. Will be written at Index::flush time.

pub fn clear_dirty(&mut self)

Remove dirty (in-memory) state. Restore the Index to the state as if it’s just loaded from disk without modifications.

pub fn flush(&mut self) -> Result<u64>

Flush changes to disk.

Take the file lock when writing.

Return 0 if nothing needs to be written. Otherwise return the new file length on success. Return io::ErrorKind::PermissionDenied if the file was marked read-only at open time.

The new file length can be used to obtain the exact same view of the index as it currently is. That means, other changes to the indexes won’t be “combined” during flush. For example, given the following events happened in order:

• Open. Get Index X.
• Open using the same arguments. Get Index Y.
• Write key “p” to X.
• Write key “q” to Y.
• Flush X. Get new length LX.
• Flush Y. Get new length LY.
• Open using LY as logical_len. Get Index Z.

Then key “p” does not exist in Z. This allows some advanced use cases. On the other hand, if “merging changes” is the desired behavior, the caller needs to take another lock, re-instantiate Index and re-insert keys.

For in-memory-only indexes, this function does nothing and returns 0, unless read-only was set at open time.

pub fn get<K: AsRef<[u8]>>(&self, key: &K) -> Result<LinkOffset>

Lookup by key. Return LinkOffset.

To test if the key exists or not, use Offset::is_null. To obtain all values, use LinkOffset::values.

pub fn scan_prefix_base16( &self, base16: impl Iterator<Item = u8>, ) -> Result<RangeIter<'_>>

Scan entries which match the given prefix in base16 form. Return RangeIter which allows accesses to keys and values.

pub fn scan_prefix<B: AsRef<[u8]>>(&self, prefix: B) -> Result<RangeIter<'_>>

Scan entries which match the given prefix in base256 form. Return RangeIter which allows accesses to keys and values.

pub fn scan_prefix_hex<B: AsRef<[u8]>>( &self, prefix: B, ) -> Result<RangeIter<'_>>

Scan entries which match the given prefix in hex form. Return RangeIter which allows accesses to keys and values.

pub fn range<'a>( &self, range: impl RangeBounds<&'a [u8]>, ) -> Result<RangeIter<'_>>

Scans entries whose keys are within the given range.

Returns a double-ended iterator, which provides accesses to keys and values.

pub fn insert<K: AsRef<[u8]>>(&mut self, key: &K, value: u64) -> Result<()>

Insert a key-value pair. The value will be the head of the linked list. That is, get(key).values().first() will return the newly inserted value.

pub fn remove(&mut self, key: impl AsRef<[u8]>) -> Result<()>

Remove all values associated with the given key.

pub fn remove_prefix(&mut self, prefix: impl AsRef<[u8]>) -> Result<()>

Remove all values associated with all keys with the given prefix.

pub fn insert_advanced( &mut self, key: InsertKey<'_>, value: InsertValue, ) -> Result<()>

Update the linked list for a given key.

If link is None, behave like insert. Otherwise, ignore the existing values key mapped to, create a new link entry that chains to the given LinkOffset.

key could be a reference, or an embedded value. See InsertKey for details.

This is a low-level API.

pub fn slice_to_bytes(&self, slice: &[u8]) -> Bytes

Convert a slice to Bytes. Do not copy the slice if it’s from the on-disk buffer.

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

Verify checksum for the entire on-disk buffer.

Trait Implementations

impl Debug for Index

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

Formats the value using the given formatter.