@zio.dev/zio-blocks 0.0.29 → 0.0.31

package/reference/resource-management/defer-handle.md

@@ -0,0 +1,246 @@
+---
+id: defer-handle
+title: "DeferHandle"
+---
+
+`DeferHandle` is a handle returned by `Scope.defer` that allows cancelling a registered finalizer before the scope closes:
+
+```scala
+abstract class DeferHandle {
+  def cancel(): Unit
+}
+```
+
+When `Scope#defer(cleanup)` is called, the cleanup action is registered and a `DeferHandle` is returned. This handle can be used to remove that finalizer early, preventing it from running when the scope closes. This is useful when a resource is explicitly released before the scope ends, and running the finalizer again would be unnecessary or harmful.
+
+## Construction
+
+`DeferHandle` is not instantiated directly. Instead, it is created by calling `Scope#defer` with a cleanup action:
+
+```scala
+import zio.blocks.scope.{Scope, DeferHandle}
+
+trait Scope {
+  def defer(cleanup: => Unit): DeferHandle
+}
+```
+
+The following example demonstrates creating a `DeferHandle`:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  val handle = defer {
+    println("This cleanup will run when scope closes, unless cancelled")
+  }
+
+  // The handle can now be used to cancel the cleanup
+  handle.cancel()
+}
+```
+
+## Core Operations
+
+The `DeferHandle#cancel` method removes the registered finalizer so it will not run when the scope closes:
+
+```scala
+trait DeferHandle {
+  def cancel(): Unit
+}
+```
+
+This method is:
+
+- **Thread-safe**: Can be called from any thread without synchronization
+- **Idempotent**: Calling it multiple times has the same effect as calling once
+
+If the scope has already closed (and the finalizer has already run or been discarded), calling `DeferHandle#cancel` is a no-op. In the following example, we register a cleanup action, then cancel it before the scope closes:
+
+```scala
+import zio.blocks.scope.Scope
+import java.io.ByteArrayOutputStream
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  val buffer = allocate(ByteArrayOutputStream())
+  val closeHandle = defer {
+    println("Auto-closing buffer")
+    $(buffer)(_.close())
+  }
+
+  // Manually close the buffer
+  $(buffer)(_.close())
+
+  // Cancel the automatic finalizer since we already closed it
+  closeHandle.cancel()
+}
+```
+
+## Use Cases
+
+`DeferHandle` is useful in several common scenarios:
+
+### Preventing Duplicate Cleanup
+
+When a resource is explicitly released before the scope ends, cancel the automatic finalizer to avoid duplicate cleanup:
+
+```scala
+import zio.blocks.scope.Scope
+import java.io.ByteArrayOutputStream
+
+val result = Scope.global.scoped { scope =>
+  import scope._
+
+  val buffer = allocate(ByteArrayOutputStream())
+
+  val finalizeHandle = defer {
+    println(s"Finalizer running, buffer closing")
+    $(buffer)(_.close())
+  }
+
+  // Explicit cleanup
+  $(buffer) { buf =>
+    buf.write("data".getBytes)
+    println(s"Manual use: buffer has ${buf.size()} bytes")
+    buf.close()
+  }
+
+  // Cancel the automatic finalizer
+  finalizeHandle.cancel()
+  
+  "done"
+}
+```
+
+### Conditional Cleanup
+
+Cancel finalizers based on runtime conditions:
+
+```scala
+import zio.blocks.scope.Scope
+
+def acquireResource(shouldCleanup: Boolean) = Scope.global.scoped { scope =>
+  import scope._
+
+  val resource = "important resource"
+  val handle = scope.defer {
+    println("Cleaning up resource")
+  }
+
+  if (!shouldCleanup) {
+    handle.cancel()
+    println("Cleanup disabled")
+  }
+
+  resource
+}
+
+acquireResource(shouldCleanup = false)
+acquireResource(shouldCleanup = true)
+```
+
+### Transferring Ownership
+
+When transferring a resource to external management, cancel its finalizer so the external system can control cleanup:
+
+```scala
+import zio.blocks.scope.Scope
+import java.io.ByteArrayInputStream
+
+val result = Scope.global.scoped { scope =>
+  import scope._
+
+  val stream = allocate(ByteArrayInputStream("data".getBytes))
+  val handle = defer {
+    println("Scope finalizer would close stream")
+    $(stream)(_.close())
+  }
+
+  // Transfer ownership to external manager
+  // (In real code, this might pass to a thread pool or async framework)
+  handle.cancel()  // Let the manager handle cleanup
+  
+  "transferred"
+}
+```
+
+## Noop Handle
+
+When `defer()` is called on an already-closed scope, a no-op handle is returned:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  val handle = scope.defer {
+    println("This will run when scope closes")
+  }
+
+  // Subsequent calls to cancel() remove the finalizer
+  handle.cancel()
+
+  println("Finalizer has been cancelled")
+}
+```
+
+## Thread Safety
+
+`DeferHandle` is thread-safe. Multiple threads can call `cancel()` on the same handle without external synchronization:
+
+```scala
+import zio.blocks.scope.Scope
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.Executors
+
+val result = Scope.global.scoped { scope =>
+  import scope._
+
+  val handle = defer {
+    println("Finalizer")
+  }
+
+  // Use a thread pool to simulate concurrent access
+  val executor = Executors.newFixedThreadPool(5)
+  val latch = new CountDownLatch(5)
+
+  (1 to 5).foreach { i =>
+    executor.submit(new Runnable {
+      def run(): Unit = {
+        handle.cancel()
+        println(s"Thread $i cancelled")
+        latch.countDown()
+      }
+    })
+  }
+
+  // Wait for all threads to finish
+  latch.await()
+  executor.shutdown()
+  
+  "completed"
+}
+```
+
+## See Also
+
+- [`Scope#defer`](./scope.md#registering-finalizers) — the method that returns a `DeferHandle`
+- [`Finalizer`](./finalizer.md) — the trait defining `Finalizer#defer`
+- [`Finalization`](./finalization.md) — the result of running all finalizers
+
+## Integration
+
+`DeferHandle` is part of ZIO Blocks' resource management system. It works directly with:
+
+- **[`Scope`](./scope.md)** — The primary way to create a `DeferHandle` is via `Scope#defer`. A scope manages multiple finalizers and runs them all when the scope closes. `DeferHandle` allows selective cancellation of individual finalizers before that happens.
+
+- **[`Finalizer`](./finalizer.md)** — `Finalizer` defines the `Finalizer#defer` operation that returns a `DeferHandle`. It abstracts the concept of registering cleanup actions.
+
+- **[`Finalization`](./finalization.md)** — When a scope closes, it runs all registered finalizers. A cancelled `DeferHandle` removes its associated finalizer from this process.
+
+Together, these types form the foundation of compile-time resource safety in ZIO Blocks, allowing you to manage resource lifecycles with certainty that cleanup will occur exactly when needed.

package/reference/resource-management/finalization.md

@@ -0,0 +1,286 @@
+---
+id: finalization
+title: "Finalization"
+---
+
+`Finalization` is the result of running all finalizers in a scope, collecting any errors that occurred during cleanup:
+
+```scala
+import zio.blocks.chunk.Chunk
+
+abstract class Finalization(val errors: Chunk[Throwable]) {
+  def isEmpty: Boolean
+  def nonEmpty: Boolean
+  def orThrow(): Unit
+  def suppress(initial: Throwable): Throwable
+}
+```
+
+When a scope closes, each registered finalizer runs in LIFO order. If any finalizer throws an exception, that error is caught and collected into a `Finalization`. This type ensures that all finalizers run even if some fail, and allows the caller to decide how to handle accumulated errors.
+
+`Finalization` collects errors from finalizers in a `Chunk[Throwable]`. The first error in the chunk corresponds to the head of the chunk (the first finalizer that failed in LIFO execution order).
+
+## Core Methods
+
+The following four methods allow you to inspect and handle errors from finalization:
+
+### `Finalization#isEmpty`
+
+Returns `true` if no finalizer errors were collected:
+
+```scala
+import zio.blocks.chunk.Chunk
+
+abstract class Finalization(val errors: Chunk[Throwable]) {
+  def isEmpty: Boolean
+}
+```
+
+Here's an example of checking if finalization succeeded:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  $(open()) { openScope =>
+    import openScope.scope._
+    defer {
+      println("Cleanup")
+    }
+    val fin = openScope.close()
+    if (fin.isEmpty) println("No errors") else println("Errors occurred")
+  }
+}
+```
+
+### `Finalization#nonEmpty`
+
+Returns `true` if at least one finalizer error was collected:
+
+```scala
+import zio.blocks.chunk.Chunk
+
+abstract class Finalization(val errors: Chunk[Throwable]) {
+  def nonEmpty: Boolean
+}
+```
+
+Here's an example of checking for errors:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  $(open()) { openScope =>
+    import openScope.scope._
+    defer {
+      throw new Exception("Cleanup failed")
+    }
+    val fin = openScope.close()
+    if (fin.nonEmpty) {
+      println(s"Errors occurred: ${fin.errors.length}")
+    }
+  }
+}
+```
+
+### `Finalization#orThrow()`
+
+Throws the first collected error with all remaining errors added as suppressed exceptions. Does nothing if there are no errors:
+
+```scala
+import zio.blocks.chunk.Chunk
+
+abstract class Finalization(val errors: Chunk[Throwable]) {
+  def orThrow(): Unit
+}
+```
+
+The first error corresponds to the head of the chunk (the first finalizer that failed in LIFO execution order). Remaining errors are attached as suppressed exceptions using `addSuppressed()`. Here's an example:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+  $(open()) { openScope =>
+    defer { throw Exception("Error 2") }
+    defer { throw Exception("Error 1") }
+    val fin = openScope.close()
+    
+    try {
+      fin.orThrow()
+    } catch {
+      case e: Exception =>
+        println(s"Primary: ${e.getMessage}")
+        e.getSuppressed.foreach(s => println(s"Suppressed: ${s.getMessage}"))
+    }
+  }
+}
+```
+
+### `Finalization#suppress(initial)`
+
+Adds all collected finalizer errors as suppressed exceptions to `initial` and returns it. If there are no errors, `initial` is returned unchanged:
+
+```scala
+import zio.blocks.chunk.Chunk
+
+abstract class Finalization(val errors: Chunk[Throwable]) {
+  def suppress(initial: Throwable): Throwable
+}
+```
+
+This is useful when you want to preserve the original error context while attaching cleanup errors. Here's an example:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  val initialError = Exception("Original error")
+
+  $(open()) { openScope =>
+    defer { throw Exception("Cleanup error") }
+    val fin = openScope.close()
+    
+    val combined = fin.suppress(initialError)
+    println(s"Primary: ${combined.getMessage}")
+    combined.getSuppressed.foreach(s => println(s"Suppressed: ${s.getMessage}"))
+  }
+}
+```
+
+## Error Ordering
+
+Errors in the finalization are ordered by when finalizers ran (in LIFO sequence):
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  $(open()) { openScope =>
+    // Registered first, runs last (LIFO)
+    defer { throw Exception("Error 1") }
+
+    // Registered second, runs first
+    defer { throw Exception("Error 2") }
+
+    // Registered third, runs first
+    defer { throw Exception("Error 3") }
+
+    val fin = openScope.close()
+    
+    // Errors list order: [Error 3, Error 2, Error 1]
+    println(s"First error: ${fin.errors.head.getMessage}")
+    println(s"Total errors: ${fin.errors.length}")
+  }
+}
+```
+
+## Use Cases
+
+Here are common scenarios where finalization handling is useful:
+
+### Conditional Error Handling
+
+Check if errors occurred and handle them appropriately:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  $(open()) { openScope =>
+    defer {
+      println("Cleanup complete")
+    }
+    val fin = openScope.close()
+    
+    if (fin.nonEmpty) {
+      fin.orThrow()
+    } else {
+      println("No errors during finalization")
+    }
+  }
+}
+```
+
+### Combining Multiple Error Sources
+
+Attach cleanup errors to an existing error:
+
+```scala
+import zio.blocks.scope.Scope
+
+def doWork(): Unit = {
+  Scope.global.scoped { scope =>
+    import scope._
+
+    try {
+      throw Exception("Work failed")
+    } catch {
+      case workError: Exception =>
+        $(open()) { openScope =>
+          defer { throw Exception("Cleanup failed") }
+          val fin = openScope.close()
+          val combined = fin.suppress(workError)
+          throw combined
+        }
+    }
+    ()  // Return unit on normal path
+  }
+}
+
+try {
+  doWork()
+} catch {
+  case e: Exception =>
+    println(s"Work: ${e.getMessage}")
+    e.getSuppressed.foreach(s => println(s"During cleanup: ${s.getMessage}"))
+}
+```
+
+### Logging All Cleanup Errors
+
+Inspect and log all errors without stopping execution:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  $(open()) { openScope =>
+    defer { throw Exception("Error 1") }
+    defer { throw Exception("Error 2") }
+    val fin = openScope.close()
+    
+    if (fin.nonEmpty) {
+      println(s"Finalization collected ${fin.errors.length} errors:")
+      fin.errors.foreach(e => println(s"  - ${e.getMessage}"))
+    }
+  }
+}
+```
+
+## Relationship to Scope
+
+`Finalization` is returned by:
+
+- `Scope.open().close()` — when explicitly closing a scope
+- `Scope.global.runFinalizers()` — when running global finalizers on shutdown
+
+## See Also
+
+- [`Scope#defer`](./scope.md) — registers finalizers that produce errors
+- [`DeferHandle`](./defer-handle.md) — handle for cancelling finalizers
+- [`Finalizer`](./finalizer.md) — the trait for registering cleanup actions

package/reference/resource-management/finalizer.md

@@ -0,0 +1,167 @@
+---
+id: finalizer
+title: "Finalizer"
+---
+
+`Finalizer` is a minimal capability interface for registering cleanup actions. It exposes only the `Finalizer#defer` method, preventing code from accessing scope internals like resource allocation or closing.
+
+The structural definition:
+
+```scala
+trait Finalizer {
+  def defer(f: => Unit): DeferHandle
+}
+```
+
+This trait serves as a boundary between scope management internals and user code that only needs to register cleanup actions. By exposing only `defer`, code can safely request cleanup registration without requiring full scope access.
+
+## Motivation / Use Case
+
+`Finalizer` integrates with `Scope` to enable resource management patterns:
+
+```scala
+import zio.blocks.scope.{Scope, Finalizer}
+
+def openConnection(url: String)(implicit fin: Finalizer): String = {
+  fin.defer {
+    println(s"Closing connection to $url")
+  }
+  s"Connected to $url"
+}
+
+Scope.global.scoped { scope =>
+  import scope._
+  openConnection("https://example.com")
+  // Connection closes when scope exits
+  ()
+}
+```
+
+By decoupling code that needs cleanup registration from code that manages the complete scope lifecycle, `Finalizer` allows functions to safely register finalizers without requiring full scope access.
+
+## Construction / Creating Instances
+
+`Finalizer` is not typically constructed directly. Instead, it is obtained through a scope:
+
+### From a `Scope`
+
+Any `Scope` instance can be used as a `Finalizer` since `Scope extends Finalizer`:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+  // scope is both a Scope and a Finalizer
+  val handle = scope.defer {
+    println("Cleanup")
+  }
+  ()  // Return unit
+}
+```
+
+### As a Context Bound
+
+Functions can request a `Finalizer` via `implicit` parameter, enabling decoupled cleanup registration:
+
+```scala
+import zio.blocks.scope.Finalizer
+
+def setupResource(name: String)(implicit fin: Finalizer): String = {
+  fin.defer {
+    println(s"Closing $name")
+  }
+  name
+}
+```
+
+## Core Operations
+
+The `Finalizer` interface provides a single core operation for registering cleanup handlers:
+
+### `Finalizer#defer`
+
+Registers a finalizer (cleanup action) to run when the scope closes. The cleanup action runs in LIFO order along with other finalizers registered on the same scope. Returns a `DeferHandle` that can cancel the registration before the scope closes:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  val handle1 = scope.defer {
+    println("Cleanup 1")
+  }
+
+  val handle2 = scope.defer {
+    println("Cleanup 2")
+  }
+
+  // Finalizers run in LIFO: Cleanup 2, then Cleanup 1
+  // Can cancel before scope closes
+  handle1.cancel()
+  // Now only Cleanup 2 runs
+}
+```
+
+### Package-Level `defer` Helper
+
+A package-level convenience function allows writing `defer { cleanup }` when a `Finalizer` is in scope. The signature is:
+
+```scala
+def defer(finalizer: => Unit)(implicit fin: Finalizer): DeferHandle
+```
+
+This removes the need to write `fin.defer { cleanup }`. Here's the convenience function in use:
+
+```scala
+import zio.blocks.scope.{Scope, defer, Finalizer}
+
+def setupWithCleanup()(implicit fin: Finalizer) = {
+  defer {
+    println("Cleanup")
+  }
+}
+
+Scope.global.scoped { scope =>
+  import scope._
+  setupWithCleanup()
+  // Cleanup prints when scope closes
+  ()  // Return unit (which is Unscoped)
+}
+```
+
+## Integration
+
+`Finalizer` is a supertrait of `Scope`. The structural definition shows this relationship:
+
+```scala
+sealed abstract class Scope extends Finalizer with ScopeVersionSpecific
+```
+
+This means any `Scope` instance can be used where a `Finalizer` is expected. However, the converse is not true—a `Finalizer` reference does not provide `Scope#allocate`, `Scope#$`, or other scope operations.
+
+## Finalization Order
+
+Finalizers registered with `Finalizer#defer` run in **LIFO order** (last registered runs first) when the scope closes. This ensures that resources acquired in order can be cleaned up in reverse order:
+
+```scala
+import zio.blocks.scope.Scope
+
+Scope.global.scoped { scope =>
+  import scope._
+
+  scope.defer { println("First registered, runs last") }
+  scope.defer { println("Second registered, runs first") }
+  // Output on scope close:
+  // Second registered, runs first
+  // First registered, runs last
+  ()  // Return unit (which is Unscoped)
+}
+```
+
+## See Also
+
+- [`Scope`](./scope.md) — the full scope lifecycle management
+- [`DeferHandle`](./defer-handle.md) — the handle returned by `Finalizer#defer` for cancellation
+- [`Finalization`](./finalization.md) — the result of running all finalizers