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
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
//! Idempotent job contract: a marker trait
//! whose impl asserts the job body is safe to execute more than
//! once. Pairs with fence-free work-stealing variants where the
//! cross-worker race can lose a steal-vs-pop conflict by
//! executing the same job twice rather than blocking.
//!
//! The [`crate::sched::arena_local`] worker loop enforces
//! exactly-once execution via Chase-Lev's atomic counters; this
//! trait is the opt-in contract for fence-free variants that trade
//! brief multiplicity windows for one fewer Acquire fence per
//! local pop.
//!
//! Most op bodies are NOT idempotent; they mutate a
//! Vec output, increment a counter, or read+write a shared
//! accumulator. The few that ARE idempotent (pure indexed-collect
//! over a `MaybeUninit` buffer where each slot is written once;
//! pure read-only fold) can opt in via this trait.
//!
//! # Examples
//!
//! ```
//! use flynnel::sched::idempotent::IdempotentJob;
//!
//! // Pure-read filter is idempotent: running the closure on the
//! // same range produces the same result with no side effects.
//! struct PureFilter<'a>(&'a [u32]);
//! impl<'a> IdempotentJob for PureFilter<'a> {
//! type Output = u64;
//! fn run(&self, start: usize, end: usize) -> u64 {
//! self.0[start..end].iter().map(|&x| x as u64).sum()
//! }
//! }
//! ```
/// Marker for a job whose body is safe to execute more than once
/// without producing incorrect output or violating invariants.
///
/// A job is **idempotent** when:
/// - The body is a pure function of the input range (no side
/// effects that depend on call count).
/// - Writes go through `MaybeUninit` slots that each closure call
/// would write to the same value, OR the writes never observe
/// their own prior state.
///
/// Examples:
/// - Pure `Fn(usize) -> R` indexed-collect - idempotent IF the
/// closure has no captured mutable state.
/// - Read-only fold like `sum`, `max`, `count` - idempotent.
/// - Per-tile matmul that writes into a fresh accumulator buffer -
/// idempotent IF the buffer is zeroed before each call attempt.
///
/// Counter-examples (NOT idempotent):
/// - Anything that `fetch_add`s an atomic counter - running twice
/// double-counts.
/// - Pushing onto a shared `Vec` - running twice double-pushes.
/// - Newton iteration where each step reads its previous output -
/// running twice perturbs convergence.
/// Dispatch helper for idempotent jobs: runs the body, returning
/// its output. This is the entry point that an idempotent-aware
/// worker loop would call. Provided in the trait surface so the
/// production wiring path (when added) has a stable API target.
// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------