sturgeon 0.1 · OCaml Package

Session extends S-exp with abstract objects. One can now put function-like values inside s-expressions.

When serializing, the library will take care of representing these values by handles that can be used from the remote side.

type 'a result =

| Feed of 'a
(*
Feed is the action to transmit a value to an abstract object. See dual type below. A promise (Once) can be fed only once, a stream (Sink) can be fed an arbitrary number of times.
*)
| Quit of Sturgeon_sexp.basic
(*
Quit release an abstract object. If it is a promise (Once), it will be canceled (waiter will receive an error), if it is a stream (Sink) it will be closed.
*)

The actions that can be sent to abstract objects.

type 'a neg = 'a result -> unit

Negation: consuming values. Normal values are positive. When you have one of them you own an instance of some type. Negations are the opposite. When you have one of them all you can do is provide an instance of some type.

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

type dual =

| Once of t neg
(*
Once is the constructor for linear negations: they can consume only one value.
*)
| Sink of t neg
(*
Sink is the constructor for streams: they can consume arbitrarily many values.
*)

and t = dual Sturgeon_sexp.sexp

Finally the type of sessions: it is the S-exp extended with dual values.

val cancel_message : 'a result

The message to send to cancel a negation

val finalize_message : 'a result

The message send by the GC when a negation is collected (and will never be reachable again).

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

Cancel a session: traverse all sub-expressions to cancel negations.

type 'a error = [

| `Already_closed of t 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

]

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 session sent and received. The whole purpose of connect is to convert high-level sessions to plain values back and forth, by allocating and managing concrete addresses.

val close : output -> unit

val pending_sessions : status -> int

val is_closed : status -> bool

package sturgeon