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_entriesentries. - In practice, none.
attachreads the replica to find how much of an interrupted batch it kept, andreconcileskips 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.
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.
Sourcepub fn is_attached(&self) -> bool
pub fn is_attached(&self) -> bool
Whether a volume is attached, faulted or not.
Sourcepub fn is_faulted(&self) -> bool
pub fn is_faulted(&self) -> bool
Whether the attached volume has faulted and needs detaching.
Sourcepub fn resume_point(&self) -> Option<LogPosition>
pub fn resume_point(&self) -> Option<LogPosition>
Source position replication will resume from, if a volume is attached.
Sourcepub fn source_log(&self) -> Option<LogId>
pub fn source_log(&self) -> Option<LogId>
Identity of the log this spooler replicates.
Sourcepub fn region(&self) -> CursorRegion
pub fn region(&self) -> CursorRegion
Layout of the cursor region on the volume.
Source§impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Spooler<C, PAGE_SIZE, MAX_SECTORS>where
C: NorFlash + ReadNorFlash,
impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Spooler<C, PAGE_SIZE, MAX_SECTORS>where
C: NorFlash + ReadNorFlash,
Sourcepub fn new(
source_log: Option<LogId>,
cursor_base: u32,
sector_size: u32,
) -> Result<Self, Error>
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 atattach.cursor_base: start of the two-sector cursor region on the volumesector_size: the volume’s erase size
§Errors
InvalidConfigif the geometry cannot hold cursor recordsOverflowif the region runs past the end of the address space
Sourcepub fn attach(
&mut self,
volume: SensorDb<C, PAGE_SIZE, MAX_SECTORS>,
) -> Result<Attached, Error>
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
AlreadyAttachedif a volume is already attachedNotMountedif the volume has not been mountedForeignVolumeif its cursor belongs to a different log
Sourcepub fn reconcile<S, const SP: usize, const SS: usize>(
&mut self,
source: &mut SensorDb<S, SP, SS>,
) -> Result<u32, Error>where
S: NorFlash + ReadNorFlash,
pub fn reconcile<S, const SP: usize, const SS: usize>(
&mut self,
source: &mut SensorDb<S, SP, SS>,
) -> Result<u32, Error>where
S: NorFlash + ReadNorFlash,
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.
Sourcepub fn fault(&mut self) -> Option<&mut SensorDb<C, PAGE_SIZE, MAX_SECTORS>>
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.
Sourcepub fn detach(&mut self) -> Option<SensorDb<C, PAGE_SIZE, MAX_SECTORS>>
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.
Sourcepub fn volume(&self) -> Option<&SensorDb<C, PAGE_SIZE, MAX_SECTORS>>
pub fn volume(&self) -> Option<&SensorDb<C, PAGE_SIZE, MAX_SECTORS>>
The attached volume, if it is usable.
Sourcepub fn volume_mut(&mut self) -> Option<&mut SensorDb<C, PAGE_SIZE, MAX_SECTORS>>
pub fn volume_mut(&mut self) -> Option<&mut SensorDb<C, PAGE_SIZE, MAX_SECTORS>>
The attached volume, if it is usable.
Sourcepub fn volume_fill(&self) -> Option<VolumeFill>
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.
Sourcepub fn spool<S, const SP: usize, const SS: usize>(
&mut self,
source: &mut SensorDb<S, SP, SS>,
budget: SpoolBudget,
) -> Result<SpoolProgress, Error>where
S: NorFlash + ReadNorFlash,
pub fn spool<S, const SP: usize, const SS: usize>(
&mut self,
source: &mut SensorDb<S, SP, SS>,
budget: SpoolBudget,
) -> Result<SpoolProgress, Error>where
S: NorFlash + ReadNorFlash,
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
NotAttachedif no volume is attachedVolumeLostif the volume errored; detach and re-attach to recoverGeometryMismatchif the volume’s pages are smaller than the source’s
Sourcepub 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>where
S: NorFlash + ReadNorFlash,
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>where
S: NorFlash + ReadNorFlash,
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>
impl<C, const PAGE_SIZE: usize, const MAX_SECTORS: usize> Spooler<C, PAGE_SIZE, MAX_SECTORS>
Sourcepub 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>where
S: NorFlash + ReadNorFlash,
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>where
S: NorFlash + ReadNorFlash,
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.
Sourcepub fn is_present(&mut self) -> bool
pub fn is_present(&mut self) -> bool
Whether the driver reports the attached medium as present.
false when nothing is attached.