/usr/share/doc/liblwt-ocaml-dev/api/Lwt.html

<!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_list.html">
<link rel="next" href="Lwt_mutex.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_pqueue" rel="Chapter" href="Lwt_pqueue.html">
<link title="Lwt_glib" rel="Chapter" href="Lwt_glib.html">
<link title="Lwt_preemptive" rel="Chapter" href="Lwt_preemptive.html">
<link title="Lwt_react" rel="Chapter" href="Lwt_react.html">
<link title="Lwt_ssl" rel="Chapter" href="Lwt_ssl.html">
<link title="Lwt_log_core" rel="Chapter" href="Lwt_log_core.html">
<link title="Lwt_log_rules" rel="Chapter" href="Lwt_log_rules.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">
<link title="Ppx_lwt" rel="Chapter" href="Ppx_lwt.html"><link title="Definitions and basics" rel="Section" href="#2_Definitionsandbasics">
<link title="Thread storage" rel="Section" href="#2_Threadstorage">
<link title="Exceptions handling" rel="Section" href="#2_Exceptionshandling">
<link title="Multi-threads composition" rel="Section" href="#2_Multithreadscomposition">
<link title="Sleeping and resuming" rel="Section" href="#2_Sleepingandresuming">
<link title="Threads state" rel="Section" href="#2_Threadsstate">
<link title="Cancelable threads" rel="Section" href="#2_Cancelablethreads">
<link title="Cancelable threads" rel="Section" href="#2_Cancelablethreads">
<link title="Pause" rel="Section" href="#2_Pause">
<link title="Misc" rel="Section" href="#2_Misc">
<link title="Pre-allocated threads" rel="Subsection" href="#3_Preallocatedthreads">
<title>Lwt</title>
</head>
<body>
<div class="navbar"><a class="pre" href="Lwt_list.html" title="Lwt_list">Previous</a>
&nbsp;<a class="up" href="index.html" title="Index">Up</a>
&nbsp;<a class="post" href="Lwt_mutex.html" title="Lwt_mutex">Next</a>
</div>
<h1>Module <a href="type_Lwt.html">Lwt</a></h1>

<pre><span class="keyword">module</span> Lwt: <code class="code"><span class="keyword">sig</span></code> <a href="Lwt.html">..</a> <code class="code"><span class="keyword">end</span></code></pre><div class="info module top">
Module <code class="code"><span class="constructor">Lwt</span></code>: cooperative light-weight threads.<br>
</div>
<hr width="100%">
<br>
This module defines <em>cooperative light-weight threads</em> with
    their primitives. A <em>light-weight thread</em> represent a
    computation that may be not terminated, for example because it is
    waiting for some event to happen.
<p>

    Lwt threads are cooperative in the sense that switching to another
    thread is awlays explicit (with <a href="Lwt.html#VALwakeup"><code class="code"><span class="constructor">Lwt</span>.wakeup</code></a> or <a href="Lwt.html#VALwakeup_exn"><code class="code"><span class="constructor">Lwt</span>.wakeup_exn</code></a>). When a
    thread is running, it executes as much as possible, and then
    returns (a value or an error) or sleeps.
<p>

    Note that inside a Lwt thread, exceptions must be raised with
    <a href="Lwt.html#VALfail"><code class="code"><span class="constructor">Lwt</span>.fail</code></a> instead of <code class="code">raise</code>. Also the <code class="code"><span class="keyword">try</span> ... <span class="keyword">with</span> ...</code>
    construction will not catch Lwt errors. You must use <a href="Lwt.html#VALcatch"><code class="code"><span class="constructor">Lwt</span>.catch</code></a>
    instead. You can also use <a href="Lwt.html#VALwrap"><code class="code"><span class="constructor">Lwt</span>.wrap</code></a> for functions that may raise
    normal exception.
<p>

    Lwt also provides the syntax extension <a href="Pa_lwt.html"><code class="code"><span class="constructor">Pa_lwt</span></code></a> to make code
    using Lwt more readable.<br>
<br>
This module defines <em>cooperative light-weight threads</em> with
    their primitives. A <em>light-weight thread</em> represent a
    computation that may be not terminated, for example because it is
    waiting for some event to happen.
<p>

    Lwt threads are cooperative in the sense that switching to another
    thread is awlays explicit (with <a href="Lwt.html#VALwakeup"><code class="code"><span class="constructor">Lwt</span>.wakeup</code></a> or <a href="Lwt.html#VALwakeup_exn"><code class="code"><span class="constructor">Lwt</span>.wakeup_exn</code></a>). When a
    thread is running, it executes as much as possible, and then
    returns (a value or an error) or sleeps.
<p>

    Note that inside a Lwt thread, exceptions must be raised with
    <a href="Lwt.html#VALfail"><code class="code"><span class="constructor">Lwt</span>.fail</code></a> instead of <code class="code">raise</code>. Also the <code class="code"><span class="keyword">try</span> ... <span class="keyword">with</span> ...</code>
    construction will not catch Lwt errors. You must use <a href="Lwt.html#VALcatch"><code class="code"><span class="constructor">Lwt</span>.catch</code></a>
    instead. You can also use <a href="Lwt.html#VALwrap"><code class="code"><span class="constructor">Lwt</span>.wrap</code></a> for functions that may raise
    normal exception.
<p>

    Lwt also provides the syntax extension <a href="Pa_lwt.html"><code class="code"><span class="constructor">Pa_lwt</span></code></a> to make code
    using Lwt more readable.<br>
<br>
<h2 id="2_Definitionsandbasics">Definitions and basics</h2><br>

<pre><span id="TYPEt"><span class="keyword">type</span> <code class="type">+'a</code> t</span> </pre>
<div class="info ">
The type of threads returning a result of type <code class="code"><span class="keywordsign">'</span>a</code>.<br>
</div>


<pre><span id="VALreturn"><span class="keyword">val</span> return</span> : <code class="type">'a -> 'a <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">return e</code> is a thread whose return value is the value of the
      expression <code class="code">e</code>.<br>
</div>

<pre><span id="VALfail"><span class="keyword">val</span> fail</span> : <code class="type">exn -> 'a <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">fail e</code> is a thread that fails with the exception <code class="code">e</code>.<br>
</div>

<pre><span id="VALfail_with"><span class="keyword">val</span> fail_with</span> : <code class="type">string -> 'a <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">fail_with msg</code> is a thread that fails with the exception
      <code class="code"><span class="constructor">Failure</span> msg</code>.<br>
</div>

<pre><span id="VALfail_invalid_arg"><span class="keyword">val</span> fail_invalid_arg</span> : <code class="type">string -> 'a <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">fail_invalid_arg msg</code> is a thread that fails with the exception
      <code class="code"><span class="constructor">Invalid_argument</span> msg</code>.<br>
</div>

<pre><span id="VALbind"><span class="keyword">val</span> bind</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> -> ('a -> 'b <a href="Lwt.html#TYPEt">t</a>) -> 'b <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">bind t f</code> is a thread which first waits for the thread <code class="code">t</code> to
      terminate and then, if the thread succeeds, behaves as the
      application of function <code class="code">f</code> to the return value of <code class="code">t</code>.  If the
      thread <code class="code">t</code> fails, <code class="code">bind t f</code> also fails, with the same
      exception.
<p>

      The expression <code class="code">bind t (<span class="keyword">fun</span> x <span class="keywordsign">-&gt;</span> t')</code> can intuitively be read as
      <code class="code"><span class="keyword">let</span> x = t <span class="keyword">in</span> t'</code>, and if you use the <em>lwt.syntax</em> syntax
      extension, you can write a bind operation like that: <code class="code">lwt x = t <span class="keyword">in</span> t'</code>.
<p>

      Note that <code class="code">bind</code> is also often used just for synchronization
      purpose: <code class="code">t'</code> will not execute before <code class="code">t</code> is terminated.
<p>

      The result of a thread can be bound several times.
<p>

      Note that <code class="code">bind</code> will not propagate backtraces correctly.
      See &lt;&lt;a_api project="lwt" | The manual&gt;&gt;
      for how to enable backtraces.<br>
</div>

<pre><span id="VAL(>>=)"><span class="keyword">val</span> (&gt;&gt;=)</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> -> ('a -> 'b <a href="Lwt.html#TYPEt">t</a>) -> 'b <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">t &gt;&gt;= f</code> is an alternative notation for <code class="code">bind t f</code>.<br>
</div>

<pre><span id="VAL(=<<)"><span class="keyword">val</span> (=&lt;&lt;)</span> : <code class="type">('a -> 'b <a href="Lwt.html#TYPEt">t</a>) -> 'a <a href="Lwt.html#TYPEt">t</a> -> 'b <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">f =&lt;&lt; t</code> is <code class="code">t &gt;&gt;= f</code><br>
</div>

<pre><span id="VALmap"><span class="keyword">val</span> map</span> : <code class="type">('a -> 'b) -> 'a <a href="Lwt.html#TYPEt">t</a> -> 'b <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">map f m</code> maps the result of a thread. This is the same as <code class="code">bind
      m (<span class="keyword">fun</span> x <span class="keywordsign">-&gt;</span> return (f x))</code><br>
</div>

<pre><span id="VAL(>|=)"><span class="keyword">val</span> (&gt;|=)</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> -> ('a -> 'b) -> 'b <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">m &gt;|= f</code> is <code class="code">map f m</code><br>
</div>

<pre><span id="VAL(=|<)"><span class="keyword">val</span> (=|&lt;)</span> : <code class="type">('a -> 'b) -> 'a <a href="Lwt.html#TYPEt">t</a> -> 'b <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">f =|&lt; m</code> is <code class="code">map f m</code><br>
</div>
<br>
<h3 id="3_Preallocatedthreads">Pre-allocated threads</h3><br>

<pre><span id="VALreturn_unit"><span class="keyword">val</span> return_unit</span> : <code class="type">unit <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">return_unit = return ()</code><br>
</div>

<pre><span id="VALreturn_none"><span class="keyword">val</span> return_none</span> : <code class="type">'a option <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">return_none = return <span class="constructor">None</span></code><br>
</div>

<pre><span id="VALreturn_some"><span class="keyword">val</span> return_some</span> : <code class="type">'a -> 'a option <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">return_some x = return (<span class="constructor">Some</span> x)</code><br>
</div>

<pre><span id="VALreturn_nil"><span class="keyword">val</span> return_nil</span> : <code class="type">'a list <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">return_nil = return []</code><br>
</div>

<pre><span id="VALreturn_true"><span class="keyword">val</span> return_true</span> : <code class="type">bool <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">return_true = return <span class="keyword">true</span></code><br>
</div>

<pre><span id="VALreturn_false"><span class="keyword">val</span> return_false</span> : <code class="type">bool <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">return_false = return <span class="keyword">false</span></code><br>
</div>
<br>
<h2 id="2_Threadstorage">Thread storage</h2><br>

<pre><span id="TYPEkey"><span class="keyword">type</span> <code class="type">'a</code> key</span> </pre>
<div class="info ">
Type of a key. Keys are used to store local values into
      threads.<br>
</div>


<pre><span id="VALnew_key"><span class="keyword">val</span> new_key</span> : <code class="type">unit -> 'a <a href="Lwt.html#TYPEkey">key</a></code></pre><div class="info ">
<code class="code">new_key ()</code> creates a new key.<br>
</div>

<pre><span id="VALget"><span class="keyword">val</span> get</span> : <code class="type">'a <a href="Lwt.html#TYPEkey">key</a> -> 'a option</code></pre><div class="info ">
<code class="code">get key</code> returns the value associated with <code class="code">key</code> in the current
      thread.<br>
</div>

<pre><span id="VALwith_value"><span class="keyword">val</span> with_value</span> : <code class="type">'a <a href="Lwt.html#TYPEkey">key</a> -> 'a option -> (unit -> 'b) -> 'b</code></pre><div class="info ">
<code class="code">with_value key value f</code> executes <code class="code">f</code> with <code class="code">value</code> associated to
      <code class="code">key</code>. <code class="code">key</code> is restored to its previous value after <code class="code">f</code> terminates.<br>
</div>
<br>
<h2 id="2_Exceptionshandling">Exceptions handling</h2><br>

<pre><span id="VALcatch"><span class="keyword">val</span> catch</span> : <code class="type">(unit -> 'a <a href="Lwt.html#TYPEt">t</a>) -> (exn -> 'a <a href="Lwt.html#TYPEt">t</a>) -> 'a <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">catch t f</code> is a thread that behaves as the thread <code class="code">t ()</code> if
      this thread succeeds.  If the thread <code class="code">t ()</code> fails with some
      exception, <code class="code">catch t f</code> behaves as the application of <code class="code">f</code> to this
      exception.<br>
</div>

<pre><span id="VALtry_bind"><span class="keyword">val</span> try_bind</span> : <code class="type">(unit -> 'a <a href="Lwt.html#TYPEt">t</a>) -> ('a -> 'b <a href="Lwt.html#TYPEt">t</a>) -> (exn -> 'b <a href="Lwt.html#TYPEt">t</a>) -> 'b <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">try_bind t f g</code> behaves as <code class="code">bind (t ()) f</code> if <code class="code">t</code> does not
      fail.  Otherwise, it behaves as the application of <code class="code">g</code> to the
      exception associated to <code class="code">t ()</code>.<br>
</div>

<pre><span id="VALfinalize"><span class="keyword">val</span> finalize</span> : <code class="type">(unit -> 'a <a href="Lwt.html#TYPEt">t</a>) -> (unit -> unit <a href="Lwt.html#TYPEt">t</a>) -> 'a <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">finalize f g</code> returns the same result as <code class="code">f ()</code> whether it
      fails or not. In both cases, <code class="code">g ()</code> is executed after <code class="code">f</code>.<br>
</div>

<pre><span id="VALwrap"><span class="keyword">val</span> wrap</span> : <code class="type">(unit -> 'a) -> 'a <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">wrap f</code> calls <code class="code">f</code> and transforms the result into an Lwt thread.
      If <code class="code">f</code> raises an exception, it is caught and converted to an Lwt
      exception.
<p>

      This is actually the same as:
<p>

      <pre class="codepre"><code class="code">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="keyword">try</span><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return&nbsp;(f&nbsp;())<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="keyword">with</span>&nbsp;exn&nbsp;<span class="keywordsign">-&gt;</span><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fail&nbsp;exn<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code></pre><br>
</div>

<pre><span id="VALwrap1"><span class="keyword">val</span> wrap1</span> : <code class="type">('a -> 'b) -> 'a -> 'b <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">wrap1 f x</code> applies <code class="code">f</code> on <code class="code">x</code> and returns the result as a
      thread. If the application of <code class="code">f</code> to <code class="code">x</code> raise an exception it
      is catched and a thread is returned.
<p>

      Note that you must use <a href="Lwt.html#VALwrap"><code class="code"><span class="constructor">Lwt</span>.wrap</code></a> instead of <a href="Lwt.html#VALwrap1"><code class="code"><span class="constructor">Lwt</span>.wrap1</code></a> if the
      evaluation of <code class="code">x</code> may raise an exception.
<p>

      For example, the following code is incorrect:
<p>

      <pre class="codepre"><code class="code">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;wrap1&nbsp;f&nbsp;(<span class="constructor">Hashtbl</span>.find&nbsp;table&nbsp;key)<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code></pre>
<p>

      and should be written as:
<p>

      <pre class="codepre"><code class="code">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;wrap&nbsp;(<span class="keyword">fun</span>&nbsp;()&nbsp;<span class="keywordsign">-&gt;</span>&nbsp;f&nbsp;(<span class="constructor">Hashtbl</span>.find&nbsp;table&nbsp;key))<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code></pre><br>
</div>

<pre><span id="VALwrap2"><span class="keyword">val</span> wrap2</span> : <code class="type">('a -> 'b -> 'c) -> 'a -> 'b -> 'c <a href="Lwt.html#TYPEt">t</a></code></pre>
<pre><span id="VALwrap3"><span class="keyword">val</span> wrap3</span> : <code class="type">('a -> 'b -> 'c -> 'd) -> 'a -> 'b -> 'c -> 'd <a href="Lwt.html#TYPEt">t</a></code></pre>
<pre><span id="VALwrap4"><span class="keyword">val</span> wrap4</span> : <code class="type">('a -> 'b -> 'c -> 'd -> 'e) -> 'a -> 'b -> 'c -> 'd -> 'e <a href="Lwt.html#TYPEt">t</a></code></pre>
<pre><span id="VALwrap5"><span class="keyword">val</span> wrap5</span> : <code class="type">('a -> 'b -> 'c -> 'd -> 'e -> 'f) -> 'a -> 'b -> 'c -> 'd -> 'e -> 'f <a href="Lwt.html#TYPEt">t</a></code></pre>
<pre><span id="VALwrap6"><span class="keyword">val</span> wrap6</span> : <code class="type">('a -> 'b -> 'c -> 'd -> 'e -> 'f -> 'g) -><br>       'a -> 'b -> 'c -> 'd -> 'e -> 'f -> 'g <a href="Lwt.html#TYPEt">t</a></code></pre>
<pre><span id="VALwrap7"><span class="keyword">val</span> wrap7</span> : <code class="type">('a -> 'b -> 'c -> 'd -> 'e -> 'f -> 'g -> 'h) -><br>       'a -> 'b -> 'c -> 'd -> 'e -> 'f -> 'g -> 'h <a href="Lwt.html#TYPEt">t</a></code></pre><br>
<h2 id="2_Multithreadscomposition">Multi-threads composition</h2><br>

<pre><span id="VALchoose"><span class="keyword">val</span> choose</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> list -> 'a <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">choose l</code> behaves as the first thread in <code class="code">l</code> to terminate.  If
      several threads are already terminated, one is chosen at
      random.
<p>

      Note: <a href="Lwt.html#VALchoose"><code class="code"><span class="constructor">Lwt</span>.choose</code></a> leaves the local values of the current thread
      unchanged.<br>
</div>

<pre><span id="VALnchoose"><span class="keyword">val</span> nchoose</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> list -> 'a list <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">nchoose l</code> returns the value of all that have succcessfully
      terminated. If all threads are sleeping, it waits for at least
      one to terminates. If one the threads of <code class="code">l</code> fails, <code class="code">nchoose</code>
      fails with the same exception.
<p>

      Note: <a href="Lwt.html#VALnchoose"><code class="code"><span class="constructor">Lwt</span>.nchoose</code></a> leaves the local values of the current thread
      unchanged.<br>
</div>

<pre><span id="VALnchoose_split"><span class="keyword">val</span> nchoose_split</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> list -> ('a list * 'a <a href="Lwt.html#TYPEt">t</a> list) <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">nchoose_split l</code> does the same as <a href="Lwt.html#VALnchoose"><code class="code"><span class="constructor">Lwt</span>.nchoose</code></a> but also retrurns
      the list of threads that have not yet terminated.<br>
</div>

<pre><span id="VALjoin"><span class="keyword">val</span> join</span> : <code class="type">unit <a href="Lwt.html#TYPEt">t</a> list -> unit <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">join l</code> waits for all threads in <code class="code">l</code> to terminate. If one of
      the threads fails, then <code class="code">join l</code> will fails with the same
      exception as the first one to terminate.
<p>

      Note: <a href="Lwt.html#VALjoin"><code class="code"><span class="constructor">Lwt</span>.join</code></a> leaves the local values of the current thread
      unchanged.<br>
</div>

<pre><span id="VAL(<?>)"><span class="keyword">val</span> (&lt;?&gt;)</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> -> 'a <a href="Lwt.html#TYPEt">t</a> -> 'a <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">t &lt;?&gt; t'</code> is the same as <code class="code">choose [t; t']</code><br>
</div>

<pre><span id="VAL(<&>)"><span class="keyword">val</span> (&lt;&amp;&gt;)</span> : <code class="type">unit <a href="Lwt.html#TYPEt">t</a> -> unit <a href="Lwt.html#TYPEt">t</a> -> unit <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">t &lt;&amp;&gt; t'</code> is the same as <code class="code">join [t; t']</code><br>
</div>

<pre><span id="VALasync"><span class="keyword">val</span> async</span> : <code class="type">(unit -> 'a <a href="Lwt.html#TYPEt">t</a>) -> unit</code></pre><div class="info ">
<code class="code">async f</code> starts a thread without waiting for the result. If it
      fails (now or later), the exception is given to
      <a href="Lwt.html#VALasync_exception_hook"><code class="code"><span class="constructor">Lwt</span>.async_exception_hook</code></a>.
<p>

      You should use this function if you want to start a thread that
      might fail and don't care what its return value is, nor when it
      terminates (for instance, because it is looping).<br>
</div>

<pre><span id="VALignore_result"><span class="keyword">val</span> ignore_result</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> -> unit</code></pre><div class="info ">
<code class="code">ignore_result t</code> is like <code class="code"><span class="constructor">Pervasives</span>.ignore t</code> except that:
<p>
<ul>
<li>if <code class="code">t</code> already failed, it raises the exception now,</li>
<li>if <code class="code">t</code> is sleeping and fails later, the exception will be
        given to <a href="Lwt.html#VALasync_exception_hook"><code class="code"><span class="constructor">Lwt</span>.async_exception_hook</code></a>.</li>
</ul>
<br>
</div>

<pre><span id="VALasync_exception_hook"><span class="keyword">val</span> async_exception_hook</span> : <code class="type">(exn -> unit) Pervasives.ref</code></pre><div class="info ">
Function called when a asynchronous exception is thrown.
<p>

      The default behavior is to print an error message with a
      backtrace if available and to exit the program.
<p>

      The behavior is undefined if this function raise an
      exception.
<p>

      See &lt;&lt;a_api project="lwt" | The manual&gt;&gt;
      for how to enable backtraces.<br>
</div>
<br>
<h2 id="2_Sleepingandresuming">Sleeping and resuming</h2><br>

<pre><span id="TYPEu"><span class="keyword">type</span> <code class="type">'a</code> u</span> </pre>
<div class="info ">
The type of thread wakeners.<br>
</div>


<pre><span id="VALwait"><span class="keyword">val</span> wait</span> : <code class="type">unit -> 'a <a href="Lwt.html#TYPEt">t</a> * 'a <a href="Lwt.html#TYPEu">u</a></code></pre><div class="info ">
<code class="code">wait ()</code> is a pair of a thread which sleeps forever (unless it
      is resumed by one of the functions <code class="code">wakeup</code>, <code class="code">wakeup_exn</code> below)
      and the corresponding wakener.  This thread does not block the
      execution of the remainder of the program (except of course, if
      another thread tries to wait for its termination).<br>
</div>

<pre><span id="VALwakeup"><span class="keyword">val</span> wakeup</span> : <code class="type">'a <a href="Lwt.html#TYPEu">u</a> -> 'a -> unit</code></pre><div class="info ">
<code class="code">wakeup t e</code> makes the sleeping thread <code class="code">t</code> terminate and return
      the value of the expression <code class="code">e</code>.<br>
</div>

<pre><span id="VALwakeup_exn"><span class="keyword">val</span> wakeup_exn</span> : <code class="type">'a <a href="Lwt.html#TYPEu">u</a> -> exn -> unit</code></pre><div class="info ">
<code class="code">wakeup_exn t e</code> makes the sleeping thread <code class="code">t</code> fail with the
      exception <code class="code">e</code>.<br>
</div>

<pre><span id="VALwakeup_later"><span class="keyword">val</span> wakeup_later</span> : <code class="type">'a <a href="Lwt.html#TYPEu">u</a> -> 'a -> unit</code></pre><div class="info ">
Same as <a href="Lwt.html#VALwakeup"><code class="code"><span class="constructor">Lwt</span>.wakeup</code></a> but it is not guaranteed that the thread will
      be woken up immediately.<br>
</div>

<pre><span id="VALwakeup_later_exn"><span class="keyword">val</span> wakeup_later_exn</span> : <code class="type">'a <a href="Lwt.html#TYPEu">u</a> -> exn -> unit</code></pre><div class="info ">
Same as <a href="Lwt.html#VALwakeup_exn"><code class="code"><span class="constructor">Lwt</span>.wakeup_exn</code></a> but it is not guaranteed that the thread
      will be woken up immediately.<br>
</div>

<pre><span id="VALwaiter_of_wakener"><span class="keyword">val</span> waiter_of_wakener</span> : <code class="type">'a <a href="Lwt.html#TYPEu">u</a> -> 'a <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
Returns the thread associated to a wakener.<br>
</div>

<pre><span id="TYPEresult"><span class="keyword">type</span> <code class="type">+'a</code> result</span> </pre>
<div class="info ">
Either a value of type <code class="code"><span class="keywordsign">'</span>a</code>, either an exception.<br>
</div>


<pre><span id="VALmake_value"><span class="keyword">val</span> make_value</span> : <code class="type">'a -> 'a <a href="Lwt.html#TYPEresult">result</a></code></pre><div class="info ">
<code class="code">value x</code> creates a result containing the value <code class="code">x</code>.<br>
</div>

<pre><span id="VALmake_error"><span class="keyword">val</span> make_error</span> : <code class="type">exn -> 'a <a href="Lwt.html#TYPEresult">result</a></code></pre><div class="info ">
<code class="code">error e</code> creates a result containing the exception <code class="code">e</code>.<br>
</div>

<pre><span id="VALof_result"><span class="keyword">val</span> of_result</span> : <code class="type">'a <a href="Lwt.html#TYPEresult">result</a> -> 'a <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
Returns a thread from a result.<br>
</div>

<pre><span id="VALwakeup_result"><span class="keyword">val</span> wakeup_result</span> : <code class="type">'a <a href="Lwt.html#TYPEu">u</a> -> 'a <a href="Lwt.html#TYPEresult">result</a> -> unit</code></pre><div class="info ">
<code class="code">wakeup_result t r</code> makes the sleeping thread <code class="code">t</code> terminate with
      the result <code class="code">r</code>.<br>
</div>

<pre><span id="VALwakeup_later_result"><span class="keyword">val</span> wakeup_later_result</span> : <code class="type">'a <a href="Lwt.html#TYPEu">u</a> -> 'a <a href="Lwt.html#TYPEresult">result</a> -> unit</code></pre><div class="info ">
Same as <a href="Lwt.html#VALwakeup_result"><code class="code"><span class="constructor">Lwt</span>.wakeup_result</code></a> but it is not guaranteed that the
      thread will be woken up immediately.<br>
</div>
<br>
<h2 id="2_Threadsstate">Threads state</h2><br>

<pre><code><span id="TYPEstate"><span class="keyword">type</span> <code class="type">'a</code> state</span> = </code></pre><table class="typetable">
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTstate.Return"><span class="constructor">Return</span></span> <span class="keyword">of</span> <code class="type">'a</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" ><div class="info ">
The thread which has successfully terminated<br>
</div>
</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTstate.Fail"><span class="constructor">Fail</span></span> <span class="keyword">of</span> <code class="type">exn</code></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" ><div class="info ">
The thread raised an exception<br>
</div>
</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr>
<tr>
<td align="left" valign="top" >
<code><span class="keyword">|</span></code></td>
<td align="left" valign="top" >
<code><span id="TYPEELTstate.Sleep"><span class="constructor">Sleep</span></span></code></td>
<td class="typefieldcomment" align="left" valign="top" ><code>(*</code></td><td class="typefieldcomment" align="left" valign="top" ><div class="info ">
The thread is sleeping<br>
</div>
</td><td class="typefieldcomment" align="left" valign="bottom" ><code>*)</code></td>
</tr></table>

<div class="info ">
State of a thread<br>
</div>


<pre><span id="VALstate"><span class="keyword">val</span> state</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> -> 'a <a href="Lwt.html#TYPEstate">state</a></code></pre><div class="info ">
<code class="code">state t</code> returns the state of a thread<br>
</div>

<pre><span id="VALis_sleeping"><span class="keyword">val</span> is_sleeping</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> -> bool</code></pre><div class="info ">
<code class="code">is_sleeping t</code> returns <code class="code"><span class="keyword">true</span></code> iff <code class="code">t</code> is sleeping.<br>
</div>
<br>
<h2 id="2_Cancelablethreads">Cancelable threads</h2><br>
<br>
<h2 id="2_Cancelablethreads">Cancelable threads</h2><br>
<br>
Cancelable threads are the same as regular threads except that
    they can be canceled.<br>

<pre><span id="EXCEPTIONCanceled"><span class="keyword">exception</span> Canceled</span></pre>
<div class="info ">
Canceled threads fails with this exception<br>
</div>

<pre><span id="VALtask"><span class="keyword">val</span> task</span> : <code class="type">unit -> 'a <a href="Lwt.html#TYPEt">t</a> * 'a <a href="Lwt.html#TYPEu">u</a></code></pre><div class="info ">
<code class="code">task ()</code> is the same as <code class="code">wait ()</code> except that threads created
      with <code class="code">task</code> can be canceled.<br>
</div>

<pre><span id="VALon_cancel"><span class="keyword">val</span> on_cancel</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> -> (unit -> unit) -> unit</code></pre><div class="info ">
<code class="code">on_cancel t f</code> executes <code class="code">f</code> when <code class="code">t</code> is canceled. <code class="code">f</code> will be
      executed before all other threads waiting on <code class="code">t</code>.
<p>

      If <code class="code">f</code> raises an exception it is given to
      <a href="Lwt.html#VALasync_exception_hook"><code class="code"><span class="constructor">Lwt</span>.async_exception_hook</code></a>.<br>
</div>

<pre><span id="VALadd_task_r"><span class="keyword">val</span> add_task_r</span> : <code class="type">'a <a href="Lwt.html#TYPEu">u</a> <a href="Lwt_sequence.html#TYPEt">Lwt_sequence.t</a> -> 'a <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">add_task_r seq</code> creates a sleeping thread, adds its wakener to
      the right of <code class="code">seq</code> and returns its waiter. When the thread is
      canceled, it is removed from <code class="code">seq</code>.<br>
</div>

<pre><span id="VALadd_task_l"><span class="keyword">val</span> add_task_l</span> : <code class="type">'a <a href="Lwt.html#TYPEu">u</a> <a href="Lwt_sequence.html#TYPEt">Lwt_sequence.t</a> -> 'a <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">add_task_l seq</code> creates a sleeping thread, adds its wakener to
      the left of <code class="code">seq</code> and returns its waiter. When the thread is
      canceled, it is removed from <code class="code">seq</code>.<br>
</div>

<pre><span id="VALcancel"><span class="keyword">val</span> cancel</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> -> unit</code></pre><div class="info ">
<code class="code">cancel t</code> cancels the threads <code class="code">t</code>. This means that the deepest
      sleeping thread created with <code class="code">task</code> and connected to <code class="code">t</code> is
      woken up with the exception <a href="Lwt.html#EXCEPTIONCanceled"><code class="code"><span class="constructor">Lwt</span>.<span class="constructor">Canceled</span></code></a>.
<p>

      For example, in the following code:
<p>

      <pre class="codepre"><code class="code">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<span class="keyword">let</span>&nbsp;waiter,&nbsp;wakener&nbsp;=&nbsp;task&nbsp;()&nbsp;<span class="keyword">in</span><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cancel&nbsp;(waiter&nbsp;&gt;&gt;&nbsp;printl&nbsp;<span class="string">"plop"</span>)<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</code></pre>
<p>

      <code class="code">waiter</code> will be woken up with <a href="Lwt.html#EXCEPTIONCanceled"><code class="code"><span class="constructor">Lwt</span>.<span class="constructor">Canceled</span></code></a>.<br>
</div>

<pre><span id="VALpick"><span class="keyword">val</span> pick</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> list -> 'a <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">pick l</code> is the same as <a href="Lwt.html#VALchoose"><code class="code"><span class="constructor">Lwt</span>.choose</code></a>, except that it cancels all
      sleeping threads when one terminates.
<p>

      Note: <a href="Lwt.html#VALpick"><code class="code"><span class="constructor">Lwt</span>.pick</code></a> leaves the local values of the current thread
      unchanged.<br>
</div>

<pre><span id="VALnpick"><span class="keyword">val</span> npick</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> list -> 'a list <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">npick l</code> is the same as <a href="Lwt.html#VALnchoose"><code class="code"><span class="constructor">Lwt</span>.nchoose</code></a>, except that it cancels all
      sleeping threads when one terminates.
<p>

      Note: <a href="Lwt.html#VALnpick"><code class="code"><span class="constructor">Lwt</span>.npick</code></a> leaves the local values of the current thread
      unchanged.<br>
</div>

<pre><span id="VALprotected"><span class="keyword">val</span> protected</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> -> 'a <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">protected thread</code> creates a new cancelable thread which behave
      as <code class="code">thread</code> except that cancelling it does not cancel
      <code class="code">thread</code>.<br>
</div>

<pre><span id="VALno_cancel"><span class="keyword">val</span> no_cancel</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> -> 'a <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">no_cancel thread</code> creates a thread which behave as <code class="code">thread</code>
      except that it cannot be canceled.<br>
</div>
<br>
<h2 id="2_Pause">Pause</h2><br>

<pre><span id="VALpause"><span class="keyword">val</span> pause</span> : <code class="type">unit -> unit <a href="Lwt.html#TYPEt">t</a></code></pre><div class="info ">
<code class="code">pause ()</code> is a sleeping thread which is wake up on the next
      call to <a href="Lwt.html#VALwakeup_paused"><code class="code"><span class="constructor">Lwt</span>.wakeup_paused</code></a>. A thread created with <code class="code">pause</code> can be
      canceled.<br>
</div>

<pre><span id="VALwakeup_paused"><span class="keyword">val</span> wakeup_paused</span> : <code class="type">unit -> unit</code></pre><div class="info ">
<code class="code">wakeup_paused ()</code> wakes up all threads which suspended
      themselves with <a href="Lwt.html#VALpause"><code class="code"><span class="constructor">Lwt</span>.pause</code></a>.
<p>

      This function is called by the scheduler, before entering the
      main loop. You usually do not have to call it directly, except
      if you are writing a custom scheduler.
<p>

      Note that if a paused thread resumes and pauses again, it will not
      be woken up at this point.<br>
</div>

<pre><span id="VALpaused_count"><span class="keyword">val</span> paused_count</span> : <code class="type">unit -> int</code></pre><div class="info ">
<code class="code">paused_count ()</code> returns the number of currently paused
      threads.<br>
</div>

<pre><span id="VALregister_pause_notifier"><span class="keyword">val</span> register_pause_notifier</span> : <code class="type">(int -> unit) -> unit</code></pre><div class="info ">
<code class="code">register_pause_notifier f</code> register a function <code class="code">f</code> that will be
      called each time pause is called. The parameter passed to <code class="code">f</code> is
      the new number of threads paused. It is usefull to be able to
      call <a href="Lwt.html#VALwakeup_paused"><code class="code"><span class="constructor">Lwt</span>.wakeup_paused</code></a> when there is no scheduler<br>
</div>
<br>
<h2 id="2_Misc">Misc</h2><br>

<pre><span id="VALon_success"><span class="keyword">val</span> on_success</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> -> ('a -> unit) -> unit</code></pre><div class="info ">
<code class="code">on_success t f</code> executes <code class="code">f</code> when <code class="code">t</code> terminates without
      failing. If <code class="code">f</code> raises an exception it is given to
      <a href="Lwt.html#VALasync_exception_hook"><code class="code"><span class="constructor">Lwt</span>.async_exception_hook</code></a>.<br>
</div>

<pre><span id="VALon_failure"><span class="keyword">val</span> on_failure</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> -> (exn -> unit) -> unit</code></pre><div class="info ">
<code class="code">on_failure t f</code> executes <code class="code">f</code> when <code class="code">t</code> terminates and fails. If
      <code class="code">f</code> raises an exception it is given to
      <a href="Lwt.html#VALasync_exception_hook"><code class="code"><span class="constructor">Lwt</span>.async_exception_hook</code></a>.<br>
</div>

<pre><span id="VALon_termination"><span class="keyword">val</span> on_termination</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> -> (unit -> unit) -> unit</code></pre><div class="info ">
<code class="code">on_termination t f</code> executes <code class="code">f</code> when <code class="code">t</code> terminates. If <code class="code">f</code>
      raises an exception it is given to <a href="Lwt.html#VALasync_exception_hook"><code class="code"><span class="constructor">Lwt</span>.async_exception_hook</code></a>.<br>
</div>

<pre><span id="VALon_any"><span class="keyword">val</span> on_any</span> : <code class="type">'a <a href="Lwt.html#TYPEt">t</a> -> ('a -> unit) -> (exn -> unit) -> unit</code></pre><div class="info ">
<code class="code">on_any t f g</code> executes <code class="code">f</code> or <code class="code">g</code> when <code class="code">t</code> terminates. If <code class="code">f</code>
      or <code class="code">g</code> raises an exception it is given to
      <a href="Lwt.html#VALasync_exception_hook"><code class="code"><span class="constructor">Lwt</span>.async_exception_hook</code></a>.<br>
</div>

<pre><span class="keyword">module</span> <a href="Lwt.Infix.html">Infix</a>: <code class="code"><span class="keyword">sig</span></code> <a href="Lwt.Infix.html">..</a> <code class="code"><span class="keyword">end</span></code></pre><div class="info">
Infix operators.
</div>
</body></html>
liblwt-ocaml-doc 2.5.2-1 / usr / share / doc / liblwt-ocaml-dev / api / Lwt.html
