Skip to main content

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.