From 4acd2e7ae6be2cdab9d2d3f4adc96692ac67855d Mon Sep 17 00:00:00 2001
From: Dave Bakker <github@davebakker.io>
Date: Mon, 15 Jul 2024 19:53:13 +0200
Subject: [PATCH] Clarify behavior when dropping an active output-stream (#79)

---
 imports.md      | 7 +++++--
 wit/streams.wit | 4 ++++
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/imports.md b/imports.md
index 01969c5..b26ca79 100644
--- a/imports.md
+++ b/imports.md
@@ -133,12 +133,15 @@ use the <code>subscribe</code> function to obtain a <a href="#pollable"><code>po
 for using <code>wasi:io/poll</code>.</p>
 <h4><a name="output_stream"></a><code>resource output-stream</code></h4>
 <p>An output bytestream.</p>
-<h2><a href="#output_stream"><code>output-stream</code></a>s are <em>non-blocking</em> to the extent practical on
+<p><a href="#output_stream"><code>output-stream</code></a>s are <em>non-blocking</em> to the extent practical on
 underlying platforms. Except where specified otherwise, I/O operations also
 always return promptly, after the number of bytes that can be written
 promptly, which could even be zero. To wait for the stream to be ready to
 accept data, the <code>subscribe</code> function to obtain a <a href="#pollable"><code>pollable</code></a> which can be
-polled for using <code>wasi:io/poll</code>.</h2>
+polled for using <code>wasi:io/poll</code>.</p>
+<h2>Dropping an <a href="#output_stream"><code>output-stream</code></a> while there's still an active write in
+progress may result in the data being lost. Before dropping the stream,
+be sure to fully flush your writes.</h2>
 <h3>Functions</h3>
 <h4><a name="method_input_stream_read"></a><code>[method]input-stream.read: func</code></h4>
 <p>Perform a non-blocking read from the stream.</p>
diff --git a/wit/streams.wit b/wit/streams.wit
index c938362..b5e2a36 100644
--- a/wit/streams.wit
+++ b/wit/streams.wit
@@ -112,6 +112,10 @@ interface streams {
     /// promptly, which could even be zero. To wait for the stream to be ready to
     /// accept data, the `subscribe` function to obtain a `pollable` which can be
     /// polled for using `wasi:io/poll`.
+    ///
+    /// Dropping an `output-stream` while there's still an active write in
+    /// progress may result in the data being lost. Before dropping the stream,
+    /// be sure to fully flush your writes.
     @since(version = 0.2.0)
     resource output-stream {
         /// Check readiness for writing. This function never blocks.