Luv is a neatly-packaged OCaml/Reason binding to libuv, the
cross-platform C library that does asynchronous I/O in Node.js and runs Node's
main loop.

Here's an example, which retrieves the Google search page:

let () =
  Luv.DNS.getaddrinfo ~family:`INET ~node:"google.com" ~service:"80" ()
      begin fun result ->

    let address = (List.hd (Result.get_ok result)).addr in
    let socket = Luv.TCP.init () |> Result.get_ok in
    Luv.TCP.connect socket address begin fun _ ->

      Luv.Stream.write socket [Luv.Buffer.from_string "GET / HTTP/1.1\r\n\r\n"]
        (fun _ _ -> Luv.Stream.shutdown socket ignore);

      Luv.Stream.read_start socket (function
        | Error `EOF -> Luv.Handle.close socket ignore
        | Error _ -> exit 2
        | Ok response -> print_string (Luv.Buffer.to_string response))

    end
  end;

  ignore (Luv.Loop.run () : bool)

libuv does more than just asynchronous I/O. It also supports
multiprocessing and multithreading. You can even run
multiple async I/O loops, in different threads. libuv wraps a lot of
other functionality, and exposes a comprehensive operating system API.

Indeed, Luv does not depend on Unix. It is an alternative operating
system API. Nonetheless, Luv and Unix can coexist readily in one program.

Because libuv is a major component of Node.js, it is
cross-platform and well-maintained. Luv, being a
fairly thin binding, inherits these properties.

Luv takes care of the tricky parts of dealing with libuv from OCaml:

• Memory management — Luv keeps track of OCaml objects that have been
  passed to libuv, so that they don't get collected too early by the GC.

• The runtime lock — multithreaded Luv programs don't wreck the OCaml
  runtime.

• 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 internally builds libuv, so
  users don't have to figure out how to do it.

• Linking — a specific release of libuv is statically linked into
  your program together with Luv, and there is no dependency on a system
  installation of libuv.

Basically, when wrapped in Luv, libuv looks like any normal OCaml library you
might install from opam or using esy. In a loose sense, libuv is just an
implementation detail of Luv — though, indeed, a very powerful one.

One of the design goals of Luv is to be easy to integrate into larger libraries,
such as Lwt. To that end, Luv is...

• Minimalist — Luv only takes care of inherent libuv headaches, such
  as memory management, adding as little else 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 thoroughly tested. Apart from checking return values and I/O
effects, the test cases also check for memory leaks, invalid references, and
potential issues with multithreading.

Installing

opam install luv

If using esy, add

"dependencies": {
  "@opam/luv": "*"
}

Documentation

• User guide

• API reference

• Examples — explained in the user guide.

• libuv manual

Experimenting

You can run any example by cloning the repo:

git clone https://github.com/aantron/luv.git --recursive
cd luv
opam install --deps-only .

Note: the clone has to be recursive, because libuv is vendored using a git
module. Also, the examples require OCaml 4.08+.

Then, to run, say, delay.ml...

dune exec example/delay.exe

The first time you do this, it will take a couple minutes, because Luv will
build libuv.

You can add your own experiments to the example/ directory. To run
them, add the module name to example/dune, and then run them
like any other example:

dune exec example/my_test.exe

Alternatively, you can try Luv in a REPL by installing utop:

opam install --unset-root utop
dune utop

Once you get the REPL prompt, try running Luv.Env.environ ();;

External libuv

You can tell Luv to ignore its vendored libuv, and build against an external one
by setting LUV_USE_SYSTEM_LIBUV=yes during the build. This requires libuv to
be findable by -luv, uv.h to be in the header path, and the Luv version to
be at least 0.5.7.

The external libuv can be considerably older than what Luv vendors — at
the moment, Luv supports compilation against libuv versions all the way down to
1.3.0, using a bunch of shims.

If you use an older libuv, you may want to look at the feature tests exposed by
Luv in auto-generated module Luv.Require. The one posted online was
generated for Luv's vendored libuv, so everything is present. If you use an
older libuv, some of the features will have type _false feature.

License

Luv has several pieces, with slightly different permissive licenses:

• Luv itself is under the MIT license.

• This repo links to libuv with a git submodule. However, a release archive will
  generally include the full libuv source. Portions of libuv are variously
  licensed under the MIT, 2-clause BSD, 3-clause BSD, and ISC
  licenses.

• The user guide is a very heavily reworked version of uvbook,
  originally by Nikhil Marathe, which was incorporated into the libuv docs as
  the libuv user guide, and made available under
  CC BY 4.0.