Skip to main content

Store

Struct Store 

Source
pub struct Store<P: Platform> { /* private fields */ }
Expand description

A store: one container file on one device.

Implementations§

Source§

impl<P: Platform> Store<P>
where P::Queue: Send,

Source

pub fn create( platform: P, path: &Path, opts: StoreOptions, ) -> Result<Self, Error>

Creates a new store in path (the directory is created if missing).

The device is probed first; a durable open on an unsafe or unverified device is refused (and nothing is left behind) unless opts.trust attests or overrides it.

§Errors

Error::AlreadyExists if a store is already there; Error::Locked if another handle holds the new container’s lock; Error::UnsafeDevice / Error::Unverified on refusal; Error::Io / Error::DurabilityUnknown on platform failures (Io(Lock) on a file system that cannot lock).

Source§

impl<P: Platform> Store<P>
where P::Queue: Send,

Source

pub fn open(platform: P, path: &Path, opts: StoreOptions) -> Result<Self, Error>

Opens an existing store for reading and writing.

Takes the ownership lock, makes a dead owner’s completed writes durable (one full flush), reads the metadata, verifies every ready region, and bumps the owner generation. Modifies no caller bytes.

§Errors

Error::NotFound, Error::Locked (another handle, in this or another process, holds the store), refusal errors, Error::Corruption for unreadable or foreign metadata, Error::Unsupported (FormatVersion) for a newer format and for a format-1 store (read-only in 0.5: open it with Store::open_readonly, or copy it to format 2 with copy_store) before anything is written, Error::DurabilityUnknown when a dead owner’s writes may not be durable: the drain’s flush failed, or the probe did (on macOS its flush check is a flush; elsewhere it reads, and fails only on an I/O error), Error::Io (Io(Lock) on a file system that cannot lock).

Source

pub fn open_readonly( platform: P, path: &Path, opts: StoreOptions, ) -> Result<Self, Error>

Opens an existing store read-only: no write rights, nothing modified, no refusal on unsafe or unverified devices (reading is always allowed).

§Errors

As Store::open, without the refusal errors.

Source§

impl<P: Platform> Store<P>
where P::Queue: Send,

Region lookups and provisioning.

Source

pub fn append_region(&self, name: &str) -> Result<AppendRegion<P>, Error>

Looks up an existing append region.

§Errors

Error::NotFound if no ready append region has that name.

Source

pub fn provision_append_region( &self, name: &str, size: u64, ) -> Result<AppendRegion<P>, Error>

Provisions a new append region of at least size bytes.

§Errors

Error::AlreadyExists, Error::NoSpace, or a platform error.

Source

pub fn provision_append_region_with( &self, name: &str, opts: RegionOptions, ) -> Result<AppendRegion<P>, Error>

Provisions a new append region as opts say (its size, and in container format 2 its cap).

§Errors

As Self::provision_append_region; NotWritten(InvalidOptions) for options RegionOptions::validate refuses; Unsupported for a cap in container format 1.

Source

pub fn provision_append_region_default( &self, name: &str, ) -> Result<AppendRegion<P>, Error>

Provisions a new append region with the store’s StoreOptions::region_defaults.

let opts = StoreOptions {
    region_defaults: Some(RegionOptions::default().size(1 << 20)),
    ..StoreOptions::default()
};
let store = Store::create(SimPlatform::new(SimConfig::volatile(1)), Path::new("/db"), opts)?;
let log = store.provision_append_region_default("log")?;
assert_eq!(log.len(), 1 << 20);
§Errors

As Self::provision_append_region_with; NotWritten(InvalidOptions) when the store has no defaults (before any other refusal).

Source

pub fn provision_page_region_default( &self, name: &str, ) -> Result<PageRegion<P>, Error>

Provisions a new page region with the store’s StoreOptions::region_defaults.

§Errors

As Self::provision_append_region_default.

Source

pub fn page_region(&self, name: &str) -> Result<PageRegion<P>, Error>

Looks up an existing page region.

§Errors

Error::NotFound if no ready page region has that name.

Source

pub fn provision_page_region( &self, name: &str, size: u64, ) -> Result<PageRegion<P>, Error>

Provisions a new page region of at least size bytes.

§Errors

Error::AlreadyExists, Error::NoSpace, or a platform error.

Source

pub fn provision_page_region_with( &self, name: &str, opts: RegionOptions, ) -> Result<PageRegion<P>, Error>

Provisions a new page region as opts say (its size, and in container format 2 its cap).

§Errors

As Self::provision_append_region_with.

Source

pub fn slot(&self, name: &str) -> Result<Slot<P>, Error>

Looks up an existing small-object slot.

§Errors

Error::NotFound if no slot has that name.

Source

pub fn provision_slot(&self, name: &str) -> Result<Slot<P>, Error>

Provisions a new small-object slot. Its capacity is the block size minus 176 bytes of headers (Slot::capacity).

§Errors

Error::AlreadyExists, Error::NoSpace, or a platform error.

Source§

impl<P: Platform> Store<P>
where P::Queue: Send,

Source

pub fn repair_unavailable(&self, id: RegionId) -> Result<(), Error>

Releases the table entry of an unavailable region, one that Self::unavailable_regions lists (or, named by its id page << 32 | seq, an entry of a kind this version does not know, report().metadata.invalid_entries: given up deliberately). The entry’s page is written without it (durable on return); the region’s bytes are not touched, and its space becomes free where no other region’s footprint lies. Its name is free again; the repair is recorded (Self::repairs). Container format 2.

§Errors

NotFound(Region) if id names no unavailable entry (a usable region is released with release); NotWritten(Overlap), naming a region whose open-time verdict rests on this entry (spec §9 step 4: a live region it supersedes, which may read another’s bytes, or an unavailable one it demoted by an overlap or a name): the entry stays while that region does (repair a demoted one first; a superseded one is read-only and cannot be released: the way out is a copy of the store that leaves unavailable entries out, copy_store’s accept_stale_pages, v0.5 E6 C4); NotWritten(Frozen) also for a page holding an entry past its own write that would be kept (repair that one first, when it can be: one that supersedes a live region cannot, and two on one page block each other; the way out is then the copy); NotWritten(Frozen) while allocation is frozen (a table page is stale or lost: free space cannot be trusted); NotWritten(ReadOnly); Unsupported(FormatVersion) for format 1; Poisoned; DurabilityUnknown if the page write failed after submission (the store is then poisoned; the entry may or may not be gone at the next open).

Source

pub fn accept_page_rollback(&self, pages: &[u32]) -> Result<(), Error>

Accepts the rollback of stale table pages (spec §12): for each page of pages that is Unconfirmed (report().metadata.stale_pages), its winner is rewritten byte for byte into its failed slot (even an unreadable one: writing usually remaps the sector) at the next meta_seq, durably, and read back; once the new copy reads back as the winner the page counts as Confirmed: whatever its lost commits held is given up (space they used may be handed out again) and the extra extents counted allocated for it are free. Every page is checked before any is written (an error from a check accepts none). Each accepted page is recorded (Self::repairs); a Confirmed page is left as it is.

Once no page is stale or lost, allocation is no longer frozen (Self::frozen) and the regions become writable (not one possibly superseded, or with a header feature this version may not write). Not before: a region of an accepted page may be one a lost commit released, its space then given to a region of another stale page’s lost commit, whose bytes it would overwrite. The same holds across a reopen: an accepted page’s two slots then hold the same payload (as after a heal), and while any page is stale or lost the open keeps such a page’s regions read-only (also once its older copy is damaged: any Confirmed page with a damaged older copy counts). A store with a Lost page stays frozen, the regions of the pages accepted read-only: it is copied (copy_store). An accepted page’s next_seq counts higher (raised by the open that found it stale and by each open while its trace lasts, written by its next commit): the region ids its lost commit gave out are not given out again (unless more than 4,096 provisionings failed on that page between its last two commits). Container format 2.

§Errors

NotWritten(NotReady) for a Lost page, its slots named (no winner to keep); NotWritten(OutOfBounds) for a page the table does not have; NotWritten(Frozen) for a page holding an entry whose footprint_seq is past the page’s own write, the entry named (the rewrite would change how the next open counts it, and no repair runs while allocation is frozen: such a store is copied). Corruption(MediaError) if the page does not read back with both slots Valid and the same, and Io if it does not read: the write was durable, so the store is poisoned (what the next open finds is the page’s state: Confirmed if the new copy reads, else stale, to be accepted again). NotWritten(ReadOnly); Unsupported(FormatVersion) for format 1; Poisoned; DurabilityUnknown if the write failed after submission (the store poisoned; at the next open the page is still stale, or Confirmed if the new copy reached the media).

Source§

impl<P: Platform> Store<P>
where P::Queue: Send,

Source

pub fn extent_of(&self, data_size: u64) -> Option<u64>

Bytes a region of data_size data bytes occupies in the container: the data size rounded up to the block, plus two header blocks.

Source

pub fn set_cap(&self, tag: u32, cap: Option<u64>)

Sets (or with None removes) the hard cap of tag: the most bytes its regions and reservations may hold together. Caps live in memory; set them again after every open.

Source

pub fn reserve(&self, bytes: u64, tag: u32) -> Result<Reservation<P>, Error>

Reserves bytes for later provisioning under tag: checks the tag’s cap and grows the container so that provisioning from the reservation cannot run out of space.

§Errors

NoSpace { tag } if the cap or the file system is exceeded (nothing changes and nothing is poisoned); NotWritten(ReadOnly); Poisoned; Io for other allocation failures.

Source

pub fn space(&self) -> SpaceReport

Where space goes: the container, regions, released extents, reservations, and usage per tag.

Source§

impl<P: Platform> Store<P>
where P::Queue: Send,

Source

pub fn oldest_outstanding(&self) -> Option<Outstanding>

The oldest operation still in flight on the store’s queues (shared, parallel and flush) and its submitters, or None when they are all idle. O(queues + submitters), no I/O; reads the platform’s coarse clock once. A submitter’s operation counts until its completion is processed by reap or wait.

The age counts from the first call that saw the operation, so a watchdog calling this every second learns of a hung device within a second of its deadline.

Source§

impl<P: Platform> Store<P>
where P::Queue: Send,

Source

pub fn poisoned(&self) -> Option<FirstCause>

The failure that poisoned the store, if one has: every write and barrier fails with Poisoned from then on. A cheap check, for a health probe or a monitor.

Source

pub fn observe(&self) -> Snapshot

Event counters and sampled per-stage latencies since this handle was opened. With feature observe off (the default) nothing is recorded and the snapshot is all zeros.

Source

pub fn report(&self) -> &StoreReport

What the store learned about its device and what it decided, as the open found it (never changed after: what repairs change since is in Self::unavailable_regions, Self::frozen and Self::repairs).

Source

pub fn io_path(&self) -> IoPath

The kernel interface the store’s I/O uses now, and why: as StoreReport::io, with every queue made since counted (a ring the kernel refused for a Submitter or a parallel lane, and what served instead).

Source

pub fn volume(&self) -> VolumeId

The volume identity.

Source

pub fn poison(&self)

Poisons the device domain (for a caller’s watchdog that decided the device is hung). Every later write and barrier fails with Error::Poisoned; reads keep working.

Source

pub fn domain_stats(&self) -> DomainStats

Flush-sharing counters of the device domain.

Source

pub fn submit_pool_threads(&self) -> Option<usize>

Worker threads in the submit pool that runs this store’s page batches and large reads concurrently, once this store’s first such call has started its parallel queues (the pool may have been started earlier by another store on the same platform, and stays None if they could not be started); None before that, or on a backend that needs no pool (IOCP, the simulator).

Source

pub fn regions(&self) -> Vec<(String, RegionKind)>

Names and kinds of the ready regions.

Source

pub fn unavailable_regions(&self) -> Vec<UnavailableRegion>

Regions the region table names that open could not use, with the reason (D-090), less any repaired since. Empty for a healthy store. Their names stay reserved.

Source

pub fn frozen(&self) -> bool

Whether allocation is frozen now (format 2: a table page is stale or lost; spec §9 step 2): no provisioning, no growth beyond capacity, no release, no repair. report().metadata.frozen is what the open found.

Source

pub fn repairs(&self) -> Vec<Repair>

What this handle’s repairs and accepts did, in order (Self::repair_unavailable, Self::accept_page_rollback): the store’s log of them, for the caller to record. The library prints nothing.

Source§

impl<P: Platform> Store<P>
where P::Queue: Send,

Source

pub fn submitter(&self, cfg: SubmitterConfig) -> Result<Submitter<P>, Error>

A Submitter for this thread, with its own queue of cfg.depth operations (1 to MAX_DEPTH).

§Errors

Io if the platform could not create the queue.

Trait Implementations§

Source§

impl<P: Platform> Clone for Store<P>

Source§

fn clone(&self) -> Self

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<P: Platform> Debug for Store<P>

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<P> !RefUnwindSafe for Store<P>

§

impl<P> !UnwindSafe for Store<P>

§

impl<P> Forget for Store<P>

§

impl<P> Freeze for Store<P>
where Arc<Inner<P>>: Freeze,

§

impl<P> Move for Store<P>

§

impl<P> Send for Store<P>
where Arc<Inner<P>>: Send,

§

impl<P> Sync for Store<P>
where Arc<Inner<P>>: Sync,

§

impl<P> Unpin for Store<P>
where Arc<Inner<P>>: Unpin,

§

impl<P> UnsafeUnpin for Store<P>
where Arc<Inner<P>>: UnsafeUnpin,

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.