Design notes

Well formed streams

The design tries to enforce well-formed streams as a sequence of non-empty slices terminated by Bytesrw.Bytes.Slice.eod. We want to ensure that read and write functions of stream readers and writers are not called with unexpected empty slices or that they are called after they returned or were called with Bytesrw.Bytes.Slice.eod.

For example the Bytesrw.Bytes.Slice creation functions raise Invalid_argument when they unexpectedly produce an empty slice and those that can produce them have dedicated names that include _eod to make users and code readers aware that this might terminate the stream.

Also readers and writers internally overwrite their read and write function as soon as Bytesrw.Bytes.Slice.eod is seen so that no closure are kept longer than it should be.

Error strategy

The error strategy may look involved but it caters for:

while retaining the ability to pattern match on the error of specific streams and making sure informative human error messages can always be produced.

For users it means that when they use streams:

To enforce good behaviour by stream reader and writers the following type structure is used:

Effectively this system can be seen as an OCaml-like exception system inside the Bytesrw.Bytes.Stream.Error exception.

Signature of read/write primitives



If we determine that this API works well we should consider proposing to upstream the extension of Bytesrw.Bytes. The core code is mostly trivial it's "just" three data structures. But added code is more code to maintain.

However here are a few things to consider: