Module task 

Background work whose panic comes back as a TaskFailed (api.md E15). Work run apart from its caller — on the blocking pool, as its own task, or as one message of a long-lived loop — whose panic comes back to that caller as a value instead of an unwind (api.md E15).

A panic turned into an Err at the nearest join lets the caller’s own failure path run: the rollback or cleanup it does on Err, which an unwind would skip. The caller reports the panic as a bug. Work nobody waits for, a long-lived worker or work its caller stopped waiting for, reports its panic to a BugSink instead, the app’s own reporter.

Structs

Bug

Work that panicked: a bug in it, not a failure its caller can act on (E15). The caller reports it wherever it reports its own bugs, and the call that ran the work returns it as its error.

CompletingTask

The result of work spawn_completing or blocking_completing runs. Dropping it leaves the work running, and the work’s panic, or a bug its error carries, goes to the sink: once the work ends, or as it drops, for an answer the work gave that no one read.

HeardBugs

Keeps every bug it hears of, and logs each at error, as an app’s crash reporter would: the sink a test gives coven. A test that expects a bug takes it; one left untaken when the sink drops fails the test, so a bug no test expected never passes unseen.

LoggedBugs

Logs each bug at error: the sink of an app that wants its bugs only logged.

OwnedTask

A task spawn_owned started. Dropping it leaves the task running.

Shutdown

Work its runtime dropped as it shut down, before the work finished. Not a bug: the process is ending the work. The caller gets it as a value and returns it as its own error (E15).

SourceLocation

Where in the code a bug showed itself: the file, line and column of the panic, or of the code that found the bug and made it.

Enums

BugKind

How a bug showed itself (E15).

ShutdownOutcome

How far work its runtime dropped got (E15).

TaskFailed

Why work apart from its caller gave no result.

Traits

BugSink

Where a bug in work nobody waits for goes (E15): a store’s long-lived workers, such as its sync loop and upload worker, and work whose caller stopped waiting for it. The app passes its own crash reporter to Coven::new.

CarriesBug

An error that may carry a bug: work its call ran panicked, and the call’s error says so (E15). Work nobody waits for reports the bug its error carries, as it reports its own panic.

Functions

blocking

Run work on the blocking pool. A panic in it, or the runtime dropping it unstarted (ShutdownOutcome::NotRun), comes back as TaskFailed, never as an unwind.

blocking_completing

Run work, named operation, on the blocking pool, where it runs to its end even when its caller stops waiting. Its panic comes back as TaskFailed::Panicked to a caller still waiting, and the pool dropping it unstarted as Shutdown with ShutdownOutcome::NotRun. Once no caller waits, the panic goes to bugs, as does a bug its error carries.

catching_operation

The operation of the innermost catch of coven’s running on this thread, or None outside every one: for the app’s own panic hook, to say what the panicking work was doing. A panic a catch inside that work handles itself, such as a task tokio runs on this thread and catches, still names it. It never panics, so a hook can call it: a panic inside a hook ends the process.

caught

Run work inline, catching a panic in any of its polls. For one message of a long-lived loop: the panic fails that message and the loop serves the next. Run inline, the work can’t be dropped by its runtime, so a panic is its only failure.

caught_sync

caught for a synchronous call: an FFI callback, a dedicated thread’s body, a Drop. Unwinding out of an extern "C" function aborts the process, so such a function catches here and answers with its own failure value.

joined

Wait for a task whose work runs under caught, as tokio::spawn(caught(operation, work)) starts it. Its panic comes back as TaskFailed::Panicked, naming where it began; the runtime cancelling it, as Shutdown.

panic_message

The text a panic carried: what panic! and expect were given, or a placeholder for a payload that is not text.

report

Hand bug to bugs. A sink that panics too is logged, and its panic goes no further: it runs where nothing above it catches.

report_carried

Hand the bug error carries, if it carries one, to bugs: the error of work nobody waits for, which no caller hears of. Whether it carried one, so the work logs an error that carried none.

reported

error, once the bug it carries, if any, has gone to bugs: the error of work nobody waits for, which it records where readers see it.

spawn_completing

Run work, named operation, as its own task, so it finishes even when its caller stops waiting, as closing a store does. Its panic comes back as TaskFailed::Panicked to a caller still waiting. Once none is, the panic goes to bugs, as does a bug its error carries.

spawn_owned

Run work, named operation, as its own task that nobody waits for: a worker its owner stops. A panic in it goes to bugs, then ended runs, so the owner ends what the work served in a way its readers see, such as recording that sync failed. A panic in ended goes to bugs too, and no further.

Type Aliases

BugSinkRef

A shared BugSink.