unikernel/duniverse/mirage-channel/README.md

@@ -0,0 +1,64 @@
+mirage-channel — Buffered channels for MirageOS FLOW types
+----------------------------------------------------------
+v5.0.0
+
+Channels are buffered reader/writers built on top of unbuffered `FLOW`
+implementations.
+
+Example:
+
+```ocaml
+module Channel = Channel.Make(Flow)
+...
+Channel.read_exactly ~len:16 t >>= function
+| Error read_error
+| Ok `Eof -> ...
+| Ok `Data bufs -> (* read header of message *)
+  let payload_length = Cstruct.(LE.get_uint16 (concat bufs) 0) in
+  Channel.read_exactly ~len:payload_length t >>= function
+  | Ok `Data bufs -> (* payload of message *)
+  | Ok `Eof -> ...
+  | Error read_error
+(* process message *)
+
+Channel.write_buffer t header;
+Channel.write_buffer t payload;
+Channel.flush t >>= function
+| Error write_error -> ...
+| Ok () -> ...
+```
+
+mirage-channel is distributed under the ISC license.
+
+* Homepage: https://github.com/mirage/mirage-channel
+* Issue: <https://github.com/mirage/mirage-channel/issues>
+* Contact: `<mirageos-devel@lists.xenproject.org>`
+
+## Installation
+
+mirage-channel can be installed with `opam`:
+
+    opam install mirage-channel
+
+If you don't use `opam` consult the [`opam`](opam) file for build
+instructions.
+
+## Documentation
+
+The documentation and API reference is automatically generated by
+`ocamldoc` from the interfaces. It can be consulted [online][doc]
+and there is a generated version in the `doc` directory of the
+distribution.
+
+[doc]: http://docs.mirage.io/channel
+
+## Sample programs
+
+If you installed mirage-channel with `opam` sample programs are located in
+the directory `opam config var channel:doc`.
+
+In the distribution sample programs and tests are located in the
+[`test`](test) directory of the distribution. They can be built with:
+
+    dune runtest
+