iox v0.3.6 — Clarify semantic control classification

[hayabusa-cloud]

Introduction

Package iox provides non-blocking I/O semantics for Go, extending the standard io package with explicit control outcomes for readiness suspension and live streaming or multishot frontiers while preserving ordinary io.Reader and io.Writer compatibility.

Blocking I/O code often treats (count, error) as a simple success or failure boundary. Non-blocking and streaming I/O also need to expose "not ready yet" and "this operation is still alive." iox makes both cases explicit: ErrWouldBlock means the immediate attempt reached a no-progress readiness boundary and should be retried only after readiness or event evidence, while ErrMore means the current observation is usable and the same logical operation can yield later observations before it terminates, is canceled, or fails.

This release tightens the public classification contract around semantic-control outcomes. ErrWouldBlock and ErrMore remain non-failure control outcomes; callers should process the returned count first, then use helpers such as IsMore, IsWouldBlock, IsSemantic, IsNonFailure, IsFailure, or Classify to choose the next control action.

The package now exposes IsFailure(err error) bool for the direct failure case: it reports true only for actual failures, not for nil, ErrWouldBlock, or ErrMore. The documentation also separates wrapped semantic classification at API boundaries from exact sentinel identity used by internal hot-path policy dispatch.

Usage

n, err := op()
if n > 0 {
	consume(n)
}

switch {
case err == nil:
	return nil
case iox.IsMore(err):
	continue
case iox.IsWouldBlock(err):
	wait()
	continue
default:
	return err
}

Highlights

The main change is clearer public vocabulary for the four observable outcomes: terminal success, live-frontier continuation, readiness suspension, and actual failure. IsFailure gives callers a direct helper for the failure case when they need it, while the canonical loop can continue to branch on IsMore, IsWouldBlock, and ordinary error return.

The GoDoc and README guidance now consistently say to prefer iox semantic helper predicates for ordinary classification. Wrapped semantic sentinels still classify correctly through the helpers, while internal copy and tee policy dispatch intentionally depends on exact unwrapped sentinels for hot-path retry decisions.

What's Changed

Features

• Add IsFailure(err error) bool to classify actual failures directly without treating ErrWouldBlock or ErrMore as failures (docs: clarify semantic control documentation #27)

Documentation

• Clarify semantic-control boundaries in package GoDoc, including count-first handling, bounded CopyN terminal behavior, helper-based classification, and exact sentinel dispatch for hot paths (docs: clarify semantic control documentation #27)

Tests

• Add regression coverage for wrapped ErrMore classification and for policy dispatch returning wrapped semantic sentinels without exact-sentinel retry (docs: clarify semantic control documentation #27)

Compatibility

• Go: 1.26+
• Platforms: linux/amd64, linux/arm64, linux/riscv64, linux/loong64

---

This discussion was created from the release iox v0.3.6 — Clarify semantic control classification.