/usr/lib/ocaml/lwt/lwt_switch.mli is in liblwt-ocaml-dev 2.7.1-4build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 | (* Lightweight thread library for OCaml
* http://www.ocsigen.org/lwt
* Interface Lwt_switch
* Copyright (C) 2010 Jérémiem Dimino
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation, with linking exceptions;
* either version 2.1 of the License, or (at your option) any later
* version. See COPYING file for details.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
* 02111-1307, USA.
*)
(** Lwt switches *)
(** Switch has two goals:
- being able to free multiple resources at the same time,
- offer a better alternative than always returning an id to free
some resource.
For example, consider the following interface:
{[
type id
val free : id -> unit Lwt.t
val f : unit -> id Lwt.t
val g : unit -> id Lwt.t
val h : unit -> id Lwt.t
]}
Now you want to call [f], [g] and [h] in parallel. You can
simply do:
{[
lwt idf = f () and idg = g () and idh = h () in
...
]}
However, one may want to handle possible failures of [f ()], [g
()] and [h ()], and disable all allocated resources if one of
these three threads fails. This may be hard since you have to
remember which one failed and which one returned correctly.
Now if we change the interface a little bit:
{[
val f : ?switch : Lwt_switch.t -> unit -> id Lwt.t
val g : ?switch : Lwt_switch.t -> unit -> id Lwt.t
val h : ?switch : Lwt_switch.t -> unit -> id Lwt.t
]}
the code becomes:
{[
Lwt_switch.with_switch (fun switch ->
lwt idf = f ~switch ()
and idg = g ~switch ()
and idh = h ~switch () in
...
)
]}
*)
type t
(** Type of switches. *)
val create : unit -> t
(** [create ()] creates a new switch. *)
val with_switch : (t -> 'a Lwt.t) -> 'a Lwt.t
(** [with_switch fn] is [fn switch], where [switch] is a fresh switch
that is turned off when the callback thread finishes (whether it
succeeds or fails).
@since 2.6.0 *)
val is_on : t -> bool
(** [is_on switch] returns [true] if the switch is currently on, and
[false] otherwise. *)
val turn_off : t -> unit Lwt.t
(** [turn_off switch] turns off the switch. It calls all registered
hooks, waits for all of them to terminate, then returns. If
one of the hooks failed, it will fail with the exception raised
by the hook. If the switch is already off, it does nothing. *)
exception Off
(** Exception raised when trying to add a hook to a switch that is
already off. *)
val check : t option -> unit
(** [check switch] does nothing if [switch] is [None] or contains an
switch that is currently on, and raises {!Off} otherwise. *)
val add_hook : t option -> (unit -> unit Lwt.t) -> unit
(** [add_hook switch f] registers [f] so it will be called when
{!turn_off} is invoked. It does nothing if [switch] is
[None]. If [switch] contains an switch that is already off then
{!Off} is raised. *)
val add_hook_or_exec : t option -> (unit -> unit Lwt.t) -> unit Lwt.t
(** [add_hook_or_exec switch f] is the same as {!add_hook} except
that if the switch is already off, [f] is called immediately. *)
|