Components
In Context-Generic Programming (CGP), a component is one trait, defined once, that a
context can wire to any of several implementations. The constructs on the other pages of this reference are the tools you use to build
your own components; the pages in this section document the components CGP already ships. Each is a
consumer trait you call, a provider trait an implementation targets, and a wiring key a context
delegates, exactly like a component you define yourself, so you wire a built-in error type or runtime
with the same delegate_components! table as everything else.
A context is the type a method runs on, which supplies whatever values an implementation needs as its own fields. You wire these components onto a context and call them the way you call any CGP trait. This page groups them by the job they do, in roughly the order most CGP code reaches for them. If you are new to CGP, start with the reference overview rather than here.
Handle errors
CGP keeps the error type abstract so that fallible generic code never names a concrete error, and three
components carry that. HasErrorType gives a context one shared abstract Error
type, chosen once at wiring time, so that every fallible operation refers to the same error and their
results compose. It is the component nearly every non-trivial program meets, and the two below build on
it.
CanRaiseError turns a concrete source error into that abstract error, so a
provider can call Context::raise_error(source) without knowing what the context's error type is.
CanWrapError attaches detail to an error the context already holds, such as a
message or a path, as it propagates. Both dispatch per source or detail type, and both are usually
satisfied by wiring one of the error providers or a standalone backend
crate rather than by hand.
Let each context choose a type
HasType is CGP's tag-indexed abstract type:
a trait whose associated type a context resolves, one tag at a time, to a concrete type through wiring.
CGP's other abstract types, such as HasErrorType and HasRuntimeType below,
are named components defined with #[cgp_type], and the same
UseType<T> marker supplies all of them. You reach for HasType directly
only rarely; a named #[cgp_type] component reads better.
Compute things
The handler family models a computation as a swappable component along three axes:
synchronous or async, fallible or not, and taking an input or not. It is a subsection of its own, with
one page per member. Computer is the pure synchronous transform that never
fails, TryComputer adds a failure path, and
Handler is the general corner, async and fallible, that generic pipeline code
targets because every simpler member promotes up to it. Producer is the
input-free case that yields a value from the context alone.
Each of Computer, TryComputer, and Handler also has by-reference and, for the computers, async
siblings, such as ComputerRef, AsyncComputer, and HandlerRef. Each differs from its base member by
one axis and has a page of its own in the subsection. Providers for the family are written from plain
functions with #[cgp_computer] and
#[cgp_producer], then composed with the
handler combinators.
Run tasks against a runtime
The last group executes work and supplies the runtime that work runs on. HasRuntime
hands out a borrow of the context's runtime value, and HasRuntimeType declares
the abstract runtime type it borrows, so a provider reaches a Tokio runtime, a mock, or a test executor
generically. CanRun runs a task named at the type level to a Result<(), Error>, and
CanSendRun is the variant whose returned future is Send, for work that must cross
a thread boundary.
An AI agent wrote this page using the CGP knowledge base. Its content was verified against the library's source. See How AI is used in this project.