google / google/uuid

Proposal: Lock-free CAS monotonicity and branchless hex decoding for UUIDv7 (73% faster under contention)

Open
#226 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
6.1k
Forks
440
PR merge metrics
No merged PRs in 30d

Description

### Proposal: Lock-free CAS monotonicity and branchless hex decoding for UUIDv7

#### 1. Context & Motivation
Under high-throughput concurrent workloads (e.g. multi-goroutine ingestion pipelines, high-frequency RPC handlers), `NewV7()` experiences lock contention due to serializing on a global `sync.Mutex` for timestamp monotonicity and sub-millisecond sequencing.

In addition, hexadecimal parsing and formatting currently rely on multiple sub-slicing steps and repeated `hex.Encode` / `hex.Decode` calls, which introduces branch mispredictions and bounds checks.

#### 2. Technical Proposals
1. **Lock-Free Atomic Compare-And-Swap Monotonicity (RFC 9562 §6.2):**
Replace the global mutex with an atomic Compare-And-Swap (`atomic.Uint64`) state machine on the combined millisecond timestamp + sub-millisecond fraction. In case of clock rollback or sub-millisecond burst contention (`cur <= prev`), `cur = prev + 1` guarantees strict lexicographical ordering without blocking OS threads.
2. **Branchless Hexadecimal Lookup Table:**
Use a 256-byte static lookup table to parse 36-byte canonical and 32-byte compact UUID strings in a single pass without conditional branching.
3. **In-Place Stack Formatting:**
Direct in-place nibble encoding into stack buffers (`*[36]byte`), eliminating intermediate heap allocations.

#### 3. Benchmark Results (`benchstat -count=10` on Intel Core i9-14900K, 32 Goroutines)

```
goos: linux
goarch: amd64
pkg: github.com/google/uuid
cpu: Intel(R) Core(TM) i9-14900K
│ old.txt │ new.txt │
│ sec/op │ sec/op vs base │
NewV7_Parallel-32 161.85n ± 3% 43.40n ± 9% -73.19% (p=0.000 n=10)
NewV7_SingleThread-32 59.59n ± 3% 35.13n ± 1% -41.05% (p=0.000 n=10)
Format_InPlace-32 14.400n ± 6% 5.960n ± 4% -58.61% (p=0.000 n=10)
Format_String-32 29.89n ± 4% 20.32n ± 5% -32.02% (p=0.000 n=10)
Parse_Bytes-32 17.64n ± 4% 12.25n ± 5% -30.53% (p=0.000 n=10)
geomean 37.41n 18.66n -50.11%

│ old.txt │ new.txt │
│ B/op │ B/op vs base │
NewV7_Parallel-32 0.000 ± 0% 0.000 ± 0% ~ (p=1.000 n=10)
NewV7_SingleThread-32 0.000 ± 0% 0.000 ± 0% ~ (p=1.000 n=10)
Format_InPlace-32 0.000 ± 0% 0.000 ± 0% ~ (p=1.000 n=10)
Format_String-32 48.00 ± 0% 48.00 ± 0% ~ (p=1.000 n=10)
Parse_Bytes-32 0.000 ± 0% 0.000 ± 0% ~ (p=1.000 n=10)
```

#### 4. Verification & Reference Implementation
* 100% compliant with RFC 9562 §5.7 and §6.2 (verified against a C99 oracle with 160,000 concurrent assertions and 100,000 Monte-Carlo passes).
* Zero API breaks; fully backward compatible.
* Standalone reference implementation available for inspection: https://github.com/hazyhaar/c2uuidv7

We would be glad to submit a PR if this direction is aligned with the maintainers' roadmap.

Contributor guide

Open the contributing guide

Research direction

The proposal names NewV7(), UUID parsing, and formatting as the affected entry points; read those implementations and the cited RFC 9562 sections before assessing the design. Reproduce the listed benchmarks and concurrency checks, then consider the work done only if ordering, parsing and formatting behavior, compatibility, and the claimed performance are validated.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
performance
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.