Clarify the semantics of Flow.write when the buffer is full

[samoht]

In Fflow.write will fill the buffer and return eof if the buffer is full. Lwt_io_flow.write will fill the buffer and then block. One of them is wrong and need to be fixed.

[hannesm]

Sorry to hijack this issue, but I stumbled upon a similar issue: mirage-console is a FLOW, and it would be great to have its error behaviour well documented... what should happen if Mirage_console.write can only do a partial write (which may be the case if the underlying socket is a unix domain socket)?

The implementations differ:

• unix uses Lwt_cstruct.complete (and thus loops till all the bytes are written)
• xen loops manually until all the bytes are written
• solo5 uses solo5_console_write via mirage-solo5 from solo5, but discards the returned int (which is the number of bytes written)

The majority (of console implementations) is in favor of blocking until all bytes are written. It would IMHO be very sensible to have a common behaviour amongst all implementations of write -- is there anything depending on @samoht mentioned "returns eof" anyone is aware of?

[hannesm]

//cc @mato

ups, looking deeper into solo5, it turns out that console_write is using the hypercall puts, which is implemented to return void (and int platform_puts () returns the string length):

    int rc = write(1, UKVM_CHECKED_GPA_P(hv, p->data, p->len), p->len);
    assert(rc >= 0);

[hannesm]

I have a fix proposal for the issue I mentioned above, spanning over 3 PRs: Solo5/solo5#196 mirage/mirage-solo5#19 mirage/mirage-console-solo5#12

[hannesm]

This is pretty old issue, but for network streams my opinion is that write should block when the buffer is full. Otherwise you've some task that isn't aware of what to do and when to continue. If the underlying transport is closed, a `Closed error should be returned.

Indeed, we should clarify this in the documentation.

[hannesm]

adressed in 7a4eb61 - the call to write blocks until the buffer has been accepted by the implementation. no partial writes.