effects

name	effects
description	OCaml 5 algebraic effects design patterns. Use when Claude needs to: (1) Design APIs that interact with effect-based schedulers, (2) Decide between effects vs exceptions, (3) Integrate libraries with Eio or affect, (4) Handle suspension vs error cases in streaming code, (5) Understand the layered effect design principle
license	ISC

OCaml 5 Effects Design

Core Principle

Effects for control flow, exceptions for errors.

Concern	Mechanism	Example
Suspension (wait for data)	Effects	perform Block, perform Yield
Error (EOF, malformed)	Exceptions	raise End_of_file, Invalid_argument

Layered Design

Effects should be handled at the source level, not in protocol parsers:

Application
    ↓
Protocol parser (Binary.Reader, Cbor, etc.)
    ↓  raises exceptions on EOF/error
bytesrw (effect-agnostic)
    ↓  just calls pull function
Source (Eio flow, affect fd, Unix fd)
    ↓  performs effects for suspension
Effect handler (Eio scheduler, affect runtime)

Why This Matters

• Parsers stay pure: No effect dependencies, easy to test
• Sources control blocking: Handler decides wait vs fail vs timeout
• Composability: Same parser works with any effect system

Effect Libraries