glennsl/luv

Cross-platform asynchronous I/O and system calls

Luv   

Luv is an OCaml/ReasonML 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;

  Luv.Loop.run () |> ignore

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, and are otherwise referenced only by C callbacks.
• The OCaml runtime lock — multithreaded Luv programs are safe.
• 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.

Basically, when wrapped in Luv, libuv looks like any normal OCaml library, with the kind of usage functional programmers expect.

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, building 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.

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 ();;

Future

• A "post-compose" functor that applies a transformation to the whole API, for globally converting callbacks to promises, changing the error handling strategy, etc. Prototype was here.
• Integration with Lwt. There was an old example that used the early post-compose functor and a Luv-based Lwt event loop.
• Luv could make multithreaded event-driven programming very easy by lazily initializing a loop for each thread, and storing the reference to it in a TLS key that Luv uses internally. This could be especially powerful once OCaml has a genuine multicore runtime.
• let* operators for convenient chaining of callbacks.

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.