Enum ReservationOptions 

pub enum ReservationOptions<'a> {
    New,
    BorrowedMetadata,
    BorrowedMetadataAndData,
    Hold(&'a Reservation),
}

How metadata and allocator reservations should be handled for a transaction.

A transaction consumes space in two different ways:

1. The transaction will consume space in the journal and eventually in an LSM tree (the “metadata” cost of the transaction).
2. The transaction might also include additional allocations or deallocations. These may come directly from the global allocator, or they might come from a Reservation object, depending on the context. (See specific enum cases for details.)

The basic decision tree for which variant to use is as follows:

• Is there an existing reservation which the transaction should draw from?
  • YES: Use ReservationOptions::Hold
  • NO: Is the transaction allocating or deallocating extents for internal filesystem metadata (e.g. LSM tree compaction, journal/superblock growth, or graveyard tombstoning in the root/root-parent stores)? - YES: Use ReservationOptions::BorrowedMetadataAndData - NO: Is the transaction expected to be space-neutral or space-saving? - YES: Use ReservationOptions::BorrowedMetadata - NO: Use ReservationOptions::New

Variants

New

A new reservation is created to accommodate the metadata of a maximally-sized transaction, and the transaction’s metadata is paid for from this reservation. Allocations and deallocations within the transaction will go directly to the global allocator (and therefore might fail if there’s insufficient space).

This should be the default case for most transactions which permit failure when there’s no space left in the global allocator.

BorrowedMetadata

Metadata space is borrowed directly from the global reservation held by the ObjectManager. Deallocations in the transaction will be returned to the allocator, rather than to the global reservation.

This must be used for transactions which will either not affect net space usage after compaction (e.g. setting attributes on an object), or will reduce space (e.g. unlinking a file or deleting a range of extents). By extension, this should not be used for transactions which include allocations.

When this is used appropriately, it is guaranteed that transactions will not fail due to lack of space.

When choosing between this and BorrowedMetadataAndData, the main consideration is whether the freed space from a deallocation must go back to the global reservation, or whether it can go back to the global pool. An example of where it must go back to the global reservation would be when purging a layer file during compaction; that space was borrowed from the metadata reservation, so it needs to go back there as well (and in that case BorrowedMetadataAndData should be used instead).

BorrowedMetadataAndData

Metadata space is borrowed directly from the global reservation held by the ObjectManager. Allocations and deallocations in the transaction will be from the global reservation as well.

This must be used for transactions that allocate or deallocate extents for internal filesystem metadata, such as journal and superblock growth, LSM tree compaction, and graveyard tombstoning of objects in the root and root-parent stores. These transactions will never fail due to running out of space (barring any bugs resulting in a deficit in the global reservation).

Hold(&'a Reservation)

Use the specified reservation for the transaction’s metadata (placing a hold on it) as well as any allocations or deallocations in the transaction.

Trait Implementations

impl<'a> Clone for ReservationOptions<'a>

fn clone(&self) -> ReservationOptions<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Copy for ReservationOptions<'a>

impl<'a> Default for ReservationOptions<'a>

fn default() -> ReservationOptions<'a>

Returns the “default value” for a type.