Struct VarView 

pub struct VarView<'page> { /* private fields */ }

A mutable view of the var-len section of a Page.

Implementations

impl<'page> VarView<'page>

pub fn alloc_for_len( &mut self, obj_len: usize, ) -> Result<(VarLenRef, bool), Error>

Allocates a linked-list of granules, in the var-len storage of the page, for a var-len object of obj_len bytes.

Returns a VarLenRef pointing to the head of that list, and a boolean in_blob for whether the allocation is a BlobHash and the object must be inserted into the large-blob store.

The length of each granule is set, but no data is written to any granule. Thus, the caller must proceed to write data to each granule for the claimed lengths.

Safety post-requirements

The following are the safety post-requirements of calling this method. That is, this method is safe to call, but may leave the page in an inconsistent state which must be rectified before other unsafe methods may be called.

1. When the returned in_blob holds, caller must ensure that, before the granule’s data is read from / assumed to be initialized, the granule pointed to by the returned vlr.first_granule has an initialized header and a data section initialized to at least as many bytes as claimed by the header.

2. The caller must initialize each granule with data for the claimed length of the granule’s data.

pub unsafe fn granule_offset_iter( &mut self, first_granule: PageOffset, ) -> GranuleOffsetIter<'_, 'page>

Returns an iterator over all offsets of the VarLenGranules of the var-len object that has its first granule at offset first_granule. An empty iterator will be returned when first_granule is NULL.

Safety

first_granule must be an offset to a granule or NULL. The data of the granule need not be initialized.

pub fn alloc_for_slice( &mut self, slice: &[u8], ) -> Result<(VarLenRef, bool), Error>

Allocates and stores slice as a linked-list of granules in the var-len storage of the page.

Returns a VarLenRef pointing to the head of that list, and a boolean in_blob for whether the allocation is a BlobHash and the slice must be inserted into the large-blob store.

Safety post-requirements

The following are the safety post-requirements of calling this method. That is, this method is safe to call, but may leave the page in an inconsistent state which must be rectified before other unsafe methods may be called.

1. When the returned in_blob holds, caller must ensure that, before the granule’s data is read from / assumed to be initialized, the granule pointed to by the returned vlr.first_granule has an initialized header and a data section initialized to at least as many bytes as claimed by the header.

pub unsafe fn write_large_blob_hash_to_granule( &mut self, blob_store: &mut dyn BlobStore, var_len_obj: &impl AsRef<[u8]>, vlr: VarLenRef, ) -> BlobNumBytes

Inserts var_len_obj into blob_store and stores the blob hash in the granule pointed to by vlr.first_granule.

This insertion will never fail.

Safety

vlr.first_granule must point to an unused VarLenGranule in bounds of this page, which must be valid for writes.

pub unsafe fn free_object_ignore_blob(&mut self, var_len_obj: VarLenRef)

Frees an entire var-len linked-list object.

If the var_len_obj is a large blob, the VarLenGranule which stores its blob hash will be freed from the page, but the blob itself will not be freed from the blob store. If used incorrectly, this may leak large blobs.

This behavior is used to roll-back on failure in [crate::bflatn::ser::write_av_to_page], where inserting large blobs is deferred until all allocations succeed. Freeing a fully-inserted object should instead use Self::free_object.

Safety

var_len_obj.first_granule must point to a valid VarLenGranule or be NULL.