Struct ObjectStore

pub struct ObjectStore { /* private fields */ }

An object store supports a file like interface for objects. Objects are keyed by a 64 bit identifier. And object store has to be backed by a parent object store (which stores metadata for the object store). The top-level object store (a.k.a. the root parent object store) is in-memory only.

Implementations

impl ObjectStore

pub async fn flush_with_reason(&self, reason: Reason) -> Result<Version, Error>

impl ObjectStore

pub async fn set_project_limit( &self, project_id: u64, bytes: u64, nodes: u64, ) -> Result<(), Error>

Adds a mutation to set the project limit as an attribute with bytes and nodes to root node.

pub async fn clear_project_limit(&self, project_id: u64) -> Result<(), Error>

Clear the limit for a project by tombstoning the limits and usage attributes for the given project_id. Fails if the project is still in use by one or more nodes.

pub async fn set_project_for_node( &self, node_id: u64, project_id: u64, ) -> Result<(), Error>

Apply a project_id to a given node. Fails if node is not found or target project is zero.

pub async fn get_project_for_node(&self, node_id: u64) -> Result<u64, Error>

Return the project_id associated with the given node_id.

pub async fn clear_project_for_node(&self, node_id: u64) -> Result<(), Error>

Remove the project id for a given node_id. The call will do nothing and return success if the node is found to not be associated with any project.

pub async fn list_projects( &self, start_id: u64, max_entries: usize, ) -> Result<(Vec<u64>, Option<u64>), Error>

Returns a list of project ids currently tracked with project limits or usage in ascending order, beginning after last_id and providing up to max_entries. If max_entries would be exceeded then it also returns the final id in the list, for use in the following call to resume the listing.

pub async fn project_info( &self, project_id: u64, ) -> Result<(Option<(u64, u64)>, Option<(u64, u64)>), Error>

Looks up the limit and usage of project_id as a pair of bytes and notes. Any of the two fields not found will return None for them.

impl ObjectStore

pub fn new_root_parent( device: Arc<dyn Device>, block_size: u64, store_object_id: u64, ) -> Self

Cycle breaker constructor that returns an ObjectStore without a filesystem. This should only be used from super block code.

pub fn attach_filesystem( this: ObjectStore, filesystem: Arc<FxFilesystem>, ) -> ObjectStore

Used to set filesystem on root_parent stores at bootstrap time after the filesystem has been created.

pub fn set_trace(&self, trace: bool)

pub fn set_flush_callback<F: Fn(&ObjectStore) + Send + Sync + 'static>( &self, callback: F, )

Sets a callback to be invoked each time the ObjectStore flushes. The callback is invoked at the end of flush, while the write lock is still held.

pub fn is_root(&self) -> bool

pub fn record_data(self: &Arc<Self>, root: &Node)

Populates an inspect node with store statistics.

pub fn device(&self) -> &Arc<dyn Device>

pub fn block_size(&self) -> u64

pub fn filesystem(&self) -> Arc<FxFilesystem>

pub fn store_object_id(&self) -> u64

pub fn tree(&self) -> &LSMTree<ObjectKey, ObjectValue>

pub fn root_directory_object_id(&self) -> u64

pub fn graveyard_directory_object_id(&self) -> u64

pub fn object_count(&self) -> u64

pub fn key_manager(&self) -> &KeyManager

pub fn parent_store(&self) -> Option<&Arc<ObjectStore>>

pub fn crypt(&self) -> Option<Arc<dyn Crypt>>

Returns the crypt object for the store. Returns None if the store is unencrypted.

pub async fn get_or_create_internal_directory_id( self: &Arc<Self>, ) -> Result<u64, Error>

pub async fn open_object<S: HandleOwner>( owner: &Arc<S>, obj_id: u64, options: HandleOptions, crypt: Option<Arc<dyn Crypt>>, ) -> Result<DataObjectHandle<S>, Error>

crypt can be provided if the crypt service should be different to the default; see the comment on create_object. Users should avoid having more than one handle open for the same object at the same time because they might get out-of-sync; there is no code that will prevent this. One example where this can cause an issue is if the object ends up using a permanent key (which is the case if a value is passed for crypt), the permanent key is dropped when a handle is dropped, which will impact any other handles for the same object.

pub async fn create_object<S: HandleOwner>( owner: &Arc<S>, transaction: &mut Transaction<'_>, options: HandleOptions, wrapping_key_id: Option<u128>, ) -> Result<DataObjectHandle<S>, Error>

Creates an object in the store.

If the store is encrypted, the object will be automatically encrypted as well. If wrapping_key_id is set, the new keys will be wrapped with that specific key, and otherwise the default data key is used.

pub async fn adjust_refs( &self, transaction: &mut Transaction<'_>, oid: u64, delta: i64, ) -> Result<bool, Error>

Adjusts the reference count for a given object. If the reference count reaches zero, the object is moved into the graveyard and true is returned.

pub async fn tombstone_object( &self, object_id: u64, txn_options: Options<'_>, ) -> Result<(), Error>

pub async fn trim(&self, object_id: u64) -> Result<(), Error>

Trim extents beyond the end of a file for all attributes. This will remove the entry from the graveyard when done.

pub async fn tombstone_attribute( &self, object_id: u64, attribute_id: u64, txn_options: Options<'_>, ) -> Result<(), Error>

pub async fn trim_some( &self, transaction: &mut Transaction<'_>, object_id: u64, attribute_id: u64, mode: TrimMode, ) -> Result<TrimResult, Error>

Deletes extents for attribute attribute_id in object object_id. Also see the comments for TrimMode and TrimResult. Should hold a lock on the attribute, and the object as it performs a read-modify-write on the sizes.

pub fn parent_objects(&self) -> Vec<u64>

Returns all objects that exist in the parent store that pertain to this object store. Note that this doesn’t include the object_id of the store itself which is generally referenced externally.

pub fn root_objects(&self) -> Vec<u64>

Returns root objects for this store.

pub fn store_info(&self) -> Option<StoreInfo>

pub fn store_info_handle_object_id(&self) -> Option<u64>

Returns None if called during journal replay.

pub async fn unlock( self: &Arc<Self>, owner: Weak<dyn StoreOwner>, crypt: Arc<dyn Crypt>, ) -> Result<(), Error>

Unlocks a store so that it is ready to be used. This is not thread-safe.

pub async fn unlock_read_only( self: &Arc<Self>, crypt: Arc<dyn Crypt>, ) -> Result<(), Error>

Unlocks a store so that it is ready to be read from. The store will generally behave like it is still locked: when flushed, the store will write out its mutations into the encrypted mutations file, rather than directly updating the layer files of the object store. Re-locking the store (which must be done with Self::lock_read_only will not trigger a flush, although the store might still be flushed during other operations. This is not thread-safe.

pub fn is_locked(&self) -> bool

pub fn is_unlocked(&self) -> bool

NB: This is not the converse of is_locked, as there are lock states where neither are true.

pub fn is_unknown(&self) -> bool

pub fn is_encrypted(&self) -> bool

pub async fn lock(&self) -> Result<(), Error>

pub fn lock_read_only(&self)

pub async fn get_next_object_id( &self, txn_guard: &TxnGuard<'_>, ) -> Result<u64, Error>

Returns a new object ID that can be used. This will create an object ID cipher if needed.

If the object ID key needs to be rolled, a new transaction will be created and committed. This transaction does not take the filesystem lock, hence txn_guard.

pub fn add_to_graveyard( &self, transaction: &mut Transaction<'_>, object_id: u64, )

Adds the specified object to the graveyard.

pub fn remove_from_graveyard( &self, transaction: &mut Transaction<'_>, object_id: u64, )

Removes the specified object from the graveyard. NB: Care should be taken when calling this because graveyard entries are used for purging deleted files and for trimming extents. For example, consider the following sequence:

1. Add Trim graveyard entry.
2. Replace with Some graveyard entry (see above).
3. Remove graveyard entry.

If the desire in #3 is just to cancel the effect of the Some entry, then #3 should actually be:

3. Replace with Trim graveyard entry.

pub fn remove_attribute_from_graveyard( &self, transaction: &mut Transaction<'_>, object_id: u64, attribute_id: u64, )

Removes the specified attribute from the graveyard. Unlike object graveyard entries, attribute graveyard entries only have one functionality (i.e. to purge deleted attributes) so the caller does not need to be concerned about replacing the graveyard attribute entry with its prior state when cancelling it. See comment on remove_from_graveyard().

pub async fn read_symlink(&self, object_id: u64) -> Result<Vec<u8>, Error>

Returns the link of a symlink object.

pub async fn get_keys(&self, object_id: u64) -> Result<WrappedKeys, Error>

Retrieves the wrapped keys for the given object. The keys should be known to exist and it will be considered an inconsistency if they don’t.

pub async fn update_attributes<'a>( &self, transaction: &mut Transaction<'a>, object_id: u64, node_attributes: Option<&MutableNodeAttributes>, change_time: Option<Timestamp>, ) -> Result<(), Error>

Trait Implementations

impl AsRef<ObjectStore> for ObjectStore

fn as_ref(&self) -> &ObjectStore

Converts this type into a shared reference of the (usually inferred) input type.

impl AssociatedObject for ObjectStore

fn will_apply_mutation( &self, _mutation: &Mutation, _object_id: u64, _manager: &ObjectManager, )

impl JournalingObject for ObjectStore

fn flush<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Version, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Push all in-memory structures to the device. This is not necessary for sync since the journal will take care of it. This is supposed to be called when there is either memory or space pressure (flushing the store will persist in-memory data and allow the journal file to be trimmed).

Also returns the earliest version of a struct in the filesystem (when known).

fn apply_mutation( &self, mutation: Mutation, context: &ApplyContext<'_, '_>, _assoc_obj: AssocObj<'_>, ) -> Result<(), Error>

This method get called when the transaction commits, which can either be during live operation (See ObjectManager::apply_mutation) or during journal replay, in which case transaction will be None (See super_block::read).

fn drop_mutation(&self, _mutation: Mutation, _transaction: &Transaction<'_>)

Called when a transaction fails to commit.

fn write_mutation(&self, mutation: &Mutation, writer: Writer<'_>)

Writes a mutation to the journal. This allows objects to encrypt or otherwise modify what gets written to the journal.

impl HandleOwner for ObjectStore