Struct libimagstore::store::Store

pub struct Store { /* fields omitted */ }

The Store itself, through this object one can interact with IMAG's entries

Methods

impl Store

pub fn new(location: PathBuf, store_config: &Option<Value>) -> Result<Store>

Create a new Store object

This opens a Store in location. The store_config is used to check whether creating the store implicitely is allowed.

If the location does not exist, creating directories is by default denied and the operation fails, if not configured otherwise. An error is returned in this case.

If the path exists and is a file, the operation is aborted as well, an error is returned.

Return values

• On success: Store object

pub fn new_with_backend(
    location: PathBuf,
    store_config: &Option<Value>,
    backend: Arc<dyn FileAbstraction>
) -> Result<Store>

Create a Store object as descripbed in Store::new() documentation, but with an alternative backend implementation.

Do not use directly, only for testing purposes.

pub fn create<'a, S: IntoStoreId>(&'a self, id: S) -> Result<FileLockEntry<'a>>

Creates the Entry at the given location (inside the entry)

Return value

On success: FileLockEntry

pub fn retrieve<'a, S: IntoStoreId>(
    &'a self,
    id: S
) -> Result<FileLockEntry<'a>>

Borrow a given Entry. When the FileLockEntry is either updated or dropped, the new Entry is written to disk

Implicitely creates a entry in the store if there is no entry with the id id. For a non-implicitely-create look at Store::get.

Return value

On success: FileLockEntry

pub fn get<'a, S: IntoStoreId + Clone>(
    &'a self,
    id: S
) -> Result<Option<FileLockEntry<'a>>>

Get an entry from the store if it exists.

Return value

On success: Some(FileLockEntry) or None

On error:

• Errors StoreId::into_storeid() might return
• Errors Store::retrieve() might return

pub fn update<'a>(&'a self, entry: &mut FileLockEntry<'a>) -> Result<()>

Write (update) the FileLockEntry to disk

Return value

On success: Entry

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

Flush the store internal cache

This is helpful if a lot of entries are beeing read/written, because the store holds the file handles internally. At some point, the OS simply errors with "Too many files open". With this function, not-borrowed entries can be flushed back to disk and thus file handles are dropped.

After the flushables are dropped, the internal cache is shrinked to fit the number of elements still in the cache.

pub fn cache_size(&self) -> Result<usize>

The number of elements in the internal cache

pub fn cache_capacity(&self) -> Result<usize>

The size of the internal cache

pub fn get_copy<S: IntoStoreId>(&self, id: S) -> Result<Entry>

Return value

On success: Entry

pub fn delete<S: IntoStoreId>(&self, id: S) -> Result<()>

Delete an entry and the corrosponding file on disk

Return value

On success: ()

pub fn save_to(&self, entry: &FileLockEntry, new_id: StoreId) -> Result<()>

Save a copy of the Entry in another place

pub fn save_as(&self, entry: FileLockEntry, new_id: StoreId) -> Result<()>

Save an Entry in another place Removes the original entry

pub fn move_by_id(&self, old_id: StoreId, new_id: StoreId) -> Result<()>

Move an entry without loading

This function moves an entry from one path to another.

Generally, this function shouldn't be used by library authors, if they "just" want to move something around. A library for moving entries while caring about meta-data and links.

Errors

This function returns an error in certain cases:

• If the about-to-be-moved entry is borrowed
• If the lock on the internal data structure cannot be aquired
• If the new path already exists
• If the about-to-be-moved entry does not exist
• If the FS-operation failed

Warnings

This should be used with great care, as moving an entry from a to b might result in dangling links (see below).

Moving linked entries

If the entry which is moved is linked to another entry, these links get invalid (but we do not detect this here). As links are always two-way-links, so a is not only linked to b, but also the other way round, moving b to c results in the following scenario:

• a links to b, which does not exist anymore.
• c links to a, which does exist.

So the link is partly dangling, so to say.

pub fn entries<'a>(&'a self) -> Result<Entries<'a>>

Get all entries in the store (by id as iterator)

pub fn exists<'a>(&'a self, id: StoreId) -> Result<bool>

Check whether the store has the Entry pointed to by the StoreId id

pub fn path(&self) -> &PathBuf

Gets the path where this store is on the disk

Trait Implementations

impl Debug for Store

fn fmt(&self, fmt: &mut Formatter) -> RResult<(), FMTError>

Formats the value using the given formatter.