spin v0.1.6 -- Pause semantics and CI maintenance

Introduction

Package spin provides minimal spin primitives for performance-critical Go code paths: Lock for ultra-short critical sections, Wait for adaptive polling, Pause for architecture-specific CPU pause hints, and Yield for cooperative yielding outside hot paths. It is designed for code where allocation, scheduler overhead, and avoidable cache-line traffic matter. Lock remains intentionally non-fair and specialized; general-purpose mutual exclusion should still use sync.Mutex. Wait gives callers a compact adaptive backoff surface, moving from pause hints toward scheduler cooperation as a polling loop ages. Pause exposes the lowest-level CPU hint operation while preserving a compact, allocation-free hot-path surface. Yield stays the explicit escape hatch for non-hot paths that should give other goroutines time to run.

Usage

var sw spin.Wait
for !ready {
    sw.Once()
}

spin.Pause()   // 30 pause hints by default
spin.Pause(50) // 50 pause hints

Highlights

This patch clarifies the public wording around Pause(cycles): cycles is a repeat count for pause hints, not a calibrated CPU-cycle delay. The documentation now states the hardware and fallback behavior explicitly, so callers can distinguish hardware-pause targets from wasm and unsupported fallback targets.

What's Changed

Documentation

• Clarify Pause(cycles) GoDoc and multilingual README wording: the default is 30 pause hints, cycles is a repeat count, and fallback targets may yield through runtime.Gosched() (#10)

Chore

• Update CI action versions and add explicit test timeouts while keeping the Go 1.26.x workflow and coverage gate intact (#10)

Compatibility

• Go: 1.26+
• Platforms: linux/amd64, linux/arm64, linux/386, linux/arm, linux/riscv64, linux/loong64, linux/ppc64le, linux/s390x, wasm

spin v0.1.5 — TTAS slow path with adaptive backoff

Introduction

Package spin provides minimal spin primitives for performance-critical code paths: Lock (non-fair spinlock), Wait (adaptive spin-wait), Pause (architecture-specific CPU hint), and Yield (cooperative sleep). Designed for ultra-short critical sections where OS mutex overhead is prohibitive, with zero allocations on hot paths.

Lock acquisition uses FAA (Fetch-And-Add) for O(n) coherence traffic under contention, compared to O(n²) with CAS-based spinlocks. Architecture-specific pause instructions are provided for amd64, arm64, riscv64, loong64, ppc64le, s390x, and 386.

Usage

var lk spin.Lock
lk.Lock()
// critical section (< 1µs)
lk.Unlock()

Highlights

Lock slow path rewritten to TTAS (test-and-test-and-set) with local-counter adaptive backoff, reducing cache-line invalidations under contention and guaranteeing forward progress on low-core-count machines.

What's Changed

Improvements

• Rewrite Lock slow path to TTAS: spin on read-only Load, attempt FAA only when lock appears free (#8)

Documentation

• Document FAA/TTAS design rationale in Lock type and method comments (#8)
• Document intentional FAA-on-failure behavior in Try (#8)

Chore

• Bump Go to 1.26 (#8)

Compatibility

• Go: 1.26+
• Platforms: linux/amd64, linux/arm64, linux/riscv64, linux/loong64, linux/ppc64le, linux/s390x, linux/386, wasm

spin v0.1.4 — Low-latency Spin Primitives for Go

Introduction

Package spin provides minimal spin primitives for low-latency code paths in Go. It offers a non-fair spinlock for ultra-short critical sections, an adaptive spin-wait helper for tight polling loops, architecture-specific CPU pause hints, and cooperative yield functions.

• Supported architectures: amd64, arm64, riscv64, loong64, ppc64le, s390x, 386, wasm.

Usage

// Spinlock for ultra-short critical sections
var lk spin.Lock
lk.Lock()
// critical section
lk.Unlock()

// Adaptive spin-wait
var sw spin.Wait
for !condition {
    sw.Once()
}

// CPU pause hint
spin.Pause()

What's Changed

Improvements

• Add comprehensive benchmarks
• Add Makefile with test, bench, cover, vet, clean targets

Compatibility

• Go: 1.25+
• Platforms: linux/amd64, linux/arm64, linux/riscv64, linux/loong64, linux/ppc64le, linux/s390x, linux/386, js/wasm

spin v0.1.3 — low-latency spin primitives for Go

Overview

spin provides small, low-latency spin primitives for performance-critical Go code paths.

Highlights

• Lock: a minimal, non-fair spinlock designed for extremely short critical sections.
• Wait: an adaptive spin-wait helper that escalates from CPU pause hints to cooperative scheduler yields.
• Pause: an architecture-specific CPU hint intended for tight busy-wait loops; it must not block or yield the scheduler.

Platform support

Optimized implementations are provided on common architectures, with broad multi-arch support:
amd64, arm64, 386, arm, riscv64, ppc64le, s390x, loong64.

Notes

• Lock is intentionally non-fair and is not a general-purpose replacement for sync.Mutex.
• For polling loops, prefer Wait or Pause over ad-hoc runtime.Gosched() loops.

Installation

go get code.hybscloud.com/spin

Changelog

Bug Fixes

• loong64: Fix pauseN using zero register (R0 → R4)
• riscv64: Use PAUSE hint (Zihintpause) instead of FENCE

spin v0.1.2 — low-latency spin primitives for Go

Overview

spin provides small, low-latency spin primitives for performance-critical Go code paths.

Highlights

• Lock: a minimal, non-fair spinlock designed for extremely short critical sections.
• Wait: an adaptive spin-wait helper that escalates from CPU pause hints to cooperative scheduler yields.
• Pause: an architecture-specific CPU hint intended for tight busy-wait loops; it must not block or yield the scheduler.

Platform support

Optimized implementations are provided on common architectures, with broad multi-arch support:
amd64, arm64, 386, arm, riscv64, ppc64le, s390x, loong64.

Notes

• Lock is intentionally non-fair and is not a general-purpose replacement for sync.Mutex.
• For polling loops, prefer Wait or Pause over ad-hoc runtime.Gosched() loops.

Installation

go get code.hybscloud.com/spin

Changelog

Added

• Tests for internal/pause.Pause covering the main control-flow branches.
• An allocation regression guard for Pause to keep it allocation-free in hot paths.

Changed

• No production code changes.

spin v0.1.1 — low-latency spin primitives for Go

Overview

spin provides small, low-latency spin-based primitives for performance-critical Go code paths.

Highlights

• Lock: a minimal, non-fair spinlock designed for extremely short critical sections.
• Wait: an adaptive spin-wait helper that escalates from CPU pause hints to cooperative scheduler yields.
• Pause: an architecture-specific CPU hint intended for tight busy-wait loops; it must not block or yield the scheduler.

Platform support

Optimized implementations are provided on common architectures, with broad multi-arch support:
amd64, arm64, 386, arm, riscv64, ppc64le, s390x, loong64.

Notes

• Lock is intentionally non-fair and is not a general-purpose replacement for sync.Mutex.
• For polling loops, prefer Wait or Pause over ad-hoc runtime.Gosched() loops.

Installation

go get code.hybscloud.com/spin

Changelog

• CI: Fixed Codecov reporting by uploading the generated Go coverage profile during the Linux/amd64 coverage job.

spin v0.1.0 — low-latency spin primitives for Go

Overview

spin provides small, low-latency spin-based primitives for performance-critical Go code paths.

Highlights

• Lock: a minimal, non-fair spinlock designed for extremely short critical sections.
• Wait: an adaptive spin-wait helper that escalates from CPU pause hints to cooperative scheduler yields.
• Pause: an architecture-specific CPU hint intended for tight busy-wait loops; it must not block or yield the scheduler.

Platform support

Optimized implementations are provided on common architectures, with broad multi-arch support:
amd64, arm64, 386, arm, riscv64, ppc64le, s390x, loong64.

Notes

• Lock is intentionally non-fair and is not a general-purpose replacement for sync.Mutex.
• For polling loops, prefer Wait or Pause over ad-hoc runtime.Gosched() loops.

Installation

go get code.hybscloud.com/spin