<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
<link rel="Start" href="index.html">
<link rel="previous" href="Lwt_stream.html">
<link rel="next" href="Lwt_util.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of class attributes" rel=Appendix href="index_attributes.html">
<link title="Index of class methods" rel=Appendix href="index_methods.html">
<link title="Index of classes" rel=Appendix href="index_classes.html">
<link title="Index of class types" rel=Appendix href="index_class_types.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="Lwt_condition" rel="Chapter" href="Lwt_condition.html">
<link title="Lwt_list" rel="Chapter" href="Lwt_list.html">
<link title="Lwt" rel="Chapter" href="Lwt.html">
<link title="Lwt_mutex" rel="Chapter" href="Lwt_mutex.html">
<link title="Lwt_mvar" rel="Chapter" href="Lwt_mvar.html">
<link title="Lwt_pool" rel="Chapter" href="Lwt_pool.html">
<link title="Lwt_sequence" rel="Chapter" href="Lwt_sequence.html">
<link title="Lwt_stream" rel="Chapter" href="Lwt_stream.html">
<link title="Lwt_switch" rel="Chapter" href="Lwt_switch.html">
<link title="Lwt_util" rel="Chapter" href="Lwt_util.html">
<link title="Lwt_pqueue" rel="Chapter" href="Lwt_pqueue.html">
<link title="Lwt_lib" rel="Chapter" href="Lwt_lib.html">
<link title="Lwt_glib" rel="Chapter" href="Lwt_glib.html">
<link title="Lwt_preemptive" rel="Chapter" href="Lwt_preemptive.html">
<link title="Lwt_event" rel="Chapter" href="Lwt_event.html">
<link title="Lwt_signal" rel="Chapter" href="Lwt_signal.html">
<link title="Lwt_react" rel="Chapter" href="Lwt_react.html">
<link title="Lwt_ssl" rel="Chapter" href="Lwt_ssl.html">
<link title="Lwt_text" rel="Chapter" href="Lwt_text.html">
<link title="Lwt_term" rel="Chapter" href="Lwt_term.html">
<link title="Lwt_read_line" rel="Chapter" href="Lwt_read_line.html">
<link title="Lwt_top" rel="Chapter" href="Lwt_top.html">
<link title="Lwt_chan" rel="Chapter" href="Lwt_chan.html">
<link title="Lwt_daemon" rel="Chapter" href="Lwt_daemon.html">
<link title="Lwt_gc" rel="Chapter" href="Lwt_gc.html">
<link title="Lwt_io" rel="Chapter" href="Lwt_io.html">
<link title="Lwt_log" rel="Chapter" href="Lwt_log.html">
<link title="Lwt_main" rel="Chapter" href="Lwt_main.html">
<link title="Lwt_process" rel="Chapter" href="Lwt_process.html">
<link title="Lwt_throttle" rel="Chapter" href="Lwt_throttle.html">
<link title="Lwt_timeout" rel="Chapter" href="Lwt_timeout.html">
<link title="Lwt_unix" rel="Chapter" href="Lwt_unix.html">
<link title="Lwt_sys" rel="Chapter" href="Lwt_sys.html">
<link title="Lwt_engine" rel="Chapter" href="Lwt_engine.html">
<link title="Lwt_bytes" rel="Chapter" href="Lwt_bytes.html">
<link title="Pa_lwt" rel="Chapter" href="Pa_lwt.html">
<link title="Pa_lwt_log" rel="Chapter" href="Pa_lwt_log.html"><title>Lwt_switch</title>
</head>
<body>
<div class="navbar"><a class="pre" href="Lwt_stream.html" title="Lwt_stream">Previous</a>
<a class="up" href="index.html" title="Index">Up</a>
<a class="post" href="Lwt_util.html" title="Lwt_util">Next</a>
</div>
<h1>Module <a href="type_Lwt_switch.html">Lwt_switch</a></h1>
<pre><span class="keyword">module</span> Lwt_switch: <code class="code"><span class="keyword">sig</span></code> <a href="Lwt_switch.html">..</a> <code class="code"><span class="keyword">end</span></code></pre><div class="info">
Lwt switches<br>
</div>
<hr width="100%">
<br>
Switch have two goals:
<p>
<ul>
<li>being able to free multiple resources at the same time,</li>
<li>offer a better alternative than always returning an id to free
some resource.</li>
</ul>
For example, considers the following interface:
<p>
<pre class="codepre"><code class="code"> <span class="keyword">type</span> id<br>
<br>
<span class="keyword">val</span> free : id <span class="keywordsign">-></span> unit <span class="constructor">Lwt</span>.t<br>
<br>
<span class="keyword">val</span> f : unit <span class="keywordsign">-></span> id <span class="constructor">Lwt</span>.t<br>
<span class="keyword">val</span> g : unit <span class="keywordsign">-></span> id <span class="constructor">Lwt</span>.t<br>
<span class="keyword">val</span> h : unit <span class="keywordsign">-></span> id <span class="constructor">Lwt</span>.t<br>
</code></pre>
<p>
Now you want to calls <code class="code">f</code>, <code class="code">g</code> and <code class="code">h</code> in parallel. You can
simply do:
<p>
<pre class="codepre"><code class="code"> lwt idf = f () <span class="keyword">and</span> idg = g () <span class="keyword">and</span> idh = h () <span class="keyword">in</span><br>
...<br>
</code></pre>
<p>
However, one may wants to handle possible failures of <code class="code">f ()</code>, <code class="code">g
()</code> and <code class="code">h ()</code>, 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.
<p>
Now we change a little bit the interface:
<p>
<pre class="codepre"><code class="code"> <span class="keyword">val</span> f : ?switch : <span class="constructor">Lwt_switch</span>.t <span class="keywordsign">-></span> unit <span class="keywordsign">-></span> id <span class="constructor">Lwt</span>.t<br>
<span class="keyword">val</span> g : ?switch : <span class="constructor">Lwt_switch</span>.t <span class="keywordsign">-></span> unit <span class="keywordsign">-></span> id <span class="constructor">Lwt</span>.t<br>
<span class="keyword">val</span> h : ?switch : <span class="constructor">Lwt_switch</span>.t <span class="keywordsign">-></span> unit <span class="keywordsign">-></span> id <span class="constructor">Lwt</span>.t<br>
</code></pre>
<p>
and the code becomes:
<p>
<pre class="codepre"><code class="code"> <span class="keyword">let</span> switch = <span class="constructor">Lwt_switch</span>.create () <span class="keyword">in</span><br>
try_lwt<br>
lwt idf = f ~switch () <span class="keyword">and</span> idg = g ~switch () <span class="keyword">and</span> idh = h ~switch () <span class="keyword">in</span><br>
...<br>
<span class="keyword">with</span> exn <span class="keywordsign">-></span><br>
lwt () = <span class="constructor">Lwt_switch</span>.turn_off switch <span class="keyword">in</span><br>
raise_lwt exn<br>
</code></pre><br>
<pre><span id="TYPEt"><span class="keyword">type</span> <code class="type"></code>t</span> </pre>
<div class="info">
Type of switches.<br>
</div>
<pre><span id="VALcreate"><span class="keyword">val</span> create</span> : <code class="type">unit -> <a href="Lwt_switch.html#TYPEt">t</a></code></pre><div class="info">
<code class="code">create ()</code> creates a new switch.<br>
</div>
<pre><span id="VALis_on"><span class="keyword">val</span> is_on</span> : <code class="type"><a href="Lwt_switch.html#TYPEt">t</a> -> bool</code></pre><div class="info">
<code class="code">is_on switch</code> returns <code class="code"><span class="keyword">true</span></code> if the switch is currently on, and
<code class="code"><span class="keyword">false</span></code> otherwise.<br>
</div>
<pre><span id="VALturn_off"><span class="keyword">val</span> turn_off</span> : <code class="type"><a href="Lwt_switch.html#TYPEt">t</a> -> unit <a href="Lwt.html#TYPEt">Lwt.t</a></code></pre><div class="info">
<code class="code">turn_off switch</code> turns off the switch. It calls all registered
hooks, waits for all of them to terminates, and the returns. If
one of the hook failed, then it will fail with one of the
exception raised by hooks. If the switch is already off, then it
does nothing.<br>
</div>
<pre><span id="EXCEPTIONOff"><span class="keyword">exception</span> Off</span></pre>
<div class="info">
Exception raised when trying to add a hook to a switch that is
already off.<br>
</div>
<pre><span id="VALcheck"><span class="keyword">val</span> check</span> : <code class="type"><a href="Lwt_switch.html#TYPEt">t</a> option -> unit</code></pre><div class="info">
<code class="code">check switch</code> does nothing if <code class="code">switch</code> is <code class="code"><span class="constructor">None</span></code> or contains an
switch that is currently on, and raise <a href="Lwt_switch.html#EXCEPTIONOff"><code class="code"><span class="constructor">Lwt_switch</span>.<span class="constructor">Off</span></code></a> otherwise.<br>
</div>
<pre><span id="VALadd_hook"><span class="keyword">val</span> add_hook</span> : <code class="type"><a href="Lwt_switch.html#TYPEt">t</a> option -> (unit -> unit <a href="Lwt.html#TYPEt">Lwt.t</a>) -> unit</code></pre><div class="info">
<code class="code">add_hook switch f</code> registers <code class="code">f</code> so it will be called when
<a href="Lwt_switch.html#VALturn_off"><code class="code"><span class="constructor">Lwt_switch</span>.turn_off</code></a> is invoked. It does nothing if <code class="code">switch</code> is
<code class="code"><span class="constructor">None</span></code>. If <code class="code">switch</code> contains an switch that is already off then
<a href="Lwt_switch.html#EXCEPTIONOff"><code class="code"><span class="constructor">Lwt_switch</span>.<span class="constructor">Off</span></code></a> is raised.<br>
</div>
<pre><span id="VALadd_hook_or_exec"><span class="keyword">val</span> add_hook_or_exec</span> : <code class="type"><a href="Lwt_switch.html#TYPEt">t</a> option -> (unit -> unit <a href="Lwt.html#TYPEt">Lwt.t</a>) -> unit <a href="Lwt.html#TYPEt">Lwt.t</a></code></pre><div class="info">
<code class="code">add_hook_or_exec switch f</code> is the same as <a href="Lwt_switch.html#VALadd_hook"><code class="code"><span class="constructor">Lwt_switch</span>.add_hook</code></a> except
that if the switch is already off, then <code class="code">f</code> is called
immediatly.<br>
</div>
</body></html>
