Skip to main content

Spooler

Struct Spooler 

Source
pub struct Spooler<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> { /* private fields */ }
Expand description

Copies a log onto a removable volume, and remembers how far it got.

The spooler owns the volume and borrows the source on each pass, which matches the physical situation: the card comes and goes, the spooler is the long-lived thing.

§What it guarantees

  • No loss. The source’s replication watermark advances only after the replica’s copy is durable, so an interruption anywhere re-copies rather than skips.
  • Bounded duplication. A power cut or an unclean removal replays at most the batch that was in flight — SpoolBudget::max_entries entries.
  • In practice, none. attach reads the replica to find how much of an interrupted batch it kept, and reconcile skips exactly that much on the source. The bound above is what remains when the two sides cannot be made to agree.
  • Nothing is written to a foreign volume. A medium belonging to a different log is rejected at attach.

§RAM

One page buffer for cursor records, plus about 64 bytes of state.

Implementations§

Source§

impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Spooler<C, PAGE_SIZE, MAX_SECTORS>

Inspection that needs no flash access, and therefore no trait bounds.

Source

pub fn is_attached(&self) -> bool

Whether a volume is attached, faulted or not.

Source

pub fn is_faulted(&self) -> bool

Whether the attached volume has faulted and needs detaching.

Source

pub fn resume_point(&self) -> Option<LogPosition>

Source position replication will resume from, if a volume is attached.

Source

pub fn source_log(&self) -> Option<LogId>

Identity of the log this spooler replicates.

Source

pub fn region(&self) -> CursorRegion

Layout of the cursor region on the volume.

Source

pub fn pending_reconciliation(&self) -> u32

Entries of an interrupted batch that the replica already holds and the next pass will skip rather than copy again.

Non-zero only between an attach that found an unfinished batch and the reconcile or spool that applies the skip.

Source§

impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Spooler<C, PAGE_SIZE, MAX_SECTORS>

Source

pub fn new( source_log: Option<LogId>, cursor_base: u32, sector_size: u32, ) -> Result<Self, Error>

Create a spooler for a log with the given identity.

cursor_base is a byte offset on the volume, and the region it names must lie outside the volume’s database region — the cursor is metadata about the copy, not part of the copied log.

That is checked, not merely documented: every cursor access goes through SensorDb::with_region, so a region that intersects the volume’s sectors fails attach with Error::RegionOverlap instead of overwriting replicated entries. The check lands at attach rather than here because a spooler does not know the volume’s geometry until one is attached.

§Arguments
  • source_log: identity of the log being replicated. A volume carrying cursor records for a different log is rejected at attach.
  • cursor_base: start of the two-sector cursor region on the volume
  • sector_size: the volume’s erase size
§Errors
  • InvalidConfig if the geometry cannot hold cursor records
  • Overflow if the region runs past the end of the address space
Source

pub fn attach( &mut self, volume: SensorDb<C, PAGE_SIZE, MAX_SECTORS>, ) -> Result<Attached, Error>

Attach a mounted volume and read its cursor.

The application mounts the volume itself, because only it knows whether the volume should be indexed for reads (MountMode).

§Reconciling an interrupted batch

When the newest cursor record is an intent with no commit, the batch it describes was cut short somewhere — but the replica itself knows exactly how far it got. The intent names the replica position its first entry landed at, so reading the replica forward from there counts what survived. That count is remembered and skipped on the source side by reconcile, which the next spool pass calls if the application has not.

This is what makes reinsertion exactly-once rather than at-least-once. It degrades to the old bounded-duplicate behaviour when the count cannot be trusted — see Attached::recovered_entries.

§Errors
  • AlreadyAttached if a volume is already attached
  • NotMounted if the volume has not been mounted
  • ForeignVolume if its cursor belongs to a different log
Source

pub fn reconcile<S, const SP: usize, const SS: usize>( &mut self, source: &mut SensorDb<S, SP, SS>, ) -> Result<u32, Error>

Skip the part of an interrupted batch the replica already holds.

Reads the source forward over exactly the entries attach found durable on the replica and advances the resume point past them, so the next pass copies only the remainder. Without this the whole batch replays and the replica ends up holding duplicates — bounded by SpoolBudget::max_entries, but real.

Idempotent and cheap: a no-op unless an attach found an unfinished batch, and the next spool calls it anyway. Call it directly only to see the reconciled resume point before spooling — as TieredDb::attach does, so the watermark it restores is exact.

The skip is abandoned, leaving the batch to replay whole, whenever the two sides do not agree:

  • the source ring has wrapped past the resume point, so the entries the replica holds are gone and skipping the same count from the new tail would step over entries that were never copied;
  • the source run does not fingerprint the same as the replica’s copy of it.

Both fall back to duplicating, never to skipping. Duplication is bounded and visible; a wrong skip is silent loss.

§Returns

The number of entries skipped.

Source

pub fn fault(&mut self) -> Option<&mut SensorDb<C, PAGE_SIZE, MAX_SECTORS>>

Mark the attached volume faulted and borrow it.

Returns the volume so the caller can still reach data held in its RAM page buffer — which survives the medium being physically pulled, because the processor is still running. Returns None when nothing is attached.

Source

pub fn detach(&mut self) -> Option<SensorDb<C, PAGE_SIZE, MAX_SECTORS>>

Detach the volume, returning it to the application.

Also clears a fault, so a volume that errored can be re-attached after the application has decided what to do about it.

Source

pub fn volume(&self) -> Option<&SensorDb<C, PAGE_SIZE, MAX_SECTORS>>

The attached volume, if it is usable.

Source

pub fn volume_mut(&mut self) -> Option<&mut SensorDb<C, PAGE_SIZE, MAX_SECTORS>>

The attached volume, if it is usable.

Source

pub fn volume_fill(&self) -> Option<VolumeFill>

How much room is left on the attached volume.

None when nothing is attached. A faulted volume still answers, from the index it had when it faulted: how full the medium was at the moment it went is exactly what an operator wants to know afterwards.

Source

pub fn spool<S, const SP: usize, const SS: usize>( &mut self, source: &mut SensorDb<S, SP, SS>, budget: SpoolBudget, ) -> Result<SpoolProgress, Error>

Copy up to budget.max_entries durable source entries onto the volume.

A batch never spans two source sectors, so each cursor record names exactly one source epoch. That usually costs nothing — a sector holds far more entries than a typical budget — and it is what lets a reader attribute copied entries to a particular run of the source device.

Only entries that are already durable on the source are copied. Call SensorDb::sync on the source first to include its buffered tail.

§Errors
  • NotAttached if no volume is attached
  • VolumeLost if the volume errored; detach and re-attach to recover
  • GeometryMismatch if the volume’s pages are smaller than the source’s
Source

pub fn spool_until_caught_up<S, const SP: usize, const SS: usize>( &mut self, source: &mut SensorDb<S, SP, SS>, budget: SpoolBudget, max_batches: u32, ) -> Result<SpoolProgress, Error>

Copy until the replica is level with the source, or max_batches passes have run.

The bound exists so a caller with a large backlog can still service other work between calls rather than blocking indefinitely.

Source§

impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Spooler<C, PAGE_SIZE, MAX_SECTORS>

Source

pub fn spool_if_present<S, const SP: usize, const SS: usize>( &mut self, source: &mut SensorDb<S, SP, SS>, budget: SpoolBudget, ) -> Result<Option<SpoolProgress>, Error>

Like spool, but skip the pass when the driver reports the medium absent.

Available only when the volume’s driver can answer that question. It lets a clean removal be noticed before a write fails, which keeps a genuine fault distinguishable from a yank.

Returns Ok(None) when the medium is absent.

Source

pub fn is_present(&mut self) -> bool

Whether the driver reports the attached medium as present.

false when nothing is attached.

Auto Trait Implementations§

§

impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Freeze for Spooler<C, PAGE_SIZE, MAX_SECTORS>
where Slot<C, PAGE_SIZE, MAX_SECTORS>: Freeze, [u8; PAGE_SIZE]: Freeze,

§

impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> RefUnwindSafe for Spooler<C, PAGE_SIZE, MAX_SECTORS>
where Slot<C, PAGE_SIZE, MAX_SECTORS>: RefUnwindSafe, [u8; PAGE_SIZE]: RefUnwindSafe,

§

impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Send for Spooler<C, PAGE_SIZE, MAX_SECTORS>
where Slot<C, PAGE_SIZE, MAX_SECTORS>: Send, [u8; PAGE_SIZE]: Send,

§

impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Sync for Spooler<C, PAGE_SIZE, MAX_SECTORS>
where Slot<C, PAGE_SIZE, MAX_SECTORS>: Sync, [u8; PAGE_SIZE]: Sync,

§

impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Unpin for Spooler<C, PAGE_SIZE, MAX_SECTORS>
where Slot<C, PAGE_SIZE, MAX_SECTORS>: Unpin, [u8; PAGE_SIZE]: Unpin,

§

impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> UnsafeUnpin for Spooler<C, PAGE_SIZE, MAX_SECTORS>
where Slot<C, PAGE_SIZE, MAX_SECTORS>: UnsafeUnpin, [u8; PAGE_SIZE]: UnsafeUnpin,

§

impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> UnwindSafe for Spooler<C, PAGE_SIZE, MAX_SECTORS>
where Slot<C, PAGE_SIZE, MAX_SECTORS>: UnwindSafe, [u8; PAGE_SIZE]: UnwindSafe,

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> 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, 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.