Skip to main content

AppendError

Enum AppendError 

Source
#[non_exhaustive]
pub enum AppendError<E> { ConditionViolated(ConditionViolated), NoEvents, ExceedsStoreLimit { limit: StoreLimit, len: usize, }, Busy(E), Store(E), }
Expand description

Why an append failed.

The DCB concurrency signal is lifted out of the adapter’s error type and into this enum on purpose. Every store fails differently — disk full, socket closed, a lost acknowledgement — but every store fails identically when an append condition is violated, and callers must be able to distinguish “retry the decision” from “this went wrong” without pattern-matching on strings or knowing which adapter they were handed.

A busy refusal is lifted out for the same reason, into Busy. SQLITE_BUSY after a busy timeout and a PostgreSQL serialisation failure after an adapter’s own retry budget are different driver errors with one meaning — nothing was written, and the same decision may be taken again — and a generic caller that could only ask is_condition_violated could not see that meaning behind Store.

§Examples

match result {
    Ok(()) => {}
    // Expected under contention: rebuild the decision model and retry.
    Err(AppendError::ConditionViolated(_)) => { /* re-decide */ }
    // Transient, and nothing was written: deciding again is safe.
    Err(AppendError::Busy(_)) => { /* re-decide, within your own bound */ }
    // Everything else is a genuine failure.
    Err(other) => panic!("append failed: {other:?}"),
}

Note the catch-all arm: this enum is #[non_exhaustive], so matching every named variant is not enough and a wildcard is required.

Variants (Non-exhaustive)§

This enum is marked as non-exhaustive
Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.
§

ConditionViolated(ConditionViolated)

The store already contained an event matching the append condition.

§

NoEvents

The caller passed an empty batch.

The specification defines a batch as a non-empty collection of events, so there is no position an adapter could honestly return. This is a caller bug, not a store failure.

§

ExceedsStoreLimit

The batch exceeded a capacity the store documents.

Distinct from Store on purpose, and the distinction is the whole reason the variant exists: a caller that cannot tell “this will never fit here, park it and tell a human” from “the disk is full, retry” has to guess, and a sync runner that guesses wrong drops an event permanently.

A store MUST report a capacity refusal through this variant rather than through Store, and MUST NOT truncate instead.

Fields

§limit: StoreLimit

Which limit was exceeded.

§len: usize

The value that exceeded it — a byte count, a tag count or an event count, according to limit.

§

Busy(E)

The store refused the append for a transient reason, before the batch took any effect.

Nothing was written, and re-running the decision is safe. That sentence is the variant’s whole contract, and an adapter reporting it promises all three parts of it:

  • Before any effect. No event of the batch is in the store, and none will appear later. A position the store allocated and then abandoned may leave a gap, which the specification already permits.
  • Transient. The same call can succeed once whatever held the store has let go: a lock not acquired within the adapter’s own bound, or a serialisation failure its own retry budget did not absorb. A refusal that no retry can cure is Store.
  • Safe to re-run. Read again, decide again, and append under the new read’s condition, which is the loop a ConditionViolated already asks for. Because nothing landed, re-submitting the same batch under the same condition is safe too: the condition still guards it.

An ambiguous outcome MUST stay Store. A commit whose acknowledgement was lost, a connection that dropped after COMMIT was sent, a timeout whose effect is unknown: each may have written, so none may be reported here, however transient its cause looks. Busy is a claim about what the store holds, not about why the driver failed. A caller who re-runs an unconditional append on the strength of it would otherwise append twice. A store that cannot tell is not busy.

It is not the concurrency signal: is_condition_violated answers false, because no condition was evaluated. Nor is it a capacity refusal, which is ExceedsStoreLimit and will never fit. A store is never obliged to produce it: one that serialises its writers in-process, as MemoryEventStore does, has nothing to be busy with.

The payload is the adapter’s own error, carried for diagnostics exactly as Store carries it and reachable through source. Branch on the variant, never on the payload.

§

Store(E)

The adapter failed for its own reasons.

Including every outcome it cannot vouch for: an append reported here may or may not have landed. Busy is the refusal known to have written nothing.

Implementations§

Source§

impl<E> AppendError<E>

Source

pub const fn is_condition_violated(&self) -> bool

Whether this is the DCB concurrency signal rather than a store failure.

Source

pub const fn is_busy(&self) -> bool

Whether the store refused transiently, before writing anything.

true only for Busy. A caller that retries on this re-runs a decision that is known not to have landed. It is not the question is_condition_violated asks, and a loop that wants both asks both.

let busy: AppendError<std::io::Error> =
    AppendError::Busy(std::io::Error::other("database is locked"));
assert!(busy.is_busy());
assert!(!busy.is_condition_violated());

// A store failure is neither, whatever its message says.
let broken: AppendError<std::io::Error> =
    AppendError::Store(std::io::Error::other("database is locked"));
assert!(!broken.is_busy());
Source

pub fn map_store<F, T>(self, f: F) -> AppendError<T>
where F: FnOnce(E) -> T,

Maps the adapter-specific error wherever one is carried, in Store and in Busy, leaving every other variant untouched.

Useful when a higher layer wraps an adapter’s error in its own type. The variant survives the mapping: a busy refusal stays busy, because the classification is the store’s claim about what it holds, and a wrapper has no standing to change it.

let busy: AppendError<&str> = AppendError::Busy("database is locked");
let wrapped: AppendError<String> = busy.map_store(str::to_owned);
assert!(wrapped.is_busy());

Trait Implementations§

Source§

impl<E: Clone> Clone for AppendError<E>

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<E: Debug> Debug for AppendError<E>

Source§

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

Formats the value using the given formatter. Read more
Source§

impl<E> Display for AppendError<E>
where E: Display,

Source§

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

Formats the value using the given formatter. Read more
Source§

impl<E: Eq> Eq for AppendError<E>

Source§

impl<E> Error for AppendError<E>
where E: Error + 'static, Self: Debug + Display,

Source§

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any. Read more
1.0.0 · Source§

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

1.0.0 · Source§

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

Source§

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)
Provides type-based access to context intended for error reports. Read more
Source§

impl<E> From<ConditionViolated> for AppendError<E>

Source§

fn from(source: ConditionViolated) -> Self

Converts to this type from the input type.
Source§

impl<E: PartialEq> PartialEq for AppendError<E>

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl<E: PartialEq> StructuralPartialEq for AppendError<E>

Auto Trait Implementations§

§

impl<E> Freeze for AppendError<E>
where E: Freeze,

§

impl<E> RefUnwindSafe for AppendError<E>
where E: RefUnwindSafe,

§

impl<E> Send for AppendError<E>
where E: Send,

§

impl<E> Sync for AppendError<E>
where E: Sync,

§

impl<E> Unpin for AppendError<E>
where E: Unpin,

§

impl<E> UnsafeUnpin for AppendError<E>
where E: UnsafeUnpin,

§

impl<E> UnwindSafe for AppendError<E>
where E: 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> 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> ToString for T
where T: Display + ?Sized,

Source§

fn to_string(&self) -> String

Converts the given value to a String. 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.