Struct DurableIoCore 

pub struct DurableIoCore<E, B, C, K>
where
    E: EpochId + 'static,
    K: StampClock,
{ /* private fields */ }

dioring’s core: every lineage’s durability, the targets it decides for, the operations in flight or held for their gates, and the queue of entries for the consumer (DI-D-49). E is the epoch-id type, B the backend’s owned buffer, C the consumer’s per-operation context, and K the clock failures are stamped with.

Implementations

impl<E, B, C, K> DurableIoCore<E, B, C, K>

where E: EpochId + 'static, K: StampClock,

pub fn resolve( &mut self, items: Vec<(FailureToken, Resolution)>, ) -> Result<CoreActions<DioringIds<E, <K as StampClock>::Instant>, B>, ResolveError<DioringIds<E, <K as StampClock>::Instant>>>

Resolve failures, validated whole and applied together: a refused call changes nothing and hands every token back.

Errors

ResolveError, naming why and handing back the tokens.

pub fn import_failure( &mut self, scope: ImportScope<DioringIds<E, <K as StampClock>::Instant>>, ) -> Result<(Imported<DioringIds<E, <K as StampClock>::Instant>>, CoreActions<DioringIds<E, <K as StampClock>::Instant>, B>), UnknownLineage<DioringIds<E, <K as StampClock>::Instant>>>

Record a failure the consumer learned of outside the instance (DI-D-12 (h)), reaching the uncovered writes scope names.

Errors

UnknownLineage for an ImportScope::Lineage that is not this core’s live one.

pub fn failures( &self, ) -> Vec<FailureInfo<DioringIds<E, <K as StampClock>::Instant>>>

The unresolved failures, in observation order.

pub fn take_token(&mut self, failure: FailureId) -> Option<FailureToken>

A new token for failure, if it is unresolved and its token was dropped.

impl<E, B, C, K> DurableIoCore<E, B, C, K>

where E: EpochId + 'static, K: StampClock,

pub fn mint_lineage(&mut self, description: Option<String>) -> Lineage

Mint a lineage, described by description.

pub fn lineages( &self, ) -> Vec<LineageInfo<DioringIds<E, <K as StampClock>::Instant>>>

The live lineages, in minting order, the default first.

pub fn end_lineage( &mut self, lineage: Lineage, ) -> Result<CoreActions<DioringIds<E, <K as StampClock>::Instant>, B>, EndLineageRefusal<DioringIds<E, <K as StampClock>::Instant>>>

End lineage (DI-D-30): every epoch of it not yet durable is abandoned, a LineageEnded entry reports it, and every operation held by a gate on one of its epochs, or a held write of its own, completes as NeverIssued.

Errors

EndLineageRefusal::Foreign for a lineage that is not this core’s live one, and EndLineageRefusal::Default for the default lineage.

pub fn retire_lineage( &mut self, lineage: Lineage, ) -> Result<(), RetireLineageRefusal<DioringIds<E, <K as StampClock>::Instant>>>

Retire lineage if nothing holds it, so it is no longer enumerated (DI-D-40).

Errors

RetireLineageRefusal::Foreign for a lineage that is not this core’s live one, RetireLineageRefusal::Default for the default lineage, and RetireLineageRefusal::Busy naming what still holds it.

impl<E, B, C, K> DurableIoCore<E, B, C, K>

where E: EpochId + 'static, K: StampClock,

pub fn with_provider( clock: K, diagnostics: Arc<dyn DiagnosticSink>, domains: Vec<FlushDomain>, ) -> Result<DurableIoCore<E, B, C, K>, DuplicateDomain>

A core whose consumer’s provider serves domains, read once, as new builds one otherwise. A target declaring a domain it serves has that domain’s part of each seal answered by the provider; every other domain, and every target declared with none, is the built-in default’s commit.

Errors

DuplicateDomain for a domain named twice.

pub fn provided( &mut self, lineage: Lineage, seal: u64, domain: &FlushDomain, outcome: DomainOutcome, ) -> CoreActions<DioringIds<E, <K as StampClock>::Instant>, B>

The provider answered domain of lineage’s seal seal, as a ProviderRequest named them. An answer for a lineage since ended reports nothing, as a late commit does (DI-D-42).

An answer naming another core’s lineage, a domain the provider does not serve, a seal or domain no request asked about, or a domain answered twice is the driver or the provider breaking the protocol, and is panicked on (DI-D-44, DI-D-46).

impl<E, B, C, K> DurableIoCore<E, B, C, K>

where E: EpochId + 'static, K: StampClock,

pub fn new( clock: K, diagnostics: Arc<dyn DiagnosticSink>, ) -> DurableIoCore<E, B, C, K>

A core with no targets, no provider, and only its default lineage, stamping failures with clock and reporting to diagnostics.

pub fn default_lineage(&self) -> Lineage

The default lineage, which every core has and which never ends.

pub fn add_target( &mut self, key: IoTargetKey, description: IoTargetDescription, ) -> Result<(), DuplicateTarget<IoTargetDescription>>

Decide for a target under key, as description states it. The driver attaches the target itself to the backend under the same key.

Errors

DuplicateTarget, handing the description back, if key is in use.

pub fn target(&self, key: IoTargetKey) -> Option<&IoTargetDescription>

The description of the target under key, if there is one.

pub fn remove_target( &mut self, key: IoTargetKey, ) -> Result<IoTargetDescription, RemoveTargetError<DioringIds<E, <K as StampClock>::Instant>>>

Stop deciding for the target under key, handing its description back, unless something still holds it (DI-D-45). The driver detaches the target from the backend once this succeeds.

Errors

RemoveTargetError::UnknownKey for no such target, and RemoveTargetError::Busy naming every hold at once: operations in flight, operations held for a gate, uncovered writes, and the failures suspecting writes to it.

pub fn write<Bk>( &mut self, target: IoTargetKey, offset: u64, data: SubmissionData<B>, epoch: Epoch<DioringIds<E, <K as StampClock>::Instant>>, context: C, options: WriteOptions<DioringIds<E, <K as StampClock>::Instant>>, backend: &mut Bk, ) -> Result<OpId, PushError<DioringIds<E, <K as StampClock>::Instant>, B, C>>

where Bk: IoBackend<Buffer = B>,

Write data to target at offset, tagged epoch: checked, then held for its gate, or pushed to backend as a submission and recorded once the push accepts it. The caller submits.

Errors

PushError, handing back the buffer (None for a registered region) and context: for an unknown target; an epoch whose lineage is not this core’s live one, at or below its seal point, or abandoned; a gate in another core, of a lineage not live, abandoned, or closing a cycle (DI-D-43) – checked in that order – or PushRefusal::Backend with the cause the backend gave: its check’s for a write the core would hold, its push’s for one pushed now.

pub fn read<Bk>( &mut self, target: IoTargetKey, offset: u64, data: SubmissionData<B>, context: C, options: ReadOptions<DioringIds<E, <K as StampClock>::Instant>>, backend: &mut Bk, ) -> Result<OpId, PushError<DioringIds<E, <K as StampClock>::Instant>, B, C>>

where Bk: IoBackend<Buffer = B>,

Read from target at offset into data: checked, then held for its gate, or pushed to backend and recorded once the push accepts it. The caller submits.

Errors

PushError, handing back the buffer and context: for an unknown target; a gate in another core, of a lineage not live, or abandoned; or PushRefusal::Backend with the cause the backend gave, as for write.

pub fn make_durable_through( &mut self, through: Epoch<DioringIds<E, <K as StampClock>::Instant>>, ) -> Result<(DurabilityRequest<DioringIds<E, <K as StampClock>::Instant>>, CoreActions<DioringIds<E, <K as StampClock>::Instant>, B>), SealError<DioringIds<E, <K as StampClock>::Instant>>>

Seal every epoch of through’s lineage at or below it (DI-D-9): the answer, and what it made due at once.

Errors

SealError::UnknownLineage for a lineage that is not this core’s live one, and SealError::GateCycle for a seal that would close a gate cycle (DI-D-43).

pub fn complete( &mut self, completion: Completion<B>, ) -> CoreActions<DioringIds<E, <K as StampClock>::Instant>, B>

Record a completion the backend reported: a consumer operation’s entry goes on the queue before anything it makes due, so a Durable it leads to follows it (guarantee 5).

A completion for no submission in flight – one never handed out, or completed twice – is the backend breaking its contract, and is panicked on (DI-D-46, DI-D-50 P9).

pub fn refused( &mut self, refused: Refused<B>, ) -> CoreActions<DioringIds<E, <K as StampClock>::Instant>, B>

Take back a submission the core originated that the backend refused (DI-D-54). For a retryable cause it is kept, and emitted again with the next actions or by retry; nothing is due. For any other it can never be issued, so it ends here, as a completion with a REFUSED fault would end it: an operation completes as Failed, a write nullified as one its target failed is, and a commit fails its seal’s flush of its target. What that makes due is returned.

A consumer operation the consumer’s push issued never comes back this way – its push is refused to the consumer – so one that does, or a submission never handed out, is panicked on (DI-D-46).

pub fn retry( &mut self, ) -> CoreActions<DioringIds<E, <K as StampClock>::Instant>, B>

The submissions refused before, to push again – once the driver has submitted or drained, as their causes said.

pub fn pop( &mut self, ) -> Option<Entry<DioringIds<E, <K as StampClock>::Instant>, B, C>>

The next entry, if there is one.

pub fn durable_through( &self, lineage: Lineage, ) -> Result<Option<E>, UnknownLineage<DioringIds<E, <K as StampClock>::Instant>>>

The lineage’s high-water mark: the highest epoch reported durable, or None if none is.

Errors

UnknownLineage for a lineage that is not this core’s live one.

pub fn sealed_through( &self, lineage: Lineage, ) -> Result<Option<E>, UnknownLineage<DioringIds<E, <K as StampClock>::Instant>>>

The lineage’s seal point: the highest epoch sealed, or None if none is.

Errors

UnknownLineage for a lineage that is not this core’s live one.

pub fn epoch_state( &self, epoch: Epoch<DioringIds<E, <K as StampClock>::Instant>>, ) -> Result<EpochState<DioringIds<E, <K as StampClock>::Instant>>, UnknownLineage<DioringIds<E, <K as StampClock>::Instant>>>

An epoch’s state.

Errors

UnknownLineage for a lineage that is not this core’s live one.

pub fn close(self) -> Leftovers<DioringIds<E, <K as StampClock>::Instant>, B, C>

End the core, handing back what it still holds: the operations held for their gates, which were never issued, in push order; the unresolved failures; and every lineage with its final high-water mark. What is in flight is the backend’s to run down.