sturgeon 0.4.2 (latest) · OCaml Package

A session is a channel between two parties that can exchange enriched s-expressions. These s-expressions can reference code from the remote party: on top of plain values and lists, one can put function-like values, which, when applied, invoke some remote code.

The library takes care of allocating simple handles to reference remote code.

type reason = [

| `Cancel
| `Finalize
| `Other of Sturgeon_sexp.basic

]

The reason for a continuation to not be invoked anymore. `Cancel: the continuation was not expected, consumer does not know how to deal with it. `Finalize: the GC determined that the continuation cannot be reached anymore. `Other: some error defined by implementor of remote code. This is analogous to exceptions. The error message is a plain Sexp: it is not possible to "catch" the error and resume control flow.

type 'a cont = ('a, reason) Result.result -> unit

A continuation either takes a result value or a reason for terminating.

type remote =

| Once of t cont
(*
Once is the constructor for remote linear continuations: they can consume only one value.
*)
| Many of t cont
(*
Many is the constructor for remote multi-shot continuations: they can consume arbitrarily many values. They can be used to build streams.
*)

Basic Sexp contain plain values that you can inspect. Sessions also contain remote values. Those are opaque but can consume values that you produce and send to the remote side.

Positive and negative values are the building blocks of more complex control flows. For instance, a function from 'a -> 'b can be encoded as ('a * 'b remote) remote: if you give an 'a, you will be given a 'b.

and t = remote Sturgeon_sexp.sexp

The type of sessions: it is the S-exp extended with remote values.

type 'a error = [

| `Already_closed of (t, reason) Result.result
| `Query_after_eof of t
| `Invalid_command of Sturgeon_sexp.basic
| `Feed_unknown of Sturgeon_sexp.basic
| `Quit_unknown of Sturgeon_sexp.basic
| `Exceptions_during_cancellation of t * exn list
| `Exceptions_during_shutdown of exn list

]

val cancel : 
  ?stderr:([> `Exceptions_during_cancellation of t * exn list ] -> unit) ->
  t ->
  unit

Cancel a session: traverse all sub-expressions to terminate continuations.

type output = Sturgeon_sexp.basic -> unit

type status

val connect : 
  ?greetings:t ->
  ?cogreetings:(t -> unit) ->
  ?stderr:(_ error -> unit) ->
  output ->
  output * status

Basic creation of a session. greetings and cogreetings are respectively the first sessions sent and received. The purpose of connect is to convert high-level sessions back and forth plain values, by allocating and managing concrete addresses.

val close : output -> unit

val pending_continuations : status -> int

val is_closed : status -> bool

package sturgeon