Add stream-status to stream write return values, and expand documentation

[pchickey]

Documentation focuses on how the non-blocking read and write functions respond when not ready for reading/writing, and how that maps to pollable.

stream-error is now a record with a dummy member, to follow the new component model excluding zero-sized types.

stream-error has been eliminated, since we can't determine any error value to provide there. All fallible funcs simply return result<ok> now, which can still represent an error but without any error type as the payload.

For more context on these changes: I designed and implemented them as part of bytecodealliance/wasmtime#6556

[badeend]

Could you briefly explain why writing to a closed stream is now explicitly permitted? This isn't obvious to me. What happens to the written data?

[pchickey]

The write end of a stream is a mechanism for the reader to tell the writer that it won't be reading any more input. The writer is still welcome to send input, but it will be dropped because no reader exists.

In many existing codebases when the reader doesn't care to read any more input, it may simply stop reading and won't close the stream. So, there is never a guarantee that something written ends up being read - we are exposing this as a mechanism to allow optimizing the writer.

libc might choose to translate this into EPIPE when appropriate, or even emulate a SIGPIPE exit when appropriate (e.g. on stdin). (I'm not a libc expert but those are Dan's suggestions.)

This feels to me like a weaker condition than an error, so I think its a case where we can be liberal in what we accept - its easy enough to let the writer keep writing and drop its input, if it doesn't honor the flag indicating the stream has closed.

[badeend]

All clear to me now. Thanks.

[pchickey]

We've been having some issues with the write backpressure design and I've come around to the opposite view on this topic... I'm working on the design and implementation of a different approach now which I intend will replace this PR.

[badeend]

Is this constraint specific to streams and their pollables, or do you see this as a general pattern where there is a parent/child relationship between resources?

For example, do you foresee a similar constraint on the Drop method of file descriptors, stating it may trap if a child directory-entry-stream, input-stream or output-stream is still open?

[pchickey]

The general pattern where one resource might be the child of another resource is something we aim to make possible to describe in the component model type system, but we aren't ready to do so in the preview 2 time frame.

We didn't find that this child constraint was appropriate for the streams of files. The way I drew the line was, "is this resource useful after its parent has been dropped?". With pollables of streams, readiness is telling you something particular about the stream itself: it doesn't mean anything without a stream to try reading from/writing to. On the other hand, with files, a descriptor is a "full" view of all the capabilities possible, but if you just care about reading out the contents of a directory or file, its reasonable to just "narrow" your view to the particular stream you care about, and drop the descriptor because you don't care about any other operations.

So: interfaces can decide that a resource is a child of another resource when appropriate, and for now they have to communicate that with docs, and hopefully one day with types. Not all resources will be the child of another resource.

[badeend]

Ah nice. Hadn't thought about it that way.

I completely agree.