Struct tor_persist::state_dir::InstanceStateHandle

pub struct InstanceStateHandle { /* private fields */ }

Available on crate feature state-dir only.

State or cache directory for an instance of a facility

Implies exclusive access: there is only one InstanceStateHandle at a time, across any number of processes, tasks, and threads, for the same instance.

Key uniqueness and syntactic restrictions

Methods on InstanceStateHandle typically take a TryIntoSlug.

It is important that keys are distinct within an instance.

Specifically: each key provided to a method on the same InstanceStateHandle (or a clone of it) must be different. Violating this rule does not result in memory-unsafety, but might result in incorrect operation due to concurrent filesystem access, including possible data loss and corruption. (Typically, the key is fixed, and the StorageHandles are usually obtained during instance construction, so ensuring this is straightforward.)

There are also syntactic restrictions on keys. See slug.

Implementations

impl InstanceStateHandle

pub fn storage_handle<T>( &self, key: &(impl TryIntoSlug + ?Sized) ) -> Result<StorageHandle<T>>

Obtain a StorageHandle, usable for storing/retrieving a T

key has syntactic and uniqueness restrictions.

pub fn raw_subdir( &self, key: &(impl TryIntoSlug + ?Sized) ) -> Result<InstanceRawSubdir>

Obtain a raw filesystem subdirectory, within the directory for this instance

This API is unsuitable platforms without a filesystem accessible via std::fs. May therefore only be used within Arti for features where we’re happy to not to support such platforms (eg WASM without WASI) without substantial further work.

key has syntactic and uniqueness restrictions.

pub fn purge(self) -> Result<()>

Unconditionally delete this instance directory

For expiry, use StateDirectory::purge_instances, and then call this in the dispose method.

Will return a BadAPIUsage if other clones of this InstanceStateHandle exist.

Deletion is not atomic

If a deletion operation doesn’t complete for any reason (maybe it was interrupted, or there was a filesystem access problem), part of the instance contents may remain.

After such an interrupted deletion, storage items (StorageHandle) are might each independently be deleted (load returns None) or retained (Some).

Deletion of the contents of raw subdirectories (InstanceStateHandle::raw_subdir) is done with std::fs::remove_dir_all. If deletion is interrupted, the raw subdirectory may contain partial contents.

Trait Implementations

impl Clone for InstanceStateHandle

fn clone(&self) -> InstanceStateHandle

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ContainsInstanceStateGuard for InstanceStateHandle

fn raw_lock_guard(&self) -> Arc<LockFileGuard>

Obtain a raw clone of the underlying filesystem lock

impl Debug for InstanceStateHandle

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

Formats the value using the given formatter.