Struct StoreObjectHandle

pub struct StoreObjectHandle<S: HandleOwner> { /* private fields */ }

StoreObjectHandle is the lowest-level, untyped handle to an object with the id [object_id] in a particular store, [owner]. It provides functionality shared across all objects, such as reading and writing attributes and managing encryption keys.

Since it’s untyped, it doesn’t do any object kind validation, and is generally meant to implement higher-level typed handles.

For file-like objects with a data attribute, DataObjectHandle implements traits and helpers for doing more complex extent management and caches the content size.

For directory-like objects, Directory knows how to add and remove child objects and enumerate its children.

Implementations

impl<S: HandleOwner> StoreObjectHandle<S>

pub fn new( owner: Arc<S>, object_id: u64, permanent_keys: bool, options: HandleOptions, trace: bool, ) -> Self

Make a new StoreObjectHandle for the object with id [object_id] in store [owner].

pub fn owner(&self) -> &Arc<S>

pub fn store(&self) -> &ObjectStore

pub fn trace(&self) -> bool

pub fn is_encrypted(&self) -> bool

pub fn default_transaction_options<'b>(&self) -> Options<'b>

Get the default set of transaction options for this object. This is mostly the overall default, modified by any HandleOptions held by this handle.

pub async fn new_transaction_with_options<'b>( &self, attribute_id: u64, options: Options<'b>, ) -> Result<Transaction<'b>, Error>

pub async fn new_transaction<'b>( &self, attribute_id: u64, ) -> Result<Transaction<'b>, Error>

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

Flushes the underlying device. This is expensive and should be used sparingly.

pub async fn update_allocated_size( &self, transaction: &mut Transaction<'_>, allocated: u64, deallocated: u64, ) -> Result<(), Error>

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

pub async fn zero( &self, transaction: &mut Transaction<'_>, attribute_id: u64, range: Range<u64>, ) -> Result<(), Error>

Zeroes the given range. The range must be aligned. Returns the amount of data deallocated.

pub async fn align_buffer( &self, attribute_id: u64, offset: u64, buf: BufferRef<'_>, ) -> Result<(Range<u64>, Buffer<'_>), Error>

pub async fn shrink( &self, transaction: &mut Transaction<'_>, attribute_id: u64, size: u64, ) -> Result<NeedsTrim, Error>

Trim an attribute’s extents, potentially adding a graveyard trim entry if more trimming is needed, so the transaction can be committed without worrying about leaking data.

This doesn’t update the size stored in the attribute value - the caller is responsible for doing that to keep the size up to date.

pub async fn read_and_decrypt( &self, device_offset: u64, file_offset: u64, buffer: MutableBufferRef<'_>, key_id: u64, block_bitmap: Option<BitVec>, ) -> Result<(), Error>

pub async fn get_key(&self, key_id: Option<u64>) -> Result<Option<Key>, Error>

Returns the specified key. If key_id is None, it will try and return the fscrypt key if it is present, or the volume key if it isn’t. If the fscrypt key is present, but the key cannot be unwrapped, then this will return FxfsError::NoKey. If the volume is not encrypted, this returns None.

pub async fn read( &self, attribute_id: u64, offset: u64, buf: MutableBufferRef<'_>, ) -> Result<usize, Error>

pub async fn read_attr( &self, attribute_id: u64, ) -> Result<Option<Box<[u8]>>, Error>

Reads an entire attribute.

pub async fn write_at( &self, attribute_id: u64, offset: u64, buf: MutableBufferRef<'_>, key_id: Option<u64>, device_offset: u64, ) -> Result<MaybeChecksums, Error>

Writes potentially unaligned data at device_offset and returns checksums if requested. The data will be encrypted if necessary. buf is mutable as an optimization, since the write may require encryption, we can encrypt the buffer in-place rather than copying to another buffer if the write is already aligned.

NOTE: This will not create keys if they are missing (it will fail with an error if that happens to be the case).

pub async fn multi_write( &self, transaction: &mut Transaction<'_>, attribute_id: u64, key_id: Option<u64>, ranges: &[Range<u64>], buf: MutableBufferRef<'_>, ) -> Result<(), Error>

Writes to multiple ranges with data provided in buf. The buffer can be modified in place if encryption takes place. The ranges must all be aligned and no change to content size is applied; the caller is responsible for updating size if required. If key_id is None, it means pick the default key for the object which is the fscrypt key if present, or the volume data key, or no key if it’s an unencrypted file.

pub async fn multi_overwrite<'a>( &'a self, transaction: &mut Transaction<'a>, attr_id: u64, ranges: &[Range<u64>], buf: MutableBufferRef<'_>, ) -> Result<(), Error>

Write data to overwrite extents with the provided set of ranges. This makes a strong assumption that the ranges are actually going to be already allocated overwrite extents and will error out or do something wrong if they aren’t. It also assumes the ranges passed to it are sorted.

pub async fn write_new_attr_in_batches<'a>( &'a self, transaction: &mut Transaction<'a>, attribute_id: u64, data: &[u8], batch_size: usize, ) -> Result<(), Error>

Writes an attribute that should not already exist and therefore does not require trimming. Breaks up the write into multiple transactions if data.len() is larger than batch_size. If writing the attribute requires multiple transactions, adds the attribute to the graveyard. The caller is responsible for removing the attribute from the graveyard when it commits the last transaction. This always writes using a key wrapped with the volume data key.

pub async fn write_attr( &self, transaction: &mut Transaction<'_>, attribute_id: u64, data: &[u8], ) -> Result<NeedsTrim, Error>

Writes an entire attribute. Returns whether or not the attribute needs to continue being trimmed - if the new data is shorter than the old data, this will trim any extents beyond the end of the new size, but if there were too many for a single transaction, a commit needs to be made before trimming again, so the responsibility is left to the caller so as to not accidentally split the transaction when it’s not in a consistent state. This will write using the volume data key; the fscrypt key is not supported.

pub async fn list_extended_attributes(&self) -> Result<Vec<Vec<u8>>, Error>

pub async fn get_inline_selinux_context( &self, ) -> Result<Option<SelinuxContext>, Error>

Looks up the values for the extended attribute fio::SELINUX_CONTEXT_NAME, returning it if it is found inline. If it is not inline, it will request use of the get_extended_attributes method. If the entry doesn’t exist at all, returns None.

pub async fn get_extended_attribute( &self, name: Vec<u8>, ) -> Result<Vec<u8>, Error>

pub async fn set_extended_attribute( &self, name: Vec<u8>, value: Vec<u8>, mode: SetExtendedAttributeMode, ) -> Result<(), Error>

pub async fn remove_extended_attribute( &self, name: Vec<u8>, ) -> Result<(), Error>

pub fn pre_fetch_keys(&self) -> Option<impl Future<Output = ()>>

Returns a future that will pre-fetches the keys so as to avoid paying the performance penalty later. Must ensure that the object is not removed before the future completes.

Trait Implementations

impl<S: HandleOwner> Drop for StoreObjectHandle<S>

fn drop(&mut self)

Executes the destructor for this type.

impl<S: HandleOwner> ObjectHandle for StoreObjectHandle<S>

fn set_trace(&self, v: bool)

Sets tracing for this object.

fn object_id(&self) -> u64

Returns the object identifier for this object which will be unique for the store that the object is contained in, but not necessarily unique within the entire system.

fn allocate_buffer(&self, size: usize) -> BufferFuture<'_>

Allocates a buffer for doing I/O (read and write) for the object.

fn block_size(&self) -> u64

Returns the filesystem block size, which should be at least as big as the device block size, but not necessarily the same.