mirror of
https://github.com/c-cube/linol.git
synced 2025-12-06 03:05:31 -05:00
25 lines
9.3 KiB
HTML
25 lines
9.3 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>index (lwt.index)</title><meta charset="utf-8"/><link rel="stylesheet" href="../_odoc-theme/odoc.css"/><meta name="generator" content="odoc 3.1.0"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – <a href="../index.html">Index</a> » lwt</nav><header class="odoc-preamble"><h1 id="package-lwt"><a href="#package-lwt" class="anchor"></a>Package lwt <nav><a type="text/plain; charset=UTF-8" href="_doc-dir/CHANGES">changes</a> <a href="#package_info">more…</a></nav></h1></header><div class="odoc-tocs"><nav class="odoc-toc odoc-local-toc"><ul><li><a href="#introduction">Introduction</a></li><li><a href="#tour">Tour</a></li><li><a href="#installing">Installing</a></li><li><a href="#additional-docs">Additional Docs</a></li><li><a href="#api:-library-lwt">API: Library <code>lwt</code></a></li><li><a href="#api:-library-lwt.unix">API: Library <code>lwt.unix</code></a></li><li><a href="#package_info">Package info</a></li></ul></nav></div><div class="odoc-content"><h2 id="introduction"><a href="#introduction" class="anchor"></a>Introduction</h2><p>Lwt is a concurrent programming library for OCaml. It provides a single data type: the <em>promise</em>, which is a value that will become determined in the future. Creating a promise spawns a computation. When that computation is I/O, Lwt runs it in parallel with your OCaml code.</p><p>OCaml code, including creating and waiting on promises, is run in a single thread by default, so you don't have to worry about locking or preemption. You can detach code to be run in separate threads on an opt-in basis.</p><p>Here is a simplistic Lwt program which requests the Google front page, and fails if the request is not completed in five seconds:</p><pre class="language-ocaml"><code>open Lwt.Syntax
|
||
|
||
let () =
|
||
let request =
|
||
let* addresses = Lwt_unix.getaddrinfo "google.com" "80" [] in
|
||
let google = Lwt_unix.((List.hd addresses).ai_addr) in
|
||
|
||
Lwt_io.(with_connection google (fun (incoming, outgoing) ->
|
||
let* () = write outgoing "GET / HTTP/1.1\r\n" in
|
||
let* () = write outgoing "Connection: close\r\n\r\n" in
|
||
let* response = read incoming in
|
||
Lwt.return (Some response)))
|
||
in
|
||
|
||
let timeout =
|
||
let* () = Lwt_unix.sleep 5. in
|
||
Lwt.return None
|
||
in
|
||
|
||
match Lwt_main.run (Lwt.pick [request; timeout]) with
|
||
| Some response -> print_string response
|
||
| None -> prerr_endline "Request timed out"; exit 1
|
||
|
||
(* ocamlfind opt -package lwt.unix -linkpkg example.ml && ./a.out *)</code></pre><p>In the program, functions such as <code>Lwt_io.write</code> create promises. The <code>let%lwt ... in</code> construct is used to wait for a promise to become determined; the code after <code>in</code> is scheduled to run in a "callback." <code>Lwt.pick</code> races promises against each other, and behaves as the first one to complete. <code>Lwt_main.run</code> forces the whole promise-computation network to be executed. All the visible OCaml code is run in a single thread, but Lwt internally uses a combination of worker threads and non-blocking file descriptors to resolve in parallel the promises that do I/O.</p><h2 id="tour"><a href="#tour" class="anchor"></a>Tour</h2><p>Lwt compiles to native code on Linux, macOS, Windows, and other systems. It's also routinely compiled to JavaScript for the front end and Node by js_of_ocaml.</p><p>In Lwt,</p><ul><li>The core library <a href="Lwt/index.html"><code>Lwt</code></a> provides promises...</li><li>...and a few pure-OCaml helpers, such as promise-friendly <a href="Lwt_mutex/index.html" title="Lwt_mutex">mutexes</a>, <a href="Lwt_condition/index.html" title="Lwt_condition">condition variables</a>, and <a href="Lwt_mvar/index.html" title="Lwt_mvar">mvars</a>.</li><li>There is a big Unix binding, <a href="Lwt_unix/index.html"><code>Lwt_unix</code></a>, that binds almost every Unix system call. A higher-level module <a href="Lwt_io/index.html"><code>Lwt_io</code></a> provides nice I/O channels.</li><li><a href="Lwt_process/index.html"><code>Lwt_process</code></a> is for subprocess handling.</li><li><a href="Lwt_preemptive/index.html"><code>Lwt_preemptive</code></a> spawns system threads.</li></ul><h2 id="installing"><a href="#installing" class="anchor"></a>Installing</h2><ol><li>Use your system package manager to install a development libev package. It is often called <code>libev-dev</code> or <code>libev-devel</code>.</li><li><code>opam install conf-libev lwt</code></li></ol><h2 id="additional-docs"><a href="#additional-docs" class="anchor"></a>Additional Docs</h2><ul><li><a href="manual.html" title="manual">Manual</a> (<a href="https://ocsigen.org/lwt/">Online manual</a>).</li><li><a href="https://github.com/dkim/rwo-lwt#readme">Concurrent Programming with Lwt</a> is a nice source of Lwt examples. They are translations of code from Real World OCaml, but are just as useful if you are not reading the book.</li><li><a href="https://mirage.io/docs/tutorial-lwt">Mirage Lwt tutorial</a>.</li><li><a href="https://baturin.org/code/lwt-counter-server/">Example server</a> written with Lwt.</li></ul><h2 id="api:-library-lwt"><a href="#api:-library-lwt" class="anchor"></a>API: Library <code>lwt</code></h2><p>This is the system-independent, pure-OCaml core of Lwt. To link with it, use <code>(libraries lwt)</code> in your <code>dune</code> file.</p><ul class="modules"><li><a href="Lwt/index.html"><code>Lwt</code></a> <span class="synopsis">Asynchronous programming with promises.</span></li><li><a href="Lwt_list/index.html"><code>Lwt_list</code></a> <span class="synopsis">List helpers</span></li><li><a href="Lwt_stream/index.html"><code>Lwt_stream</code></a> <span class="synopsis">Data streams</span></li><li><a href="Lwt_result/index.html"><code>Lwt_result</code></a> <span class="synopsis">Explicit error handling</span></li><li><a href="Lwt_mutex/index.html"><code>Lwt_mutex</code></a> <span class="synopsis">Cooperative locks for mutual exclusion</span></li><li><a href="Lwt_condition/index.html"><code>Lwt_condition</code></a> <span class="synopsis">Conditions</span></li><li><a href="Lwt_mvar/index.html"><code>Lwt_mvar</code></a> <span class="synopsis">Mailbox variables</span></li><li><a href="Lwt_switch/index.html"><code>Lwt_switch</code></a> <span class="synopsis">Lwt switches</span></li><li><a href="Lwt_pool/index.html"><code>Lwt_pool</code></a> <span class="synopsis">External resource pools.</span></li></ul><h2 id="api:-library-lwt.unix"><a href="#api:-library-lwt.unix" class="anchor"></a>API: Library <code>lwt.unix</code></h2><p>This is the system call and I/O library. Despite its name, it is implemented on both Unix-like systems and Windows, although not all functions are available on Windows. To link with this library, use <code>(libraries lwt.unix)</code> in your <code>dune</code> file.</p><ul class="modules"><li><a href="Lwt_unix/index.html"><code>Lwt_unix</code></a> <span class="synopsis">Cooperative system calls</span></li><li><a href="Lwt_main/index.html"><code>Lwt_main</code></a> <span class="synopsis">Main loop and event queue</span></li><li><a href="Lwt_io/index.html"><code>Lwt_io</code></a> <span class="synopsis">Buffered byte channels</span></li><li><a href="Lwt_process/index.html"><code>Lwt_process</code></a> <span class="synopsis">Process management</span></li><li><a href="Lwt_bytes/index.html"><code>Lwt_bytes</code></a> <span class="synopsis">Byte arrays</span></li><li><a href="Lwt_preemptive/index.html"><code>Lwt_preemptive</code></a> <span class="synopsis">This module allows to mix preemptive threads with <code>Lwt</code> cooperative threads. It maintains an extensible pool of preemptive threads to which you can detach computations.</span></li><li><a href="Lwt_fmt/index.html"><code>Lwt_fmt</code></a> <span class="synopsis">Format API for Lwt-powered IOs</span></li><li><a href="Lwt_throttle/index.html"><code>Lwt_throttle</code></a> <span class="synopsis">Rate limiters.</span></li><li><a href="Lwt_timeout/index.html"><code>Lwt_timeout</code></a> <span class="synopsis">Cancelable timeouts.</span></li><li><a href="Lwt_engine/index.html"><code>Lwt_engine</code></a> <span class="synopsis">Lwt unix main loop engine</span></li><li><a href="Lwt_gc/index.html"><code>Lwt_gc</code></a> <span class="synopsis">Interaction with the garbage collector</span></li><li><a href="Lwt_sys/index.html"><code>Lwt_sys</code></a> <span class="synopsis">System informations.</span></li></ul><h2 id="package_info"><a href="#package_info" class="anchor"></a>Package info</h2><table class="package info"><tr id="info-changes-files"><td><a href="#info-changes-files" aria-hidden="true" class="anchor"></a>changes-files</td><td><ul><li><a type="text/plain; charset=UTF-8" href="_doc-dir/CHANGES">CHANGES</a></li></ul></td></tr><tr id="info-license-files"><td><a href="#info-license-files" aria-hidden="true" class="anchor"></a>license-files</td><td><ul><li><a type="text/plain; charset=UTF-8" href="_doc-dir/LICENSE.md">LICENSE.md</a></li></ul></td></tr><tr id="info-readme-files"><td><a href="#info-readme-files" aria-hidden="true" class="anchor"></a>readme-files</td><td><ul><li><a type="text/plain; charset=UTF-8" href="_doc-dir/README.md">README.md</a></li></ul></td></tr></table></div></body></html>
|