Crdt.Io_intf

IO effect signatures for transport-agnostic operations

IO effect signatures for transport-agnostic network operations.

This module defines OCaml 5.4 effect signatures that allow the JSON-Rx protocol implementation to be independent of the underlying IO library (Eio, Lwt, Unix blocking, etc.).

Effect handlers can be implemented for different backends:

• Eio: Using Eio.Flow for high-performance async IO
• Lwt: Using Lwt promises for legacy async code
• Unix: Direct blocking IO for simple tools see https://v2.ocaml.org/manual/effects.html OCaml effects manual

Core IO Effects

type Effect.t += 
  | Read_bytes : int -> bytes Effect.t

Read a specified number of bytes from the current connection. Returns exactly the requested number of bytes, or raises End_of_file if the connection is closed before all bytes are available.

type Effect.t += 
  | Write_bytes : bytes -> unit Effect.t

Write bytes to the current connection. Blocks until all bytes are written or raises an exception on error.

type Effect.t += 
  | Read_byte : int Effect.t

Read a single byte from the current connection.

type Effect.t += 
  | Write_byte : int -> unit Effect.t

Write a single byte to the current connection.

type Effect.t += 
  | Yield : unit Effect.t

Yield control to the scheduler. For cooperative multitasking in async runtimes.

Connection Effects

type conn_id = int

Connection identifier type

type Effect.t += 
  | Accept : conn_id Effect.t

Accept a new connection on a listening socket. Returns a connection ID that can be used with read/write.

type Effect.t += 
  | Connect : (string * int) -> conn_id Effect.t

Connect to a remote address.

parameter host The hostname or IP address parameter port The port number Returns a connection ID.

type Effect.t += 
  | Close : conn_id -> unit Effect.t

Close a connection.

Framed Message Effects

Higher-level effects for working with length-prefixed messages.

type Effect.t += 
  | Read_frame : bytes Effect.t

Read a framed message (4-byte length prefix + payload). Returns the message payload without the length prefix.

type Effect.t += 
  | Write_frame : bytes -> unit Effect.t

Write a framed message (automatically adds 4-byte length prefix).

Timeout Effects

type 'a timeout_result = 
  | Completed of 'a
  | Timed_out

Timeout result type

type Effect.t += 
  | With_timeout : (float * (unit -> 'a)) -> 'a timeout_result Effect.t

Execute an operation with a timeout (in seconds).

Helper Functions

Convenience functions that use effects internally.

val read_string : int -> string

Read a string of specified length

val write_string : string -> unit

Write a string

val read_exactly : int -> string

Read exactly n bytes, returning a string

val read_int32_be : unit -> int

Read a 4-byte big-endian integer

val write_int32_be : int -> unit

Write a 4-byte big-endian integer

val read_framed_message : unit -> bytes

Read a framed message using low-level effects

val write_framed_message : bytes -> unit

Write a framed message using low-level effects

val yield : unit -> unit

Yield control to scheduler

Effect Handler Utilities

Helpers for implementing effect handlers.

type 'a io_result = 
  | Ok of 'a
  | Error of exn

Result type for effect handler operations

type connection_state = {
  id : conn_id;
  mutable closed : bool;
  mutable bytes_read : int;
  mutable bytes_written : int;
}

Connection state for handlers to track

val new_connection : conn_id -> connection_state

Create a new connection state

Mock Handler for Testing

A simple in-memory handler for unit tests.

module Mock : sig ... end