surelock 0.1.0

Deadlock-free locks for Rust with compile time guarantees, incremental locks, and atomic lock sets.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

# Surelock Design

Surelock prevents deadlocks by breaking the circular-wait [Coffman condition](https://en.wikipedia.org/wiki/Deadlock_(computer_science)) via two complementary mechanisms that do not overlap.

It answers: _"can my program deadlock?"_ If the program compiles, it cannot.

## Type Lifecycle

```text
┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐
│ Explicit multi-core
                      │
│      Locksmith
        (forge)       │   ┌ ─ ─ ─ ─ ─ ─ ─ ┐
│          │              │ std (default)
           ▼          │                   │
│     KeyVoucher          │   KeyHandle
      (deliver)       │        (claim)    │
└ ─ ─ ─ ─ ┼ ─ ─ ─ ─ ─ ┘   └ ─ ─ ─ ┼ ─ ─ ─ ┘
          │                       │
          └────────────┬──────────┘
                       │
                       ▼
                    MutexKey
                    (scope)
                       │
                       ├───▶ MutexGuard(s)
                       │      (access)
                       ▼
                    MutexKey
                   (subscope)
                       │
                       ├───▶ MutexGuard(s)
                       │      (access)
                       ▼
                      ...
```

## Two Mechanisms

| Mechanism  | Granularity | Acquisition | Enforcement     |
|------------|-------------|-------------|-----------------|
| `LockSet`  | Fine        | Atomic      | By construction |
| Levels     | Coarse      | Incremental | Compile-time    |

**Atomically acquire multiple locks**: `LockSet` acquires multiple locks atomically, sorted by monotonic `LockId`. The order is always consistent across threads -- no cycle can form.

**Incremental acquisition / across levels**: `Level<N>` types with `LockAfter` trait bounds enforce strictly ascending acquisition. The `MutexKey` is consumed and re-emitted at each level. Wrong-order acquisition is a compile error, not a runtime failure.

Every lock call is either _infallible (correct-by-construction) or doesn't compile_.

## Coffman Condition Analysis

| Condition        | Addressed?   | Mechanism                                             |
|------------------|--------------|-------------------------------------------------------|
| Mutual exclusion | No           | Inherent to mutexes                                   |
| Hold and wait    | Within level | `LockSet` atomic acquisition                          |
| No preemption    | No           | Inherent to cooperative locks                         |
| Circular wait    | Yes          | `LockSet` sorts by `LockId`; levels enforce ascending |

Circular-wait prevention is sufficient on its own to prevent deadlock. Hold-and-wait is present across levels (you hold locks while waiting for more at higher levels) but does not matter because circular wait is broken.

## Design Principles

- _Parse, don't validate._ The type system encodes ordering invariants directly. Invalid lock orders are unrepresentable, not just checked.
- _One mechanism per concern._ `LockSet` handles same-level ordering. Levels handle cross-level ordering. They do not overlap and need not know about each other.
- _Static over dynamic._ Prefer compile-time enforcement over runtime checks. The only runtime checks are scope uniqueness (`thread_local!` on `std`) and `Locksmith` singleton enforcement (`AtomicBool`). Lock ordering itself is fully static.
- _`no_std` is a first-class target._ The core library has no dependency on `std`. The `std` feature adds convenience (`StdMutex` default backend, `lock_scope` / `try_lock_scope` ambient entry points, `thread_local!` scope uniqueness). On `no_std`, `KeyHandle` with `scope(&mut self)` provides static nesting prevention without `thread_local!`.
- _Minimal unsafe surface._ `#![deny(unsafe_code)]` at the crate level. Only 6 of 15 source files opt in. The public API is fully safe.

## Documents

| Document                                           | Contents                                     |
|----------------------------------------------------|----------------------------------------------|
| [comparison/happylock.md](comparison/happylock.md) | Comparison with `happylock`                  |
| [comparison/lock_tree.md](comparison/lock_tree.md) | Comparison with `lock_tree`                  |
| [ROADMAP.md](ROADMAP.md)                           | Planned features and design sketches for v2+ |