New backpressure and flushing scheme for output-stream #45
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
output-stream
's backpressure design has been changed to take into account that anywrite
call with alist<byte>
argument is going to consume the resources of a component implementation, by copying those bytes into the component's linear memory.Therefore, prior to a call to
write
, the user of this interface must first callcheck-write
to learn how many bytes the implementation will accept in a call towrite
. The check will return 0 bytes when calls to write are not accepted, as well as reporting with an error if the prior operation failed or the stream has closed. Thesubscribe-to-output-stream
pollable, which has always reported write readiness, will now become ready whenevercheck-write
will return a value other thanok(0)
.Flushing is a way to request & observe the completion of a write. Since the write itself is non-blocking, it may need to buffer writes and perform work in the background (in a component implementation, this would be during a call to
poll-oneoff
). The explicit flush call allows the user to wait for a write (or sequence of writes) to produce an error, or guarantee that it succeeded. After requesting a flush,check-write
returnok(0)
until the flush is complete, or an error has occured. Accordingly, thesubscribe-to-output-stream
pollable becomes ready when the flush is complete.Replacing
blocking-write
isblocking-write-and-flush
, because the combination of write and flush is what we have found many implementations (e.g. an implementation of posixwrite(2)
) require. Rather than participate in the new backpressure scheme,blocking-write-and-flush
always accepts a write of up to 4096 bytes at a time, a threshold that was picked to large enough to be useful for common cases such as stdio debugging prints, but small enough to not be a burdenfor the implementation.
blocking-flush
is also provided as a convenience function.Wasmtime implementation:
bytecodealliance/wasmtime#6877