lwt_glib

GLib integration for Lwt
README

Lwt is OCaml's concurrent programming library. It provides a single data type:
the promise, 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.

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.

Here is a simplistic Lwt program which requests the Google front page, and fails
if the request is not completed in five seconds:

let () =
  let request =
    let%lwt addresses = Lwt_unix.getaddrinfo "google.com" "80" [] in
    let google = (List.hd addresses).Lwt_unix.ai_addr in

    Lwt_io.(with_connection google (fun (incoming, outgoing) ->
      let%lwt () = write outgoing "GET / HTTP/1.1\r\n" in
      let%lwt () = write outgoing "Connection: close\r\n\r\n" in
      let%lwt response = read incoming in
      Lwt.return (Some response)))
  in

  let timeout =
    let%lwt () = 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 -package lwt.ppx -linkpkg -o request example.ml
   ./request *)

In the program, functions such as Lwt_io.write create promises. The
let%lwt ... in construct is used to wait for a promise to become determined;
the code after in is scheduled to run in a "callback." Lwt.pick races
promises against each other, and behaves as the first one to complete.
Lwt_main.run 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.

Installing

  1. Use your system package manager to install a development libev package,
    often called libev-dev or libev-devel.

  2. opam install conf-libev lwt

Documentation

We are currently working on improving the Lwt documentation (drastically; we are
rewriting the manual). In the meantime:

  • The current manual can be found here.

  • Mirage has a nicely-written Lwt tutorial.

  • An example of a simple server written in Lwt.

  • Concurrent Programming with Lwt is a great source of Lwt examples.
    They are translations of code from the excellent Real World OCaml, but are
    just as useful if you are not reading the book.

  • Some examples are also available in Lwt's doc/examples.

Note: much of the current manual refers to 'a Lwt.t as "lightweight threads"
or just "threads." This will be fixed in the new manual. 'a Lwt.t is a
promise, and has nothing to do with system or preemptive threads.

Contact

Open an issue, visit Gitter chat, ask in #ocaml,
on discuss.ocaml.org, or on Stack Overflow. Please do ask!
Even apparently simple questions often end up educating other users, not to
mention enlightening the maintainers!

Subscribe to the announcements issue to get news about Lwt
releases. It is less noisy than watching the whole repository. Announcements are
also made in /r/ocaml, on the OCaml mailing list, and on
discuss.ocaml.org.

Contributing

What counts as a contribution to Lwt? All kinds of things make the project
better, and are very much appreciated:

  • Asking anything. This helps everyone understand Lwt, including
    long-time maintainers!

  • Making or requesting edits to the docs, or just reading
    them.

  • Reading any issue or PR, and, optionally, adding your
    opinion or requesting clarification.

  • Explaining how to make Lwt easier to contribute to, finding problems with the
    contributing docs, etc.

  • Helping other people with Lwt, whether in this repo, or elsewhere in the
    world.

  • Writing or clarifying test cases.

  • And, of course, the traditional kind of contribution, picking up
    issues and writing code :)

Contributing to Lwt is not only for OCaml "experts!" If you are near the
beginning of your OCaml journey, we'd love to give you a little help by
recommending appropriate issues, or even just chatting about Lwt or OCaml.
Newcomers make valuable contributions, that maintainers often learn from – not
the least because newcomers bring a fresh, valuable perspective :) Don't be
afraid to ask anything.

We hope you'll join us to work in a friendly community around Lwt :) On behalf
of all users of, and contributors to, Lwt: Thank you! :tada:

Resources

There are several resources to help you get started:

  • If you'd like to ask a question, or otherwise talk, there is the
    contact information.

  • Lwt maintains a list of easy issues, which you can use to try
    out the code contribution workflow. This list works two ways! Please
    contribute to it: if you find something that needs a fix, open an issue. It
    might be an easy issue that another contributor would love to solve :)

  • CONTRIBUTING.md contains optional tips for working on the
    code of Lwt, instructions on how to check the code out, and a high-level
    outline of the code base.

  • The project roadmap contains a list of long-term, large-scale
    projects, so you can get an idea of where Lwt is headed, as a whole. Planned
    upcoming releases are also listed there.

  • Watch this repository :)

License

Lwt is released under the LGPL, with an OpenSSL linking exception. See
COPYING.

Install
Published
21 Jul 2017
Sources
3.1.0.tar.gz
md5=e80364e38c5fae791a6506b9c113fd29
Dependencies
Reverse Dependencies