Skip to content
Minimalist OCaml binding to libuv
OCaml C Other
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
example Add license headers to source files Feb 23, 2019
src Fix warnings for 4.08 Jul 26, 2019
test Fix warnings for 4.08 Jul 26, 2019
.gitignore Development Oct 11, 2018
.gitmodules Initial commit Jul 17, 2018
.travis.yml
LICENSE.md Update copyright year Jul 25, 2019
Makefile Fix warnings for 4.08 Jul 26, 2019
README.md README: fix libuv version Jul 13, 2019
dune-project Development Oct 11, 2018
luv.opam Dune should no longer be tagged build-only Jul 30, 2019
luv_lwt.opam luv_lwt.opam, luv_repromise.opam: depend on ocaml Jul 30, 2019
luv_repromise.opam luv_lwt.opam, luv_repromise.opam: depend on ocaml Jul 30, 2019

README.md

Luv

What is Luv?

Luv is a binding from OCaml/ReasonML to libuv. It looks like this:

let _ =
  (* Create a 1-second timer. *)
  let Ok timer = Luv.Timer.init () in
  Luv.Timer.start timer 1000 (fun () -> print_endline "Hello, world!");

  (* Run the main loop. *)
  Luv.Loop.(run (default ()) Run_mode.default)

(* ocamlfind opt -linkpkg -package luv foo.ml *)

What is libuv?

libuv is the C library in Node.js that runs Node's event loop and does its asynchronous I/O.



Because libuv is critical to Node.js, it is cross-platform and well-maintained. Luv inherits these properties, taking care of the tricky parts of calling into libuv from OCaml:

  • Memory management — Luv keeps track of OCaml objects that have been passed to libuv, and are no longer otherwise retained on the OCaml side.
  • The runtime lock — Multithreaded OCaml and libuv programs operate normally.
  • API problems — Where libuv is forced to offer difficult APIs due to the limitations of C, Luv provides more natural APIs.
  • The build — When Luv is installed, it builds libuv, so users don't have to figure out how to do it.

Luv is usable standalone, but its main purpose is to be integrated as a back end into bigger I/O libraries, such as Repromise and Lwt. To that end, Luv aims to be...

  • Minimalist — Luv only takes care of inherent libuv headaches, such as memory management, building as little as possible over libuv.
  • Unopinionated — Luv avoids committing to design decisions beyond those dictated by libuv and OCaml.
  • Maintainable — Luv uses Ctypes to minimize the amount of C code in this repo, and vendors libuv to avoid versioning issues.

Luv is well-tested. Apart from checking return values and I/O behavior, the test cases also check for memory leaks, lost references, and potential issues with multithreading.


Status

Luv is an early alpha at this point. The binding covers the full libuv API (with a few exceptions), but the library might not build in various circumstances, lacks docs, etc. This will all be addressed in upcoming development.


Trying

git clone --recurse-submodules https://github.com/aantron/luv.git
cd luv
opam install --unset-root alcotest ctypes dune result
make test
dune exec example/http_get/http_get.exe -- www.google.com

You can try the Luv+Lwt HTTP GET example by installing a couple more dependencies:

opam install --unset-root lwt lwt_ppx
dune exec example/http_get_lwt/http_get_lwt.exe -- www.google.com

Or, for the Repromise version:

opam install --unset-root repromise
dune exec example/http_get_repromise/http_get_repromise.exe -- www.google.com

Luv probably doesn't work on Windows at the moment. The code is actually highly portable, but it is likely there are minor bugs and oversights, due to a lack of testing on Windows. This is to be fixed in the near future :)


Documentation

Proper docs for Luv haven't been started yet. However, one can get a listing of the available OCaml modules by looking in luv.ml. The modules are listed in the same order as libuv's API docs list features. The general libuv docs can be found here.

We will eventually write and generate nice HTML docs for Luv itself, with plenty of links back to libuv :)

luv currently uses libuv 1.30.1.


Roadmap

  • esy packaging and build.
  • Proof-of-concept integration with Lwt and Repromise.
  • Vendor correctly Windows.
  • Documentation, examples, CI; user-friendly repo.
  • Look into using Luv for native Node.js modules.
You can’t perform that action at this time.