1 (**************************************************************************)
2 (* *)
3 (* OCaml *)
4 (* *)
5 (* David Nowak and Xavier Leroy, projet Cristal, INRIA Rocquencourt *)
6 (* *)
7 (* Copyright 1996 Institut National de Recherche en Informatique et *)
8 (* en Automatique. *)
9 (* *)
10 (* All rights reserved. This file is distributed under the terms of *)
11 (* the GNU Lesser General Public License version 2.1, with the *)
12 (* special exception on linking described in the file LICENSE. *)
13 (* *)
14 (**************************************************************************)
15
16 (** First-class synchronous communication.
17
18 This module implements synchronous inter-thread communications over
19 channels. As in John Reppy's Concurrent ML system, the communication
20 events are first-class values: they can be built and combined
21 independently before being offered for communication.
22 *)
23
24 type 'a channel
25 (** The type of communication channels carrying values of type ['a]. *)
26
27 val new_channel : unit -> 'a channel
28 (** Return a new channel. *)
29
30 type +'a event
31 (** The type of communication events returning a result of type ['a]. *)
32
33 (** [send ch v] returns the event consisting in sending the value [v]
34 over the channel [ch]. The result value of this event is [()]. *)
35 val send : 'a channel -> 'a -> unit event
36
37 (** [receive ch] returns the event consisting in receiving a value
38 from the channel [ch]. The result value of this event is the
39 value received. *)
40 val receive : 'a channel -> 'a event
41
42 val always : 'a -> 'a event
43 (** [always v] returns an event that is always ready for
44 synchronization. The result value of this event is [v]. *)
45
46 val choose : 'a event list -> 'a event
47 (** [choose evl] returns the event that is the alternative of
48 all the events in the list [evl]. *)
49
50 val wrap : 'a event -> ('a -> 'b) -> 'b event
51 (** [wrap ev fn] returns the event that performs the same communications
52 as [ev], then applies the post-processing function [fn]
53 on the return value. *)
54
55 val wrap_abort : 'a event -> (unit -> unit) -> 'a event
56 (** [wrap_abort ev fn] returns the event that performs
57 the same communications as [ev], but if it is not selected
58 the function [fn] is called after the synchronization. *)
59
60 val guard : (unit -> 'a event) -> 'a event
61 (** [guard fn] returns the event that, when synchronized, computes
62 [fn()] and behaves as the resulting event. This enables
63 computing events with side-effects at the time of the synchronization
64 operation. *)
65
66 val sync : 'a event -> 'a
67 (** 'Synchronize' on an event: offer all the communication
68 possibilities specified in the event to the outside world,
69 and block until one of the communications succeed. The result
70 value of that communication is returned. *)
71
72 val select : 'a event list -> 'a
73 (** 'Synchronize' on an alternative of events.
74 [select evl] is shorthand for [sync(choose evl)]. *)
75
76 val poll : 'a event -> 'a option
77 (** Non-blocking version of {!Event.sync}: offer all the communication
78 possibilities specified in the event to the outside world,
79 and if one can take place immediately, perform it and return
80 [Some r] where [r] is the result value of that communication.
81 Otherwise, return [None] without blocking. *)
82