effects

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

Eio

Effects are internal to the scheduler. User code looks synchronous:

(* Reading blocks via internal effects *)
let data = Eio.Flow.read flow buf

affect

Explicit effects for fiber scheduling:

type _ Effect.t +=
| Block : 'a block -> 'a Effect.t   (* suspension *)
| Await : await -> unit Effect.t    (* wait on fibers *)
| Yield : unit Effect.t             (* cooperative yield *)

(* Block has callbacks for scheduler integration *)
type 'a block = {
  block : handle -> unit;      (* register blocked fiber *)
  cancel : handle -> bool;     (* handle cancellation *)
  return : handle -> 'a        (* extract result *)
}

bytesrw

Effect-agnostic streaming. The pull function you provide can perform any effects:

(* bytesrw just calls your function *)
let reader = Bytesrw.Bytes.Reader.make my_pull_fn

(* If my_pull_fn performs Eio effects, they propagate *)
(* If my_pull_fn performs affect Block, they propagate *)
(* bytesrw doesn't care - it just calls the function *)

Integration Pattern