package iomux

Io Multiplexers for Ocaml

API ONLINE^W^W

This aims to provide very direct, as in low level bindings to poll(2), ppoll(2), kevent(2) and epoll(2). At this time just poll(2) and ppoll(2) are implemented.

Poll & Ppoll

Poll and ppoll are the second generation of IO multiplexers, they're mostly the same, but ppoll takes nanoseconds as a timeout and allows for a list of signals to be masked atomically. Most people will be happier with poll.

This binding operates by maintaining an opaque buffer of fd slots. You access the internal buffer via Poll.set_index, Poll.get_fd, Poll.get_revents etc. These will just fill the pollfd structure at the given index. It's way easier to grasp this if you read the poll(2) manpage first.

A very basic usage would be something like this. We create a pipe, and we want to poll for reading on input and writing on output.

let poll = Poll.create () in
let pipe_r, pipe_w = Unix.pipe () in
(* We'll use index 0 for the pipe, and 7 for pipe output, just because.
   First we want to make sure we can write to the pipe without blocking *)
Poll.set_index poll 7 pipe_w Poll.Flags.pollout;
(* Wait why 8 ? we tell the kernel the number of file descriptors to scan,
   unset filedescriptors are skipped, so indexes 1-6 are ignored *)
let nready = Poll.poll poll 8 Nowait in
assert (nready = 1); (* only one entry should be ready, since we added only one *)
let n = Unix.write pipe_w (Bytes.create 1) 0 1 in
assert (n = 1);
(* We'll now poll for both events, note that we don't need to re-add index 7 *)
Poll.set_index poll 0 pipe_r Poll.Flags.pollin;
let nready = Poll.poll poll 8 Nowait in
assert (nready = 2); (* pipe input + pipe output *)
Poll.iter_ready poll nready (fun index fd flags ->
    if Poll.Flags.mem flags Poll.Flags.pollin then
      Printf.printf "fd %d (from index %d) can be read without blocking\n%!"
        (Util.fd_of_unix fd) index
    else if Poll.Flags.mem flags Poll.Flags.pollout then
      Printf.printf "fd %d (from index %d) can be written without blocking\n%!"
        (Util.fd_of_unix fd) index
    else
      assert false);
Unix.close pipe_r;
Unix.close pipe_w;
(* clean up *)
Poll.invalidate_index poll 0;
Poll.invalidate_index poll 7

Should produce:

fd 3 (from index 0) can be read without blocking
fd 4 (from index 7) can be written without blocking

This interface might look a bit weird, but it does zero allocations per set or get and only one block allocation per actual poll or ppoll.