pub struct StoreOptions {Show 16 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>,
/* 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.