Reference

< How It Works | Up: Internals | Index | Performance Investigation >

Quick-reference material for Skuld. For narrative explanations, start with Why Effects? or Getting Started.

Glossary

Computation - A function (env, k) -> {result, env} that describes an effectful program. Computations are inert until run - they don't execute side effects when constructed, only when a handler interprets them. Created with comp do ... end, Comp.pure/1, or effect operations like State.get().

Effect - A named capability that a computation can request. Effects are defined by modules (e.g., Skuld.Effects.State) and identified by signatures. An effect operation returns a computation that, when executed, looks up the appropriate handler and delegates to it.

Handler - A function that interprets effect requests. Handlers are installed in the environment and looked up by effect signature. The same computation can run with different handlers for different behaviour (production vs test, real IO vs in-memory).

Evidence - The map of effect signatures to handler functions carried in the environment. "Evidence-passing" means handlers are threaded through computations as data, enabling O(1) lookup.

Continuation (k) - A function representing "what happens next" after an effect operation completes. Normal effects call k once. Throw discards k. Yield captures k for later resumption.

Bind (<-) - Sequences two computations. x <- comp runs comp, extracts the result into x, then continues with the rest. Desugars to Comp.bind/2.

Sentinel - A special return value (%Throw{}, %Suspend{}) that signals abnormal completion. The ISentinel protocol determines how each is finalised by Comp.run/1.

Suspend - A sentinel indicating the computation has paused (via Yield.yield/1). Contains a resume function to continue execution and optionally data decorated by handlers (e.g., EffectLogger state).

Scope - A handler installation boundary. Scoped handlers (Comp.scoped/2) guarantee cleanup runs in reverse installation order, whether the computation completes normally, throws, or suspends.

leave_scope - A composed cleanup chain in the environment. Each scoped handler adds its cleanup function, chaining to the previous one. Invoked on normal completion (via ISentinel) and on Throw (via leave_scope unwinding). Not invoked on Suspend (deferred until resume).

transform_suspend - A composed decoration chain in the environment. When a computation suspends, this function decorates the Suspend struct (e.g., attaching handler state for serialisation).

Auto-lifting - Plain values in comp blocks are automatically wrapped in Comp.pure/1. The final expression, bare if without else, and similar cases are lifted so you don't need explicit return calls.

Effect quick-reference

Foundational effects

State & Environment

Error Handling & Resources

Value Generation

Collections

Concurrency

Persistence & Data

External Integration

Advanced effects

Coroutines

Cooperative Fibers

Query Batching

Serializable Coroutines

Handler installation via catch clause

Effects that implement IInstall can be installed directly in comp blocks using the catch clause:

comp do
  x <- State.get()
  config <- Reader.ask()
  {x, config}
catch
  State -> 0                    # State.__handle__(comp, 0)
  Reader -> %{timeout: 5000}   # Reader.__handle__(comp, config)
end

The config value (right side of ->) is passed to the module's __handle__/2 function. First clause becomes innermost handler, last clause outermost.

Effects that implement IIntercept can be intercepted with tagged patterns:

comp do
  result <- risky_computation()
  result
catch
  {Throw, :not_found} -> :default_value
  {Yield, :checkpoint} -> :resume_value
end

Both forms can be mixed in a single catch block.

The output option

Most stateful handlers accept an output option that transforms the result when the computation completes:

# Without output: result is just the computation's return value
State.with_handler(comp, 0)

# With output: result includes final state
State.with_handler(comp, 0, output: fn result, state -> {result, state} end)

Common patterns:

Running computations

Comparison with alternatives

vs Freyja (Freer monads)

Skuld is simpler (one type, one macro) and faster (~4x). Freyja's dual type system made higher-order effects awkward.

vs Mox/Mimic (test doubles)

For simple cases (1-3 external calls), Mox and Skuld are comparable. Skuld's advantage appears with stateful call chains (reads-after-writes), deep orchestration (10+ calls), and property tests — where reusable in-memory handlers replace ad-hoc per-test stubs. See Mox vs Skuld for a detailed comparison.

vs GenStage/Flow (streaming)

Brook is lighter-weight for cases where you want streaming with full effect support. GenStage is better for long-running production pipelines that benefit from process isolation.

vs Temporal.io (durable workflows)

EffectLogger is much lighter than Temporal but has narrower scope. It's suitable for durable conversations, multi-step wizards, and workflows that need to survive process restarts. It's not a distributed workflow orchestrator.

vs Haskell effect systems (Polysemy, Effectful, etc.)

Skuld takes the evidence-passing approach from Xie & Leijen (2021) and adapts it for a dynamic language. The single computation type with auto-lifting is what makes it practical without a type system - there's no Eff '[State, Reader, Throw] a to track.

Documentation map

< How It Works | Up: Internals | Index | Performance Investigation >