Module atomic_claim 

Atomic Claim Protocol for Queue Operations

This module provides linearizable “claim + delete” pop semantics for queue operations, ensuring no double-delivery under concurrent access.

Problem: Double-Delivery Under Concurrency

Without atomic claims, a naive “scan → delete” pattern can fail:

Worker A: scan() → finds task T
Worker B: scan() → finds task T  (same task!)
Worker A: delete(T) → success
Worker B: delete(T) → fails or double-processes

Solution: CAS-Based Claim Protocol

The claim is the linearization point. Only one worker can successfully create the claim key, establishing ownership:

Worker A: scan() → finds task T
Worker A: CAS(claim/T, absent → A) → SUCCESS
Worker B: scan() → finds task T
Worker B: CAS(claim/T, absent → B) → FAIL (key exists)
Worker B: retry with next candidate

Lease-Based Crash Recovery

Claims have expiry times. If a worker crashes:

1. Claim expires after lease_duration
2. Next worker’s scan finds task with expired claim
3. New claim can overwrite expired claim
4. Task is reprocessed (at-least-once delivery)

Integration with SochDB’s MVCC/SSI

The claim protocol works with SochDB’s transaction model:

• Claims use MVCC versioning for conflict detection
• The claim key insert is the durability boundary
• SSI’s dangerous-structure detection catches anomalies
• WAL + fsync ensures claim survives crashes

Structs

AtomicClaimManager

Atomic claim manager for queue task ownership

ClaimStats

Statistics for claim operations

ClaimToken

A token proving ownership of a claimed task

LeaseConfig

Configuration for lease management

LeaseManager

Higher-level lease manager with periodic cleanup

Enums

ClaimResult

Result of attempting to claim a task

Traits

CompareAndSwap

Compare-and-swap trait for storage backends