Skip to main content

StoreOptions

Struct StoreOptions 

Source
pub struct StoreOptions {
Show 22 fields pub trust: Trust, pub block_size: Option<u32>, pub log2_table_slot: u8, pub max_io: usize, pub buffers_per_class: u32, pub max_write: usize, pub large_buffers: u32, pub queues: usize, pub queue_depth: u32, pub t3_pool_threads: u32, pub append_window: u64, pub keyed_fill: bool, pub linux_tier: LinuxTier, pub register_file: bool, pub flushes_in_flight: u8, pub region_defaults: Option<RegionOptions>, pub background_io: u32, pub background_unpaced: u32, pub background_pacing: bool, pub commit_quiet: Duration, pub background_autotune: bool, pub background_depth_max: u32, /* private fields */
}
Expand description

Explicit, reported choices for a store. Every durability-affecting field appears in Store::report.

Fields§

§trust: Trust

Certificate, attestation and override inputs to the class decision.

§block_size: Option<u32>

Minimum block (slot) size in bytes; the device may require more.

§log2_table_slot: u8

Region-table slot size as a power of two (14 = 16 KiB: a format-2 table page of 169 regions; format 1’s single table, 253).

§max_io: usize

Largest single I/O of the blocking layers, and the batch buffer size (bytes; rounded up to a power of two, 128 KiB to 1 GiB).

§buffers_per_class: u32

Buffers per size class in the pool, up to max_io (at most 16,777,215; more fails create and open with NotWritten(PoolExhausted)).

§max_write: usize

Largest single write or read a Submitter takes, from one buffer, as one OS write or read operation (bytes; rounded up to a power of two, at most 1 GiB): the pool holds large_buffers buffers of that size, used by submitters only (D-101). Ignored when not above max_io.

§large_buffers: u32

Buffers of max_write bytes in the pool (0: none, so a submitter’s largest operation is max_io; at most 16,777,215). The defaults add 32 MiB on top of about 128 MiB of ordinary buffers per store: Windows charges the whole pool to the commit limit at creation; on both systems a buffer becomes resident when first used, and the most recently returned buffer of a size is reused first, so only about as many as are in use at once become resident. A pool too large to map fails create and open with NotWritten(PoolExhausted).

§queues: usize

Queues shared by the blocking layers (0 = number of CPUs). On Linux they perform their operations inline on either tier; the parallel lanes, as many again and created on first use, are io_uring rings on the io_uring tier, each holding two file descriptors (its ring and its eventfd), as does each Submitter.

§queue_depth: u32

Operations in flight per queue.

§t3_pool_threads: u32

Worker threads for the platform’s submit pool, which runs the independent operations of a page batch or a large read concurrently on the Linux synchronous tier (D-051, D-096); 0 = one per CPU, at most 32. The pool is shared by every store on the platform and sized by the first store that uses it (at most 256); other backends ignore this.

§append_window: u64

How far, in bytes, a new append may start ahead of the oldest incomplete one on the same region, in blocks: rounded down to a power of two, or, on a region that cannot grow past a size smaller than the window (format 1’s regions, a capped format-2 region), that size rounded up (so a region never limits its own appends); at least 2 and at most 2^20 blocks. Each append region that has appended since the open or its last recycle holds 8 bytes of memory per block of its ring: a format-2 region that may grow (no max_size) holds the window’s whatever its size, 32 KiB at the default 16 MiB and 4 KiB blocks (2 GiB for 65,536 such regions; a cap, or a smaller window, bounds it). Default 16 MiB.

§keyed_fill: bool

Fill new regions with the keyed incompressible pattern instead of zeros (for thin, virtual, deduplicating or zero-detecting stacks).

§linux_tier: LinuxTier

The kernel interface on Linux (D-082): Auto (io_uring where the kernel accepts it), Sync or Uring. Read by the native API when it makes the platform; the choice is in StoreReport::io. Other systems ignore it.

§register_file: bool

Register the store’s container file with each Submitter’s queue where the backend can (D-078, D-107: on Linux’s io_uring tier, a read-only twin of it as a direct descriptor on the submitter’s ring), so its reads skip the per-operation file lookup in the kernel; writes stay on the store’s own descriptor, so a write in flight keeps the store locked until it completes. Best effort: a registration the kernel refuses is counted in Store::io_path, never an error. On by default: the gates measured reads 1.03x to 1.08x of an unregistered ring (G3d, CI); writes take the unregistered path. Buffers are never registered: reads into registered buffers hang forever on some kernels (at least Linux 6.5.0 and 6.6.0), which no probe detects (D-107).

§flushes_in_flight: u8

Flushes the store runs at once (1 to 4; default 1, one in flight as before, D-124). Several can overlap, meant for drives that execute flushes in parallel (NVMe; not yet measured on one): each runs on a handle and queue of its own, so each reports its own failures, and a receipt still needs every flush up to its own to have succeeded. Platforms that cannot keep flush failures per handle run one (Linux 4.16 and later can); the number run is in StoreReport::flushes_in_flight. Measure on the target drive before raising it: at eight writers, 2 and 4 gained nothing on a memory-backed device and lost on a virtual disk (1,314, 974 and 595 durable writes a second at 1, 2 and 4).

§region_defaults: Option<RegionOptions>

The options the provision_{append,page}_region_default calls (of Store and Reservation) use (default none: those calls are refused). An open-time choice, never stored: each open may give others, and they apply to regions provisioned from then on (an existing region keeps its size and cap). Checked when used, so options a later call would refuse never fail an open.

§background_io: u32

Device pacing (PLANNING R5.4): background work (scans, copies, background Submitters; paced as each lands in v0.6) is split into pieces of this many bytes, whatever the device’s state, except a copy’s fill of its target, which keeps one piece in flight: while commits are quiet its pieces are background_unpaced of these, at most 1 MiB (as many bytes as a deeper call may then keep in flight; D-156). A multiple of 4096 from 4096 to 256 KiB (PERF-10’s piece); default 256 KiB. The store splits at the smaller of this and its largest I/O (max_io rounded up to a power of two, at least 128 KiB), rounded down to whole blocks, at least one; crate::QosReport::background_io says what it uses.

§background_unpaced: u32

Background pieces in flight per background call while the device’s commits are not active: 1 to 64; default 8. Stores of one device take the smallest.

§background_pacing: bool

Pace background work while the device’s commits are active (default true): one piece in flight per background call. Off for measurements such as G19’s negative control; stores of one device pace together if any of them asks for it.

§commit_quiet: Duration

How long after a commit the device’s commits count as active: at least 1 ms; default 5 s. Stores of one device take the largest.

§background_autotune: bool

Opt-in auto-tuning of the device’s background budget (PLANNING R5.4; default false). While commits are active, the pieces the device group admits beyond each background call’s own one follow windows of commit latency (200 commits, or 2 s with at least 50), each compared with a window run at the floor (1) in the same conditions, not with an idle figure: the budget rises by one after three windows within 1.25x of the latest floor window’s p99, halves at once on one over 1.4x, and every eighth window measures the floor again, up to background_depth_max. Its bound, documented and not gated: commits may run at up to 1.4x the floor’s own latency for as long as background work runs (the default, off, keeps the floor, which G19 gates within 2x of idle). On only if every store of the device asks for it. A device whose commits are only a power-safe store’s asynchronous Submitter writes is never sampled, so stays at the floor. crate::QosReport says what it does.

§background_depth_max: u32

Auto-tuning’s ceiling: the background pieces the device group may admit while commits are active (1 to 8; default 8), and never more than background_unpaced. Stores of one device take the smallest.

Trait Implementations§

Source§

impl Clone for StoreOptions

Source§

fn clone(&self) -> StoreOptions

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for StoreOptions

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Default for StoreOptions

Source§

fn default() -> StoreOptions

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.