@zio.dev/zio-blocks 0.0.51 → 0.0.56

package/reference/streams/{writer.md → primitives/writer.md}

@@ -1,6 +1,14 @@
 ---
 id: writer
 title: "Writer"
+sidebar_label: "Writer"
+description: "The push-based sink for elements: the write-and-close protocol, the primitive write family, and the sixteen deferred *Async mirrors."
+keywords:
+  - "Push-Based Writing"
+  - "Deferred Effects"
+  - "Writer Cancellation"
+  - "Specialized Writes"
+  - "Writer"
 ---
 
 `Writer[-Elem]` is a **push-based sink for elements** that accepts values one at a time until closed or filled. It is the push-based counterpart to `Reader[+Elem]` (which pulls). Elements are written on demand by the producer, making it ideal for streaming, buffering, and integration with I/O subsystems. The fundamental operations are `write(elem): Boolean` — pushes an element and returns success or closure — and `close()` — signals the end of writing and releases resources.
@@ -31,7 +39,7 @@ Imagine you're building a data pipeline where a producer feeds items to a bounde
 
 With Java's `OutputStream`, you call `write()` and either it succeeds (void return) or throws an exception. This leaves ambiguity: Was the exception transient (try again later) or permanent (the stream is done)? If the buffer fills, the thread blocks—but you don't know how long, or even that it will block beforehand. There's no way to check capacity upfront, so you're forced to either over-allocate buffers (wasting memory) or catch exceptions and guess the right strategy.
 
-`Writer` makes the state explicit and non-throwing. You check readiness with `writeable()`, then push with `write()`, which returns a `Boolean` indicating success or closure. The protocol is clear and exception-free: when `write()` returns `false`, the sink is permanently closed and you should stop.
+`Writer` makes the state explicit and non-throwing. You check readiness with `writeable()`, then push with `write()`, which returns a `Boolean` indicating success or closure. The protocol is explicit: when `write()` returns `false`, the sink is permanently closed and you should stop. It is not exception-free, though — a writer closed with `fail` may throw the stored error on a subsequent `write()`.
 
 ## Quick Showcase
 
@@ -55,7 +63,7 @@ val w = new Writer[Int] {
   override def fail(error: Throwable) = close()
   override def writeable() = !isClosed
 }
-// w: Writer[Int] = repl.MdocSession$MdocApp0$$anon$2@350ce732
+// w: Writer[Int] = repl.MdocSession$MdocApp0$$anon$2@6cb38411
 
 // Push elements, checking writeable() before each write
 def pushAll(elements: List[Int]): Unit = {
@@ -83,7 +91,7 @@ The fundamental protocol is: call `write(element)` to push an element. It return
 import zio.blocks.streams.io.Writer
 
 val w = Writer.single[Int]
-// w: Writer[Int] = zio.blocks.streams.io.Writer$SingleWriter@78b107f
+// w: Writer[Int] = zio.blocks.streams.io.Writer$SingleWriter@2086fd7a
 println(s"First write: ${w.write(42)}")      // true (accepted)
 // First write: true
 println(s"Second write: ${w.write(99)}")     // false (writer auto-closed after one element)
@@ -92,14 +100,79 @@ println(s"Third write: ${w.write(77)}")      // false (still closed)
 // Third write: false
 ```
 
+## Asynchronous Writes
+
+Every effectful member of `Writer` has a deferred mirror whose name ends in `Async` and whose result is an `Async`. There are sixteen of them, and together they are the entire asynchronous surface of the type; the structural combinators `concat` and `contramap` are deliberately outside it.
+
+A mirror does one thing. It wraps a single synchronous call in an effect that has not happened yet: constructing `writer.writeAsync(42)` performs no write at all, and driving the returned effect performs `write(42)` exactly once and yields its `Boolean`. All sixteen are `final` and delegate to one private helper, which builds them on the library's internal cancellable-defer primitive `Async.deferCancelable` (`Writer.scala:57`).
+
+The mirrors group exactly as their synchronous twins do on this page:
+
+| Group              | Synchronous member             | Deferred mirror                     | Result                |
+|--------------------|--------------------------------|-------------------------------------|-----------------------|
+| Lifecycle          | `close()`                      | `closeAsync()`                      | `Async[Unit]`         |
+| Lifecycle          | `fail(error)`                  | `failAsync(error)`                  | `Async[Unit]`         |
+| Single element     | `write(a)`                     | `writeAsync(a)`                     | `Async[Boolean]`      |
+| Bulk               | `writeAll(chunk)`              | `writeAllAsync(chunk)`              | `Async[Chunk[Elem1]]` |
+| Specialized        | `writeInt(value)`              | `writeIntAsync(value)`              | `Async[Boolean]`      |
+| Specialized        | `writeLong(value)`             | `writeLongAsync(value)`             | `Async[Boolean]`      |
+| Specialized        | `writeFloat(value)`            | `writeFloatAsync(value)`            | `Async[Boolean]`      |
+| Specialized        | `writeDouble(value)`           | `writeDoubleAsync(value)`           | `Async[Boolean]`      |
+| Byte and character | `writeByte(b)`                 | `writeByteAsync(b)`                 | `Async[Boolean]`      |
+| Byte and character | `writeBytes(buf, offset, len)` | `writeBytesAsync(buf, offset, len)` | `Async[Int]`          |
+| Byte and character | `writeChar(value)`             | `writeCharAsync(value)`             | `Async[Boolean]`      |
+| Byte and character | `writeShort(value)`            | `writeShortAsync(value)`            | `Async[Boolean]`      |
+| Byte and character | `writeBoolean(value)`          | `writeBooleanAsync(value)`          | `Async[Boolean]`      |
+| State checks       | `isClosed`                     | `isClosedAsync`                     | `Async[Boolean]`      |
+| State checks       | `writeable()`                  | `writeableAsync()`                  | `Async[Boolean]`      |
+| State checks       | `jvmType`                      | `jvmTypeAsync`                      | `Async[JvmType]`      |
+
+Each mirror carries the same parameters and the same implicit evidence as its twin, so the specialized mirrors still ask for the subtype witness their twin asks for:
+
+```scala
+abstract class Writer[-Elem] {
+  final def closeAsync(): Async[Unit]
+  final def writeAsync(a: Elem): Async[Boolean]
+  final def writeAllAsync[Elem1 <: Elem](chunk: Chunk[Elem1]): Async[Chunk[Elem1]]
+  final def writeIntAsync(value: Int)(implicit ev: Int <:< Elem): Async[Boolean]
+  final def writeBytesAsync(buf: Array[Byte], offset: Int, len: Int)(implicit ev: Byte <:< Elem): Async[Int]
+}
+```
+
+`jvmTypeAsync` is the mirror of `jvmType`, the writer's element representation (`JvmType.AnyRef` unless a subclass overrides it). It is the only mirror whose twin is not otherwise documented on this page.
+
+### What `*Async` Does and Does Not Do
+
+These are **cancellation-aware deferral adapters, not asynchronous I/O**. The library's own scaladoc says so in as many words (`Writer.scala:51`), and it is worth repeating because sixteen methods named `*Async` invite the opposite conclusion.
+
+What a mirror does:
+
+- **It defers one synchronous operation.** The wrapped call is first evaluated when the effect is driven, never when it is constructed, and it runs at most once however many times the effect is composed.
+- **It closes the writer on cancellation.** Every mirror installs `close()` as its cancellation hook. If cancellation wins before the operation finishes, the writer is closed and the operation's result is discarded rather than published — the run then delivers nothing at all, so a cancelled handle must never be given to `block`.
+
+What a mirror does not do:
+
+- **It does not move the write to another thread.** Driving `writeAsync` calls `write` on whichever thread is driving.
+- **It does not make a blocking write nonblocking.** When `write` blocks — a bounded buffer with no space, a socket with a full send window — driving `writeAsync` blocks in the same place for the same duration. `writeBytesAsync` on a `Writer.fromOutputStream` is a `java.io.OutputStream.write` behind an `Async`, and that call blocks.
+
+:::warning[These methods are not nonblocking I/O]
+A `Writer` whose `write` blocks still blocks when you drive its `*Async` mirror. The mirrors buy you deferral and a cancellation hook; they do not buy you a nonblocking writer. If you need writes that genuinely suspend rather than block, that is a different writer, not a different method on this one.
+:::
+
+Cancellation is cooperative and interrupts no thread, so the hook cannot abort a call already inside a blocking `write`. It calls `close()`, and that helps exactly when closing the writer is what releases the blocked call — which is true of a writer whose blocking wait is woken by closure, and false of one that ignores its own closed flag while parked. See [Running#cancel](../../async.md#runningcancel) for what a cancelled run does and does not stop.
+
+### Why There Is No `concatAsync` or `contramapAsync`
+
+The structural combinators `concat` and `contramap` have no mirrors, and that is deliberate rather than an omission. The synchronous `Writer` protocol requires `write` to return its `Boolean` immediately. A composition callback that produced an `Async` would have no honest way to report that result: `write` cannot return a pending value, and inventing one — blocking on it, or guessing `true` — would break the very protocol the page opens with. Modelling asynchronous composition needs a separate async-writer architecture, not another method here.
+
 ## Capacity and Buffering
 
 The default `writeable()` method returns `!isClosed`—it only tells you if the writer is closed, not whether the buffer has space. Bounded implementations can override `writeable()` to reflect remaining capacity, but this is not guaranteed by the interface. The important distinction:
 
 - **`writeable()` returns `false`**: the writer is closed (permanent state)
-- **`writeable()` returns `true` but `write()` would block**: the buffer is full but not closed; bounded implementations block the calling thread until space becomes available (they don't return `false`)
+- **`writeable()` returns `true` but `write()` would block**: the buffer is full but not closed. What happens next is implementation-defined: a writer backed by a bounded buffer may block the calling thread until space becomes available, while the buffer-backed writers in this library instead auto-close and return `false`.
 
-Implementations like `ByteBufferWriter` auto-close when the buffer fills, turning the full state into closure. Others may block indefinitely waiting for space.
+The writers behind `NioWriters.fromByteBuffer` and its typed variants auto-close when the buffer fills, turning the full state into closure. A writer you implement yourself may instead block indefinitely waiting for space.
 
 ## Error Handling
 
@@ -127,7 +200,7 @@ class ErrorStoringWriter extends Writer[Int] {
 }
 
 val w = new ErrorStoringWriter()
-// w: ErrorStoringWriter = repl.MdocSession$MdocApp9$ErrorStoringWriter@35e00b45
+// w: ErrorStoringWriter = repl.MdocSession$MdocApp9$ErrorStoringWriter@2cf0305a
 w.fail(new Exception("Stream error"))
 try {
   w.write(42)  // throws the stored error
@@ -159,7 +232,7 @@ Create a pre-closed writer that rejects all writes:
 import zio.blocks.streams.io.Writer
 
 val w = Writer.closed
-// w: Writer[Any] = zio.blocks.streams.io.Writer$$anon$1@603b3a16
+// w: Writer[Any] = zio.blocks.streams.io.Writer$$anon$1@475df1d1
 println(w.write(42))        // false (closed)
 // false
 println(w.isClosed)         // true
@@ -182,7 +255,7 @@ Create a writer that accepts exactly one element, then auto-closes:
 import zio.blocks.streams.io.Writer
 
 val w = Writer.single[Int]
-// w: Writer[Int] = zio.blocks.streams.io.Writer$SingleWriter@20f8ee95
+// w: Writer[Int] = zio.blocks.streams.io.Writer$SingleWriter@1959620c
 println(w.write(42))        // true
 // true
 println(w.write(99))        // false (already accepted one element)
@@ -218,10 +291,10 @@ val inner = new Writer[Int] {
   def write(a: Int) = { collected += a; true }
   def close() = ()
 }
-// inner: Writer[Int] = repl.MdocSession$MdocApp19$$anon$23@73ed153a
+// inner: Writer[Int] = repl.MdocSession$MdocApp19$$anon$23@31c126b0
 
 val limited = Writer.limited(inner, 2)
-// limited: Writer[Int] = zio.blocks.streams.io.Writer$LimitedWriter@6e804688
+// limited: Writer[Int] = zio.blocks.streams.io.Writer$LimitedWriter@2c2c5703
 println(limited.write(1))    // true
 // true
 println(limited.write(2))    // true (space available)
@@ -254,6 +327,8 @@ object Writer {
 
 The fundamental operations on `Writer` cover pushing elements one at a time, bulk operations, specialized writes for primitives, and state checks:
 
+Each of these operations also has a deferred mirror, listed in [Asynchronous Writes](#asynchronous-writes) above.
+
 ### Writing Elements
 
 `Writer#write` — Pushes one element to the writer. Returns `true` on success, `false` if the writer is closed and cannot accept more elements. Throws if the writer was closed with an error via `Writer#fail`:
@@ -270,7 +345,7 @@ Write elements and observe the return value indicating success or closure:
 import zio.blocks.streams.io.Writer
 
 val w = Writer.single[Int]
-// w: Writer[Int] = zio.blocks.streams.io.Writer$SingleWriter@5855f9a7
+// w: Writer[Int] = zio.blocks.streams.io.Writer$SingleWriter@40fc0d5d
 val result1 = w.write(42)
 // result1: Boolean = true
 val result2 = w.write(99)  // false, already closed
@@ -296,7 +371,7 @@ import zio.blocks.streams.io.Writer
 import zio.blocks.chunk.Chunk
 
 val w = Writer.single[Int]
-// w: Writer[Int] = zio.blocks.streams.io.Writer$SingleWriter@4130dfc
+// w: Writer[Int] = zio.blocks.streams.io.Writer$SingleWriter@3d1c8bf6
 val chunk = Chunk(1, 2, 3)
 // chunk: Chunk[Int] = IndexedSeq(1, 2, 3)
 val remaining = w.writeAll(chunk)
@@ -307,13 +382,13 @@ println(s"Remaining: $remaining")  // Chunk(2, 3)
 
 ### Specialized Writes
 
-For primitive types, specialized write methods avoid boxing by using subtype witnesses.
+For primitive types, specialized write methods take a subtype witness so that a writer backed by that primitive can override them and write the value without going through the generic `write`. The default bodies delegate to `write(value.asInstanceOf[Elem])`, so a writer that does not override them gains nothing.
 
 `writeInt` — Specialized `Int` write. Requires implicit evidence that `Int` is a subtype of `Elem`:
 
 ```scala
 abstract class Writer[-Elem] {
-  def writeInt(value: Int)(using Int <:< Elem): Boolean
+  def writeInt(value: Int)(implicit ev: Int <:< Elem): Boolean
 }
 ```
 
@@ -321,7 +396,7 @@ abstract class Writer[-Elem] {
 
 ```scala
 abstract class Writer[-Elem] {
-  def writeLong(value: Long)(using Long <:< Elem): Boolean
+  def writeLong(value: Long)(implicit ev: Long <:< Elem): Boolean
 }
 ```
 
@@ -329,7 +404,7 @@ abstract class Writer[-Elem] {
 
 ```scala
 abstract class Writer[-Elem] {
-  def writeFloat(value: Float)(using Float <:< Elem): Boolean
+  def writeFloat(value: Float)(implicit ev: Float <:< Elem): Boolean
 }
 ```
 
@@ -337,7 +412,7 @@ abstract class Writer[-Elem] {
 
 ```scala
 abstract class Writer[-Elem] {
-  def writeDouble(value: Double)(using Double <:< Elem): Boolean
+  def writeDouble(value: Double)(implicit ev: Double <:< Elem): Boolean
 }
 ```
 
@@ -347,7 +422,7 @@ abstract class Writer[-Elem] {
 
 ```scala
 abstract class Writer[-Elem] {
-  def writeByte(b: Byte)(using Byte <:< Elem): Boolean
+  def writeByte(b: Byte)(implicit ev: Byte <:< Elem): Boolean
 }
 ```
 
@@ -355,7 +430,7 @@ abstract class Writer[-Elem] {
 
 ```scala
 abstract class Writer[-Elem] {
-  def writeBytes(buf: Array[Byte], offset: Int, len: Int)(using Byte <:< Elem): Int
+  def writeBytes(buf: Array[Byte], offset: Int, len: Int)(implicit ev: Byte <:< Elem): Int
 }
 ```
 
@@ -363,7 +438,7 @@ abstract class Writer[-Elem] {
 
 ```scala
 abstract class Writer[-Elem] {
-  def writeChar(value: Char)(using Char <:< Elem): Boolean
+  def writeChar(value: Char)(implicit ev: Char <:< Elem): Boolean
 }
 ```
 
@@ -371,7 +446,7 @@ abstract class Writer[-Elem] {
 
 ```scala
 abstract class Writer[-Elem] {
-  def writeShort(value: Short)(using Short <:< Elem): Boolean
+  def writeShort(value: Short)(implicit ev: Short <:< Elem): Boolean
 }
 ```
 
@@ -379,7 +454,7 @@ abstract class Writer[-Elem] {
 
 ```scala
 abstract class Writer[-Elem] {
-  def writeBoolean(value: Boolean)(using Boolean <:< Elem): Boolean
+  def writeBoolean(value: Boolean)(implicit ev: Boolean <:< Elem): Boolean
 }
 ```
 
@@ -393,7 +468,7 @@ abstract class Writer[-Elem] {
 }
 ```
 
-`writeable` — Returns `true` if the next `write()` would accept a value without blocking (space is available and the writer is not closed). Default returns `!isClosed`. Buffered writers override for accuracy. Note: the analogous method on `Reader` is named `readable()`, not `writable()`.
+`writeable` — Returns `true` if the next `write()` would accept a value without blocking (space is available and the writer is not closed). Default returns `!isClosed`. A writer backed by a bounded buffer can override it for accuracy; none of the writers in this library does. Note the spelling: it is `writeable()`, not `writable()`; `Reader`'s counterpart is `readable()`.
 
 ```scala
 abstract class Writer[-Elem] {
@@ -407,7 +482,7 @@ Check writer capacity before writing:
 import zio.blocks.streams.io.Writer
 
 val w = Writer.single[Int]
-// w: Writer[Int] = zio.blocks.streams.io.Writer$SingleWriter@35d64778
+// w: Writer[Int] = zio.blocks.streams.io.Writer$SingleWriter@71a80be
 println(w.writeable())      // true
 // true
 w.write(42)
@@ -454,17 +529,17 @@ val w1 = new Writer[Int] {
   }
   def close() = ()
 }
-// w1: Writer[Int] = repl.MdocSession$MdocApp32$$anon$43@3bcbf5bd
+// w1: Writer[Int] = repl.MdocSession$MdocApp32$$anon$43@2b669ef3
 
 val w2 = new Writer[Int] {
   def isClosed = false
   def write(a: Int) = { collected += a * 10; true }
   def close() = ()
 }
-// w2: Writer[Int] = repl.MdocSession$MdocApp32$$anon$45@3ed3f62
+// w2: Writer[Int] = repl.MdocSession$MdocApp32$$anon$45@30a331ff
 
 val combined = w1 ++ w2
-// combined: Writer[Int] = zio.blocks.streams.io.Writer$ConcatWith@6f75d7cc
+// combined: Writer[Int] = zio.blocks.streams.io.Writer$ConcatWith@21dd14f1
 combined.write(5)
 // res33: Boolean = true
 combined.write(20)  // first writer rejects, switches to second
@@ -493,10 +568,10 @@ val stringWriter = new Writer[String] {
   def write(a: String) = { println(s"Writing: $a"); true }
   def close() = ()
 }
-// stringWriter: Writer[String] = repl.MdocSession$MdocApp36$$anon$51@23d463e2
+// stringWriter: Writer[String] = repl.MdocSession$MdocApp36$$anon$51@31113f62
 
 val intWriter = stringWriter.contramap[Int](_.toString)
-// intWriter: Writer[Int] = zio.blocks.streams.io.Writer$Contramapped@254fb1b1
+// intWriter: Writer[Int] = zio.blocks.streams.io.Writer$Contramapped@6a721b4f
 intWriter.write(42)   // Prints: Writing: 42
 // Writing: 42
 // res37: Boolean = true
@@ -532,7 +607,7 @@ Close a writer with an error:
 import zio.blocks.streams.io.Writer
 
 val w = Writer.single[Int]
-// w: Writer[Int] = zio.blocks.streams.io.Writer$SingleWriter@7e886598
+// w: Writer[Int] = zio.blocks.streams.io.Writer$SingleWriter@11dd645a
 w.write(42)
 // res39: Boolean = true
 w.fail(new RuntimeException("Error"))
@@ -555,11 +630,11 @@ val numberWriter = new Writer[Number] {
   def write(a: Number) = { println(s"Number: $a"); true }
   def close() = ()
 }
-// numberWriter: Writer[Number] = repl.MdocSession$MdocApp42$$anon$59@290eac28
+// numberWriter: Writer[Number] = repl.MdocSession$MdocApp42$$anon$59@4a564d3b
 
 // numberWriter is also a Writer[IntNum] due to contravariance
 val intNumWriter: Writer[IntNum] = numberWriter
-// intNumWriter: Writer[IntNum] = repl.MdocSession$MdocApp42$$anon$59@290eac28
+// intNumWriter: Writer[IntNum] = repl.MdocSession$MdocApp42$$anon$59@4a564d3b
 intNumWriter.write(IntNum(42))
 // Number: IntNum(42)
 // res43: Boolean = true
@@ -577,7 +652,7 @@ For typical stream usage, you'll see Writer indirectly when writing to files, ne
 
 Understanding `Writer`'s design decisions helps you use it correctly and avoid common pitfalls:
 
-### Push vs Pull
+### Push Vs Pull
 
 `Writer` is push-based (producer-driven), contrasting with `Reader` which is pull-based (consumer-driven):
 
@@ -586,7 +661,7 @@ Understanding `Writer`'s design decisions helps you use it correctly and avoid c
 | **Direction**  | Source → Consumer (pull)   | Producer → Sink (push)  |
 | **Variance**   | Covariant (`+Elem`)        | Contravariant (`−Elem`) |
 | **Blocking**   | `read()` may block         | `write()` may block     |
-| **Signal end** | Returns sentinel or `null` | `close()` or `fail()`   |
+| **Signal end** | Caller-supplied sentinel, or a negative count from a bulk read | `close()` or `fail()`   |
 | **Dual**       | Sink drains Reader         | Producer feeds Writer   |
 
 ### Thread Safety
@@ -617,22 +692,6 @@ cd zio-blocks
 This example demonstrates the most common writer factories: `Writer.single`, `Writer.limited`, `Writer.closed`, and custom writers via subclassing:
 
 ```scala title="streams-examples/src/main/scala/writer/WriterBasicConstructionExample.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package writer
 
 import zio.blocks.streams.io.Writer
@@ -714,22 +773,6 @@ sbt "streams-examples/runMain writer.WriterBasicConstructionExample"
 This example shows writer composition with `Writer#++` (concat), transformation with `Writer#contramap`, and bulk writes with `Writer#writeAll`:
 
 ```scala title="streams-examples/src/main/scala/writer/WriterCompositionExample.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package writer
 
 import zio.blocks.streams.io.Writer
@@ -851,22 +894,6 @@ sbt "streams-examples/runMain writer.WriterCompositionExample"
 This example demonstrates I/O integration with `Writer.fromOutputStream` and `Writer.fromWriter` for streaming to files or character streams:
 
 ```scala title="streams-examples/src/main/scala/writer/WriterIOAdapterExample.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package writer
 
 import zio.blocks.streams.io.Writer
@@ -965,22 +992,6 @@ sbt "streams-examples/runMain writer.WriterIOAdapterExample"
 This example shows how to implement a bounded Writer that wraps a fixed-capacity container and auto-closes when full. It demonstrates the protocol: `write()` returns `false` only on closure (not buffer fullness), and `writeable()` reflects closure state:
 
 ```scala title="streams-examples/src/main/scala/writer/WriterBoundedImplementationExample.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package writer
 
 import zio.blocks.streams.io.Writer
@@ -1043,3 +1054,148 @@ Run this example with:
 ```bash
 sbt "streams-examples/runMain writer.WriterBoundedImplementationExample"
 ```
+
+### Deferred and Cancellable Writes
+
+This example makes the `*Async` caveat concrete. It shows that constructing a mirror writes nothing while driving it writes once, composes three mirrors into one effect, and then cancels a driven `writeAsync` whose write is parked — observing that cancellation closed the writer, that no element was recorded, and that the run delivers no value at all:
+
+```scala title="streams-examples/src/main/scala/writer/WriterAsyncExample.scala" 
+package writer
+
+import zio.blocks.async.*
+import zio.blocks.chunk.Chunk
+import zio.blocks.streams.io.Writer
+
+import java.util.concurrent.{ConcurrentLinkedQueue, CountDownLatch}
+
+/**
+ * The `*Async` mirrors on `Writer`, and the two properties that define them:
+ * each mirror defers exactly one synchronous writer operation until the
+ * returned effect is driven, and cancellation closes the writer and suppresses
+ * the stale result.
+ *
+ * Neither property makes a write nonblocking, and neither moves it to another
+ * thread. The last section only observes cancellation at all because the
+ * writer's own `close()` is what releases the parked write.
+ *
+ * JVM only, because it ends in `.block` to turn an `Async` into a value for
+ * `main`.
+ */
+object WriterAsyncExample {
+
+  /** Records what actually reached the writer, so deferral is observable. */
+  final class RecordingWriter extends Writer[Int] {
+    private val recorded       = scala.collection.mutable.ArrayBuffer.empty[Int]
+    private var closed         = false
+    def isClosed: Boolean      = closed
+    def write(a: Int): Boolean = if (closed) false else { recorded += a; true }
+    def close(): Unit          = closed = true
+    def snapshot: List[Int]    = recorded.toList
+  }
+
+  /**
+   * A writer whose `write` parks until someone closes it. `close()` is the
+   * cancellation hook every `*Async` mirror installs, so cancelling a driven
+   * `writeAsync` is what wakes this writer up again.
+   */
+  final class GatedWriter extends Writer[Int] {
+    private val gate             = new CountDownLatch(1)
+    private val recorded         = new ConcurrentLinkedQueue[Int]
+    @volatile private var closed = false
+
+    /** Counts down once the deferred thunk has entered `write`. */
+    val entered = new CountDownLatch(1)
+
+    /** Counts down once `close()` has run. */
+    val wasClosed = new CountDownLatch(1)
+
+    /** Counts down once the parked `write` has returned. */
+    val finished = new CountDownLatch(1)
+
+    def isClosed: Boolean = closed
+
+    def write(a: Int): Boolean = {
+      entered.countDown()
+      gate.await()
+      val accepted =
+        if (closed) false
+        else { recorded.add(a); true }
+      finished.countDown()
+      accepted
+    }
+
+    def close(): Unit = {
+      closed = true
+      gate.countDown()
+      wasClosed.countDown()
+    }
+
+    def recordedCount: Int = recorded.size
+  }
+
+  def main(args: Array[String]): Unit = {
+    deferral()
+    sequence()
+    cancellation()
+  }
+
+  /** Constructing a mirror writes nothing; driving it writes exactly once. */
+  private def deferral(): Unit = {
+    val writer  = new RecordingWriter
+    val pending = writer.writeAsync(1)
+
+    println(s"deferral: after construction  recorded=${writer.snapshot}")
+    println(s"deferral: after driving once  accepted=${pending.block}, recorded=${writer.snapshot}")
+  }
+
+  /** The mirrors compose like any other `Async`, one operation per step. */
+  private def sequence(): Unit = {
+    val writer = new RecordingWriter
+
+    val program: Async[Chunk[Int]] =
+      writer
+        .writeAsync(10)
+        .flatMap(_ => writer.writeAllAsync(Chunk(20, 30, 40)))
+        .flatMap(undelivered => writer.closeAsync().map(_ => undelivered))
+
+    val undelivered = program.block
+    println(s"sequence: recorded=${writer.snapshot}, undelivered=$undelivered, closed=${writer.isClosed}")
+  }
+
+  /**
+   * Cancellation closes the writer and discards the result it was about to
+   * produce.
+   */
+  private def cancellation(): Unit = {
+    val writer  = new GatedWriter
+    val running = writer.writeAsync(99).start
+
+    // Wait until the deferred thunk is parked inside `write`, so cancellation
+    // races a genuinely in-flight operation rather than an unstarted one.
+    writer.entered.await()
+    running.cancel()
+
+    // Cancellation ran `close()`, which released the parked `write`.
+    writer.wasClosed.await()
+    writer.finished.await()
+
+    // The `false` that `write` then returned lost the race to publish, so this
+    // run never delivers a value. Never call `.block` on a cancelled handle.
+    println(s"cancellation: closed=${writer.isClosed}, recorded=${writer.recordedCount}")
+  }
+}
+```
+
+Run this example with:
+
+```bash
+sbt "streams-examples/runMain writer.WriterAsyncExample"
+```
+
+## See Also
+
+- [Asynchronous Stream Execution](../execution-and-compatibility/async-execution.md#cancellation) — how cancellation reaches a stream's resources, and the asynchronous stream API the deferred mirrors sit beside
+- [Async Reference](../../async.md#runningcancel) — what `Running#cancel` stops, why a cancelled run never delivers, and why the cancel hook cannot interrupt a blocked thread
+- [Reader](./reader.md) — the pull-based dual of this type, and the reader kinds a sink drains
+- [Sink](../core/sink.md) — the consumer side of a stream, which drains a `Reader` rather than feeding a `Writer`
+- [Zero-Boxing Streams](../execution-and-compatibility/zero-boxing.md) — why the specialized write family exists and how a primitive lane is chosen