From fe25c16dab4291f2b90cdc3a3ce4730970fa78c8 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Thu, 4 Sep 2025 08:46:37 -0700 Subject: [PATCH 1/3] [p3] Rename `wasi:cli/std{out,err}#set-std{out,err}` Use "append" instead of "set" to help indicate that the output of the stream is appended to stdout/stderr as opposed to only one stream being read at a time. --- wit-0.3.0-draft/stdio.wit | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/wit-0.3.0-draft/stdio.wit b/wit-0.3.0-draft/stdio.wit index 6c99a56..079ee88 100644 --- a/wit-0.3.0-draft/stdio.wit +++ b/wit-0.3.0-draft/stdio.wit @@ -7,11 +7,11 @@ interface stdin { @since(version = 0.3.0-rc-2025-08-15) interface stdout { @since(version = 0.3.0-rc-2025-08-15) - set-stdout: func(data: stream); + append-stdout: func(data: stream); } @since(version = 0.3.0-rc-2025-08-15) interface stderr { @since(version = 0.3.0-rc-2025-08-15) - set-stderr: func(data: stream); + append-stderr: func(data: stream); } From 1cb7c145f6b6c688325d6ba130bbcca242907766 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Thu, 4 Sep 2025 14:35:57 -0700 Subject: [PATCH 2/3] Add some comments --- wit-0.3.0-draft/stdio.wit | 52 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/wit-0.3.0-draft/stdio.wit b/wit-0.3.0-draft/stdio.wit index 079ee88..be1d878 100644 --- a/wit-0.3.0-draft/stdio.wit +++ b/wit-0.3.0-draft/stdio.wit @@ -1,17 +1,69 @@ @since(version = 0.3.0-rc-2025-08-15) interface stdin { + /// Gets the "stdin" of this component as a stream. + /// + /// This function returns a `stream` which is a byte-based async view + /// of the stdin to this component. What exactly stdin is depends on the + /// implementor but it could possibly be backed by any of the following: + /// + /// * A console terminal input + /// * A file via shell redirection + /// * Another stream from another component in virtualization scenarios + /// + /// This function can be called any number of times and all returned streams + /// will refer to the same I/O object that represents the stdin of this + /// component itself. Concurrent reads from separate streams are allowed + /// but it's unspecified which resolves first. + /// + /// If a read is started and then cancelled implementors need to guarantee + /// that no bytes are consumed from stdin. In other words if a read from the + /// stream returned here initiates a read somewhere else then cancelling + /// the original read should cancel this other read appropriately or buffer + /// the results. @since(version = 0.3.0-rc-2025-08-15) get-stdin: func() -> stream; } @since(version = 0.3.0-rc-2025-08-15) interface stdout { + /// Appends the provided stream of data to the "stdout" of this component. + /// + /// This function will cause the host/embedder to read from the `data` byte + /// stream provided and write the output to a component's stdout. What + /// exactly stdout is depends on the implementor but it could possibly be + /// backed by any of the following: + /// + /// * A console terminal screen + /// * A file via shell redirection + /// * Another stream from another component in virtualization scenarios + /// + /// Writes to stdout may be blocked if the system is unable to accept and/or + /// buffer any more bytes from stdout. Implementors are encouraged to only + /// complete a write once the bytes have been fully flushed out to the + /// destination in interactive situations as this API is frequently used + /// for debugging. @since(version = 0.3.0-rc-2025-08-15) append-stdout: func(data: stream); } @since(version = 0.3.0-rc-2025-08-15) interface stderr { + /// Appends the provided stream of data to the "stderr" of this component. + /// + /// This function will cause the host/embedder to read from the `data` byte + /// stream provided and write the output to a component's stderr. What + /// exactly stderr is depends on the implementor but it could possibly be + /// backed by any of the following: + /// + /// * A console terminal screen + /// * A file via shell redirection + /// * Another stream from another component in virtualization scenarios + /// + /// Writes to stderr may be blocked if the system is unable to accept and/or + /// buffer any more bytes from stderr. Implementors are encouraged to only + /// complete a write once the bytes have been fully flushed out to the + /// destination in interactive situations as this API is frequently used + /// for debugging. @since(version = 0.3.0-rc-2025-08-15) append-stderr: func(data: stream); } From 7f2e7999efda6cc9743aefe733eda504958e0622 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Tue, 9 Sep 2025 08:25:19 -0700 Subject: [PATCH 3/3] Clarify multi-call --- wit-0.3.0-draft/stdio.wit | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/wit-0.3.0-draft/stdio.wit b/wit-0.3.0-draft/stdio.wit index be1d878..66eb283 100644 --- a/wit-0.3.0-draft/stdio.wit +++ b/wit-0.3.0-draft/stdio.wit @@ -42,6 +42,11 @@ interface stdout { /// complete a write once the bytes have been fully flushed out to the /// destination in interactive situations as this API is frequently used /// for debugging. + /// + /// If this function is called multiple times then the true output of this + /// component will be an interleaving of all the various streams together + /// as data from them becomes ready. If two streams appended here are ready + /// at the same time with data then it's not specified which one comes first. @since(version = 0.3.0-rc-2025-08-15) append-stdout: func(data: stream); } @@ -64,6 +69,11 @@ interface stderr { /// complete a write once the bytes have been fully flushed out to the /// destination in interactive situations as this API is frequently used /// for debugging. + /// + /// If this function is called multiple times then the true output of this + /// component will be an interleaving of all the various streams together + /// as data from them becomes ready. If two streams appended here are ready + /// at the same time with data then it's not specified which one comes first. @since(version = 0.3.0-rc-2025-08-15) append-stderr: func(data: stream); }