Lwt: Test the Unix binding

[aantron]

NOTE: this will be much easier to work on after mirage/alcotest#177 and #701.

This is a big issue for lots of PRs. Some parts of it could be quite easy, but on the whole I'd say it is of medium difficulty.

Some care should be taken to run the tests properly sandboxed, i.e. files created in temporary directories, etc. For that, the test framework in test/test.ml will probably have to be extended with new helper functions. I'm not sure how to sandbox DNS and some of the other APIs. We should probably discuss that.

Besides correct behavior, we need really thorough tests for various error conditions. The typical system call has man pages on multiple systems, listing the various ways the system call can fail. We want to trigger as many of those as possible. See section Help below for links to man pages.

The work

To make this manageable, I would break the work into chunks, based on the current order of functions in the various .mli files of the Unix binding. These aren't listed necessarily in the order they should be tested in. We generally want simple and obvious things tested first, and more complex things that depend on them tested later.

There are a few tests already written, but I included all the functions in the category list, so make sure to check before choosing a category. I'll try to keep the check boxes up to date.

If you'd like to work on one of these items, please leave a comment, to avoid duplication of effort :)

• [x] Bigstrings. This is pure OCaml, and should be easy. (#619, by @cedlemo)
• [x] Sleeping and timeouts, probably best tested with the help of Unix.gettimeofday. (#630, by @cedlemo)
• [ ] [Lwt_throttle](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_throttle.mli). I guess this is in the Unix binding because it is aware of real time.
• [ ] [Lwt_timeout](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_timeout.mli).
• [ ] [Conversion form existing fds](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L186-L222). A basic test can just be a round-trip of a Unix fd, but really thorough testing here would have to exercise the optional arguments, and so this might depend on testing read or write first.
• [ ] [Blocking mode](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L224-L244).
• [ ] [Lwt_unix.close](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L353-L355), Lwt_unix.abort, and Lwt_unix.state.
• [ ] [Low-level subprocesses](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L257-L314).
• [ ] [Preemptive threading (Lwt_preemptive)](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_preemptive.mli).
• [ ] [Subprocesses (Lwt_process)](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_process.mli).
• [ ] [Standard I/O streams](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L318-L326). This could be as easy as applying Lwt_unix.unix_file_descr to them, and checking for equality with Unix.stdout, etc.
• [ ] [Lwt_unix.openfile](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L328-L351). This is tricky, because there are many options to test, some of them are platform-specific, etc.
• [ ] [Basic I/O](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L357-L393).
• [x] Vector I/O. This was already done when vector I/O was added in #291, but if you see more things to test, please test them :)
• [ ] [I/O status](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L497-L511).
• [ ] [Seeking](https://github.com/ocsigen/lwt/blob/master/src/unix/lwt_unix.cppo.mli#L513-L528); and for large files.
• [ ] [fsync](https://github.com/ocsigen/lwt/blob/master/src/unix/lwt_unix.cppo.mli#L530-L540).
• [ ] [fstat](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L542-L608); and for large files.
• [ ] [File names](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L664-L673).
• [ ] [Permissions](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L675-L697).
• [ ] [File descriptors](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L699-L711).
• [ ] [Directories](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L713-L765).
• [ ] [Pipes](https://github.com/ocsigen/lwt/blob/master/src/unix/lwt_unix.cppo.mli#L767-L784).
• [ ] [Symlinks](https://github.com/ocsigen/lwt/blob/master/src/unix/lwt_unix.cppo.mli#L786-L792).
• [ ] [lockf](https://github.com/ocsigen/lwt/blob/master/src/unix/lwt_unix.cppo.mli#L794-L806).
• [x] Users. (#673, by @anuragsoni)
• [ ] [Signals](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L846-L871).
• [ ] [Sockets](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L873-L1080). There are a lot of APIs in this category, and it's probably the most important I/O overall in modern programming.
• [x] Bigstring I/O. (#621, by @cedlemo)
• [x] Memory mapping. (#628, by @cedlemo)
• [x] Multicast. I believe we already have decent tests here, from #143.
• [ ] [DNS](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L1098-L1185).
• [ ] [Terminals](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L1187-L1267).
• [ ] [CPUs](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L1410-L1423).
• [ ] [Low-level interface](https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/src/unix/lwt_unix.cppo.mli#L1269-L1408). Among other things, this is used by external libraries to "plug into" Lwt.

I've left Lwt_io for a separate issue.

Help

Cheating off Unix

Some of the easiest ways to test some bindings would be to do something with Lwt_unix (or other Lwt module), and check the result using stdlib's Unix.

man pages

Here are some man page references:

• Linux
• Mac It seems Apple has archived their man pages and made them difficult to discover, so you have to do a web search for each system call.
• BSD
• For Windows, it's probably best to look at what Win32 API Lwt actually calls in src/unix/windows_c/*, and then look the API up in MSDN. A search is probably the easiest way.

Skipping tests

Many Lwt APIs aren't implemented on Windows. Tests for them can be skipped like this:

https://github.com/ocsigen/lwt/blob/4f0dabca5228b36a65ea7e49375a15d2070161fa/test/unix/test_lwt_process.ml#L27

Coverage analysis

Coverage analysis is enabled for the OCaml code of the Unix binding – run make coverage, then open _coverage/index.html. This can help to see what still needs testing, though some of the code is visited unintentionally because other code depends on it. We don't have coverage analysis for C code at the moment. That could be its own PR, but maybe it's not necessary.

Of course, high coverage doesn't imply thorough testing. Only low coverage implies insufficient testing.

cc @cedlemo

[cedlemo]

@aantron I will work on Bigstrings.

[cedlemo]

Now I will work on "sleeping and timeout".

[cedlemo]

I continue with Lwt_throttle.

[anuragsoni]

@aantron i've added some tests for unix Users (#673 )