Module Miou_state

type ('a, 'b) continuation

The type of continuations. ('a, 'b) continuation is the state of a function _ -> 'b. 'a is the type of the value to continue the continuation. The user can also discontinue with an exception the continuation.

type error = exn * Stdlib.Printexc.raw_backtrace

The type of errors. A continuation can raise or be cancelled by an exception. We keep the backtrace (where the exception comes from) with the exception raised/used.

type 'a t = private
  1. | Finished of ('a, error) Stdlib.result
  2. | Suspended : ('a, 'b) continuation * 'a Stdlib.Effect.t -> 'b t
  3. | Unhandled : ('a, 'b) continuation * 'a -> 'b t

The type of function states.

The state of a function is its execution state. A function can finish with its return value or an exception, or it can suspend on an Effect.t. In the case of a suspension, the user can "continue" the execution via what is expected by the associated effect. Note that once can only be used once on a given value t (otherwise, an exception Continuation_already_resumed is raised by OCaml).

val pp : 'a t Miou_fmt.t
module Operation : sig ... end
type ('a, 'b) handler = ('a Operation.t -> 'b t) -> 'a Stdlib.Effect.t -> 'b t
type perform = {
  1. perform : 'a 'b. ('a, 'b) handler;
}

Type of the effect handler.

perform is a function which should handle incoming effects and give an operation Operation.t via the given continuation k.

val make : ('a -> 'b) -> 'a -> 'b t

make fn value makes a new function state by executing the function with the given argument.

val suspended_with : ('c, 'a) continuation -> 'c Stdlib.Effect.t -> 'a t

suspended_with k eff allows you to create a state from the given suspension k and the effect eff which produced the given suspension. This function does not continue the given k, it is safe to use it even if the user resumed k elsewhere.

val once : perform:perform -> 'a t -> 'a t

once ~perform state applies perform once on the given state if the latter emits an effect.

val fail : backtrace:Stdlib.Printexc.raw_backtrace -> exn:exn -> 'a t -> 'a t

fail ~exn state discontinues the given state with the given exception. It always return Finished (Error exn). If the given state was already resumed elsewhere, this function traps the exception Continuation_already_resumed and return Finished (Error exn).

val pure : ('a, error) Stdlib.result -> 'a t

pure value returns Finished value.

val run : quanta:int -> perform:perform -> 'a t -> 'a t

run ~quanta ~perform state applies once quanta times. If perform responds with Operation.interrupt (and therefore does nothing), even though there may be a few quanta left, the function returns the last state obtained.

The same applies to yield, except that the continuation has burnt itself out. In other words, yield is equivalent to send (); interrupt but costs only one quanta.