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: TrustCertificate, 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: u8Region-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: usizeLargest 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: u32Buffers 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: usizeLargest 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: u32Buffers 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: usizeQueues 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: u32Operations in flight per queue.
t3_pool_threads: u32Worker 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: u64How 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: boolFill new regions with the keyed incompressible pattern instead of zeros (for thin, virtual, deduplicating or zero-detecting stacks).
linux_tier: LinuxTierThe 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: boolRegister 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: u8Flushes 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: u32Device 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: u32Background 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: boolPace 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: DurationHow 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: boolOpt-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: u32Auto-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
impl Clone for StoreOptions
Source§fn clone(&self) -> StoreOptions
fn clone(&self) -> StoreOptions
1.0.0 (const: unstable) · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source. Read more