Module effects 

Support for routing effects to explicit, type-based handlers.

This module enables an advanced use-case, where some effects are not handled by the shell using the standard serialization-based FFI interface. Instead the core FFI can be extended with core-side effect processing or custom effect handling FFI APIs, handling the operations and outputs using a different data exchange method (e.g. raw pointers, zero-copy formats like Cap’n Proto, etc.)

Overview

The entry point is the EffectRouter, which wraps a Core and a routing closure. The closure inspects each Effect the app emits and dispatches it to the appropriate handler, or “lane”. Crucially, the follow-up effects produced when a request is resolved are routed back through the same closure, so the same policy applies for the whole lifetime of a chain of effects.

The available lanes live in the routes module:

• Serialized keeps the standard, bridge-like behaviour: effects are serialized to bytes, sent to the shell, and resolved by id with serialized responses. This is the default lane and the primary onboarding path; it typically acts as the fall-through arm of the routing closure.
• Parked supports payloads and results that are awkward or undesirable to serialize (for example opaque pointer-style handles), using a custom, user-owned FFI. The request is parked under an EffectId which the shell passes back when resolving.
• Buffer collects requests for the caller to drain and handle synchronously, which is useful in tests and simple in-process handlers.

Effects can also be handled entirely inside the core by a Rust handler (including async or background work) that resolves requests back through the router via the ResolveSink trait.

Wiring it up

Routes are grouped in a user-defined type that implements Routes. The router is created with EffectRouter::new, which hands the constructed route set to a builder closure so it can be captured by the routing closure. Because routes need to resolve effects back through the router, they hold a Weak reference to it, and the router is therefore stored behind an Arc.

See the effect_router_prototype integration test in crux_core for a complete, worked example, and docs/src/rfcs/effect-router.md for the design rationale.

Modules

routes

The effect handling “lanes” an EffectRouter can dispatch to.

Structs

EffectId

Opaque ID for a parked effect request.

EffectRouter

Wraps a Core and routes each emitted effect to a type-specific handler.

Traits

ResolveSink

Lets a core-local handler resolve a Request back through the router.

Routes

A set of effect handlers (“routes”) owned by an EffectRouter.