use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize, Ordering};
use std::sync::OnceLock;
use std::thread;
#[cfg(target_pointer_width = "64")]
const THREADS_BITS: usize = 16;
#[cfg(target_pointer_width = "32")]
const THREADS_BITS: usize = 8;
#[allow(clippy::erasing_op)]
const SLEEPING_SHIFT: usize = 0 * THREADS_BITS;
#[allow(clippy::identity_op)]
const INACTIVE_SHIFT: usize = 1 * THREADS_BITS;
const JEC_SHIFT: usize = 2 * THREADS_BITS;
pub(crate) const THREADS_MAX: usize = (1 << THREADS_BITS) - 1;
const ONE_SLEEPING: usize = 1;
const ONE_INACTIVE: usize = 1 << INACTIVE_SHIFT;
const ONE_JEC: usize = 1 << JEC_SHIFT;
pub(crate) struct AtomicCounters {
value: AtomicUsize,
}
#[derive(Copy, Clone)]
pub(crate) struct Counters {
word: usize,
}
#[derive(Copy, Clone, Debug, PartialEq, PartialOrd)]
pub(crate) struct JobsEventCounter(usize);
impl JobsEventCounter {
pub(crate) const DUMMY: JobsEventCounter = JobsEventCounter(usize::MAX);
#[inline]
#[allow(dead_code)]
pub(crate) fn as_usize(self) -> usize {
self.0
}
#[inline]
pub(crate) fn is_sleepy(self) -> bool {
(self.0 & 1) == 0
}
#[inline]
pub(crate) fn is_active(self) -> bool {
!self.is_sleepy()
}
}
#[inline]
fn select_thread(word: usize, shift: usize) -> usize {
(word >> shift) & THREADS_MAX
}
#[inline]
fn select_jec(word: usize) -> usize {
word >> JEC_SHIFT
}
impl AtomicCounters {
pub(crate) const fn new() -> Self {
Self { value: AtomicUsize::new(0) }
}
#[inline]
pub(crate) fn load(&self, ordering: Ordering) -> Counters {
Counters { word: self.value.load(ordering) }
}
#[inline]
fn raw(&self, ordering: Ordering) -> usize {
self.value.load(ordering)
}
#[inline]
fn line(&self) -> *const u8 {
(&raw const self.value).cast::<u8>()
}
#[inline]
fn try_exchange(&self, old: Counters, new: Counters, ordering: Ordering) -> bool {
self.value
.compare_exchange(old.word, new.word, ordering, Ordering::Relaxed)
.is_ok()
}
#[inline]
pub(crate) fn add_inactive_thread(&self) {
self.value.fetch_add(ONE_INACTIVE, Ordering::SeqCst);
}
#[inline]
pub(crate) fn sub_inactive_thread(&self) -> usize {
let old = Counters {
word: self.value.fetch_sub(ONE_INACTIVE, Ordering::SeqCst),
};
debug_assert!(old.inactive_threads() > 0);
debug_assert!(old.sleeping_threads() <= old.inactive_threads());
let sleepers = old.sleeping_threads();
Ord::min(sleepers, 2)
}
#[inline]
pub(crate) fn sub_sleeping_thread(&self) {
let old = Counters {
word: self.value.fetch_sub(ONE_SLEEPING, Ordering::SeqCst),
};
debug_assert!(old.sleeping_threads() > 0);
}
#[inline]
pub(crate) fn try_add_sleeping_thread(&self, old: Counters) -> bool {
debug_assert!(old.inactive_threads() > 0);
debug_assert!(old.sleeping_threads() < THREADS_MAX);
let mut new = old;
new.word += ONE_SLEEPING;
self.try_exchange(old, new, Ordering::SeqCst)
}
pub(crate) fn increment_jobs_event_counter_if(
&self,
pred: impl Fn(JobsEventCounter) -> bool,
) -> Counters {
loop {
let old = self.load(Ordering::SeqCst);
if pred(old.jobs_counter()) {
let new = Counters {
word: old.word.wrapping_add(ONE_JEC),
};
if self.try_exchange(old, new, Ordering::SeqCst) {
return new;
}
} else {
return old;
}
}
}
}
impl Counters {
#[inline]
pub(crate) fn jobs_counter(self) -> JobsEventCounter {
JobsEventCounter(select_jec(self.word))
}
#[inline]
pub(crate) fn inactive_threads(self) -> usize {
select_thread(self.word, INACTIVE_SHIFT)
}
#[inline]
pub(crate) fn sleeping_threads(self) -> usize {
select_thread(self.word, SLEEPING_SHIFT)
}
#[inline]
pub(crate) fn awake_but_idle_threads(self) -> usize {
debug_assert!(self.sleeping_threads() <= self.inactive_threads());
self.inactive_threads() - self.sleeping_threads()
}
}
impl std::fmt::Debug for Counters {
fn fmt(&self, fmt: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
fmt.debug_struct("Counters")
.field("word", &format!("{:016x}", self.word))
.field("jobs", &self.jobs_counter().0)
.field("inactive", &self.inactive_threads())
.field("sleeping", &self.sleeping_threads())
.finish()
}
}
const ROUNDS_UNTIL_SLEEPY: u32 = 32;
const DEFAULT_SPIN_WINDOW_ROUNDS: u32 = 500;
const FLOOR_SPIN_WINDOW_ROUNDS: u32 = 8;
const SLEEPLESS_BEFORE_BACKOFF: u32 = 4;
const SLEEPLESS_BACKOFF_FLOOR: std::time::Duration =
std::time::Duration::from_micros(250);
const SLEEPLESS_BACKOFF_CAP: std::time::Duration =
std::time::Duration::from_millis(32);
static SLEEPLESS_BACKOFFS: AtomicU64 = AtomicU64::new(0);
fn sleepless_backoff(n: u32) -> std::time::Duration {
let steps = n.saturating_sub(SLEEPLESS_BEFORE_BACKOFF).min(16);
SLEEPLESS_BACKOFF_FLOOR
.saturating_mul(1u32 << steps)
.min(SLEEPLESS_BACKOFF_CAP)
}
pub fn total_sleepless_backoffs() -> u64 {
SLEEPLESS_BACKOFFS.load(Ordering::Relaxed)
}
static SELF_RESCUES: AtomicU64 = AtomicU64::new(0);
pub fn total_self_rescues() -> u64 {
SELF_RESCUES.load(Ordering::Relaxed)
}
pub fn total_park_events() -> u64 {
u64::from(PARK_EVENTS.load(Ordering::Relaxed))
}
pub fn total_rescue_events() -> u64 {
u64::from(RESCUE_EVENTS.load(Ordering::Relaxed))
}
pub fn total_monitor_rounds() -> u64 {
TOTAL_MONITOR_ROUNDS.load(Ordering::Relaxed)
}
#[inline]
fn spin_round_cycles() -> u64 {
round_cycles(
crate::sched::par_iter::installed_dispatch_cost_ns(),
crate::sched::par_iter::tsc_per_ns_16(),
)
}
#[inline]
fn round_cycles(dispatch_cost_ns: u64, per_ns_16: u64) -> u64 {
dispatch_cost_ns.saturating_mul(per_ns_16) / 16
}
static SPIN_WINDOW: AtomicU32 = AtomicU32::new(DEFAULT_SPIN_WINDOW_ROUNDS);
static ADAPTIVE: AtomicBool = AtomicBool::new(false);
static PARK_EVENTS: AtomicU32 = AtomicU32::new(0);
static RESCUE_EVENTS: AtomicU32 = AtomicU32::new(0);
static TOTAL_YIELDS: AtomicU64 = AtomicU64::new(0);
static TOTAL_MONITOR_ROUNDS: AtomicU64 = AtomicU64::new(0);
static ADAPT_DECISIONS: AtomicU64 = AtomicU64::new(0);
fn spin_init() {
static INIT: OnceLock<()> = OnceLock::new();
INIT.get_or_init(|| {
if let Some(v) = std::env::var("FLYNNEL_SPIN_WINDOW_ROUNDS")
.ok()
.and_then(|s| s.parse::<u32>().ok())
{
SPIN_WINDOW.store(v, Ordering::Relaxed);
ADAPTIVE.store(false, Ordering::Relaxed);
}
if std::env::var("FLYNNEL_ADAPTIVE_SPIN").as_deref() == Ok("1") {
ADAPTIVE.store(true, Ordering::Relaxed);
}
});
}
#[inline]
fn rounds_until_sleeping() -> u32 {
spin_init();
ROUNDS_UNTIL_SLEEPY + SPIN_WINDOW.load(Ordering::Relaxed)
}
const EVIDENCE_FLOOR: u32 = 256;
#[inline]
fn should_adapt(adaptive: bool, park: u32, rescue: u32) -> bool {
adaptive && park.saturating_add(rescue) >= EVIDENCE_FLOOR
}
#[inline]
fn adapted_window(cur: u32, park: u32, rescue: u32) -> u32 {
if park > rescue.saturating_mul(3) {
(cur / 2).max(FLOOR_SPIN_WINDOW_ROUNDS)
} else if rescue > park {
(cur + cur / 4 + 1).min(DEFAULT_SPIN_WINDOW_ROUNDS)
} else {
cur
}
}
fn maybe_adapt() {
let park = PARK_EVENTS.load(Ordering::Relaxed);
let rescue = RESCUE_EVENTS.load(Ordering::Relaxed);
if !should_adapt(ADAPTIVE.load(Ordering::Relaxed), park, rescue) {
return;
}
ADAPT_DECISIONS.fetch_add(1, Ordering::Relaxed);
let cur = SPIN_WINDOW.load(Ordering::Relaxed);
SPIN_WINDOW.store(adapted_window(cur, park, rescue), Ordering::Relaxed);
PARK_EVENTS.store(0, Ordering::Relaxed);
RESCUE_EVENTS.store(0, Ordering::Relaxed);
}
pub fn spin_window() -> u32 {
SPIN_WINDOW.load(Ordering::Relaxed)
}
pub fn total_idle_yields() -> u64 {
TOTAL_YIELDS.load(Ordering::Relaxed)
}
pub fn spin_adapt_decisions() -> u64 {
ADAPT_DECISIONS.load(Ordering::Relaxed)
}
pub fn reset_spin_stats() {
TOTAL_YIELDS.store(0, Ordering::Relaxed);
PARK_EVENTS.store(0, Ordering::Relaxed);
RESCUE_EVENTS.store(0, Ordering::Relaxed);
}
pub fn set_spin_window(rounds: u32) {
spin_init();
SPIN_WINDOW.store(rounds, Ordering::Relaxed);
ADAPTIVE.store(false, Ordering::Relaxed);
}
pub fn set_spin_adaptive(on: bool) {
ADAPTIVE.store(on, Ordering::Relaxed);
}
pub fn spin_adaptive() -> bool {
spin_init();
ADAPTIVE.load(Ordering::Relaxed)
}
#[repr(align(128))]
struct WorkerSleepState {
state: AtomicU32,
handle: OnceLock<thread::Thread>,
}
const AWAKE: u32 = 0;
const SLEEPING: u32 = 1;
const WAKING: u32 = 2;
pub(crate) struct IdleState {
pub worker_index: usize,
pub rounds: u32,
pub jobs_counter: JobsEventCounter,
pub parked: bool,
pub(crate) sleepless: u32,
}
impl IdleState {
pub(crate) fn new(worker_index: usize) -> Self {
Self {
worker_index,
rounds: 0,
jobs_counter: JobsEventCounter::DUMMY,
parked: false,
sleepless: 0,
}
}
fn wake_fully(&mut self) {
self.rounds = 0;
self.jobs_counter = JobsEventCounter::DUMMY;
}
fn wake_partly(&mut self) {
self.rounds = ROUNDS_UNTIL_SLEEPY;
self.jobs_counter = JobsEventCounter::DUMMY;
}
}
pub(crate) struct SleepDebug {
pub(crate) sleeping: usize,
pub(crate) inactive: usize,
pub(crate) jec: usize,
pub(crate) blocked: Vec<bool>,
}
pub(crate) struct Sleep {
counters: AtomicCounters,
worker_states: Vec<WorkerSleepState>,
claimed_slots: AtomicU64,
shutdown: AtomicBool,
}
impl Sleep {
pub(crate) fn new(num_workers: usize) -> Self {
assert!(num_workers <= THREADS_MAX, "too many workers");
let mut states = Vec::with_capacity(num_workers);
for _ in 0..num_workers {
states.push(WorkerSleepState {
state: AtomicU32::new(AWAKE),
handle: OnceLock::new(),
});
}
Self {
counters: AtomicCounters::new(),
worker_states: states,
claimed_slots: AtomicU64::new(0),
shutdown: AtomicBool::new(false),
}
}
#[inline]
pub(crate) fn worker_count(&self) -> usize {
self.worker_states.len()
}
#[inline]
pub(crate) fn note_slot_claimed(&self, slot_id: usize) {
self.claimed_slots.fetch_or(1u64 << slot_id, Ordering::Release);
}
#[inline]
pub(crate) fn note_slot_released(&self, slot_id: usize) {
self.claimed_slots.fetch_and(!(1u64 << slot_id), Ordering::Release);
}
#[inline]
pub(crate) fn claimed_slots(&self) -> u64 {
self.claimed_slots.load(Ordering::Acquire)
}
#[allow(dead_code)]
pub(crate) fn num_workers(&self) -> usize {
self.worker_states.len()
}
pub(crate) fn debug_state(&self) -> SleepDebug {
let c = self.counters.load(Ordering::SeqCst);
let blocked = self
.worker_states
.iter()
.map(|s| s.state.load(Ordering::Relaxed) != AWAKE)
.collect();
SleepDebug {
sleeping: c.sleeping_threads(),
inactive: c.inactive_threads(),
jec: c.jobs_counter().as_usize(),
blocked,
}
}
#[inline]
pub(crate) fn start_looking(&self, worker_index: usize) -> IdleState {
self.counters.add_inactive_thread();
IdleState::new(worker_index)
}
#[inline]
pub(crate) fn work_found(&self, idle: &IdleState) {
if idle.rounds > ROUNDS_UNTIL_SLEEPY && !idle.parked {
RESCUE_EVENTS.fetch_add(1, Ordering::Relaxed);
}
let wake_count = self.counters.sub_inactive_thread();
if wake_count > 0 {
self.wake_any_threads(wake_count as u32);
}
}
#[inline]
fn idle_round(&self, idle: &IdleState) {
TOTAL_YIELDS.fetch_add(1, Ordering::Relaxed);
if crate::sched::levers::spin_monitor() {
let budget = spin_round_cycles();
if budget > 0 {
let seen = self.counters.raw(Ordering::Relaxed);
let waited = unsafe {
crate::sched::sleep::monitor_wait_once(self.counters.line(), budget, || {
self.counters.raw(Ordering::Relaxed) != seen
})
};
if waited {
TOTAL_MONITOR_ROUNDS.fetch_add(1, Ordering::Relaxed);
if idle.rounds == 0 && crate::sched::trace::is_enabled() {
crate::sched::trace::emit(
crate::sched::trace::TraceEvent::SpinMonitor,
if crate::cpu_info::has_waitpkg() { 1 } else { 2 },
);
}
return;
}
}
}
if crate::sched::levers::join_park_oversubscribed() {
crate::sched::oversubscription::timed_yield();
} else {
thread::yield_now();
}
}
pub(crate) fn no_work_found(
&self,
idle: &mut IdleState,
has_reachable_work: impl Fn() -> bool,
) {
if idle.rounds < ROUNDS_UNTIL_SLEEPY {
self.idle_round(idle);
idle.rounds += 1;
} else if idle.rounds == ROUNDS_UNTIL_SLEEPY {
idle.jobs_counter = self.announce_sleepy();
idle.rounds += 1;
self.idle_round(idle);
} else if idle.rounds < rounds_until_sleeping() {
idle.rounds += 1;
self.idle_round(idle);
} else {
self.sleep(idle, has_reachable_work);
if idle.sleepless >= SLEEPLESS_BEFORE_BACKOFF {
SLEEPLESS_BACKOFFS.fetch_add(1, Ordering::Relaxed);
thread::sleep(sleepless_backoff(idle.sleepless));
}
}
}
fn announce_sleepy(&self) -> JobsEventCounter {
self.counters
.increment_jobs_event_counter_if(JobsEventCounter::is_active)
.jobs_counter()
}
fn sleep(
&self,
idle: &mut IdleState,
has_reachable_work: impl Fn() -> bool,
) {
let state = &self.worker_states[idle.worker_index];
debug_assert_eq!(state.state.load(Ordering::Relaxed), AWAKE);
if self.shutdown.load(Ordering::Acquire) {
idle.wake_partly();
return;
}
loop {
let counters = self.counters.load(Ordering::SeqCst);
debug_assert!(idle.jobs_counter.is_sleepy());
if counters.jobs_counter() != idle.jobs_counter {
idle.sleepless = idle.sleepless.saturating_add(1);
idle.wake_partly();
return;
}
if self.counters.try_add_sleeping_thread(counters) {
break;
}
}
std::sync::atomic::fence(Ordering::SeqCst);
if has_reachable_work() {
self.counters.sub_sleeping_thread();
idle.sleepless = idle.sleepless.saturating_add(1);
} else {
state.handle.get_or_init(thread::current);
state.state.store(SLEEPING, Ordering::SeqCst);
std::sync::atomic::fence(Ordering::SeqCst);
if (self.shutdown.load(Ordering::SeqCst) || has_reachable_work())
&& state
.state
.compare_exchange(SLEEPING, AWAKE, Ordering::SeqCst, Ordering::SeqCst)
.is_ok()
{
self.counters.sub_sleeping_thread();
SELF_RESCUES.fetch_add(1, Ordering::Relaxed);
idle.sleepless = idle.sleepless.saturating_add(1);
idle.wake_fully();
return;
}
idle.parked = true;
idle.sleepless = 0;
PARK_EVENTS.fetch_add(1, Ordering::Relaxed);
crate::sched::trace::emit(
crate::sched::trace::TraceEvent::PoolPark,
idle.worker_index as u32,
);
maybe_adapt();
while state.state.load(Ordering::Acquire) != AWAKE {
thread::park();
}
}
idle.wake_fully();
}
#[inline]
pub(crate) fn new_internal_jobs(&self, num_jobs: u32, queue_was_empty: bool) {
let counters = self
.counters
.increment_jobs_event_counter_if(JobsEventCounter::is_sleepy);
let awake_but_idle = counters.awake_but_idle_threads() as u32;
let num_sleepers = counters.sleeping_threads() as u32;
if num_sleepers == 0 {
return;
}
if !queue_was_empty {
let n = num_jobs.min(num_sleepers);
self.wake_any_threads(n);
} else if awake_but_idle < num_jobs {
let n = (num_jobs - awake_but_idle).min(num_sleepers);
self.wake_any_threads(n);
}
}
pub(crate) fn wake_worker(&self, idx: usize) -> bool {
if idx >= self.worker_states.len() {
return false;
}
if self.worker_states[idx].state.load(Ordering::Acquire) != SLEEPING {
return false;
}
let woke = self.wake_specific_thread(idx);
if woke {
crate::sched::trace::emit(crate::sched::trace::TraceEvent::PoolWake, idx as u32);
}
woke
}
fn wake_any_threads(&self, mut num: u32) {
if num == 0 {
return;
}
for i in 0..self.worker_states.len() {
if self.wake_specific_thread(i) {
crate::sched::trace::emit(crate::sched::trace::TraceEvent::PoolWake, i as u32);
num -= 1;
if num == 0 {
return;
}
}
}
}
fn wake_specific_thread(&self, idx: usize) -> bool {
let state = &self.worker_states[idx];
if state
.state
.compare_exchange(SLEEPING, WAKING, Ordering::SeqCst, Ordering::SeqCst)
.is_err()
{
return false;
}
self.counters.sub_sleeping_thread();
state.state.store(AWAKE, Ordering::SeqCst);
if let Some(handle) = state.handle.get() {
handle.unpark();
}
true
}
pub(crate) fn wake_all_for_shutdown(&self) {
self.shutdown.store(true, Ordering::SeqCst);
for i in 0..self.worker_states.len() {
self.wake_specific_thread(i);
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_monitor_round_is_the_dispatch_cost_in_cycles_and_zero_without_a_profile() {
assert_eq!(round_cycles(400, 64), 1_600);
assert_eq!(round_cycles(2_000, 55), 6_875);
assert_eq!(round_cycles(0, 64), 0, "no profile is no wait");
assert_eq!(round_cycles(400, 0), 0, "no rate is no wait");
assert_eq!(
round_cycles(u64::MAX, 64),
u64::MAX / 16,
"saturates rather than wraps"
);
}
#[test]
fn a_window_that_keeps_being_missed_shrinks_toward_the_floor() {
let mut window = adapted_window(DEFAULT_SPIN_WINDOW_ROUNDS, 300, 4);
assert_eq!(window, DEFAULT_SPIN_WINDOW_ROUNDS / 2);
for _ in 0..12 {
window = adapted_window(window, 300, 4);
}
assert_eq!(window, FLOOR_SPIN_WINDOW_ROUNDS);
}
#[test]
fn a_window_that_keeps_paying_grows_back_but_never_past_the_tuned_default() {
let mut window = FLOOR_SPIN_WINDOW_ROUNDS;
for _ in 0..64 {
window = adapted_window(window, 4, 300);
}
assert_eq!(window, DEFAULT_SPIN_WINDOW_ROUNDS);
}
#[test]
fn one_burst_does_not_move_the_window() {
assert!(!should_adapt(true, 200, 0), "200 parks is under the floor");
assert!(
should_adapt(true, 200, EVIDENCE_FLOOR - 200),
"the floor counts parks and rescues together"
);
}
#[test]
fn a_held_window_tells_a_controller_that_ran_from_one_that_never_reached_the_gate() {
assert!(
should_adapt(true, 4, 300),
"this much evidence reaches the gate"
);
assert_eq!(
adapted_window(DEFAULT_SPIN_WINDOW_ROUNDS, 4, 300),
DEFAULT_SPIN_WINDOW_ROUNDS,
"clamped to where it began"
);
}
#[test]
fn the_controller_stays_still_while_it_is_off() {
assert!(
!should_adapt(false, 1_000, 0),
"evidence past the floor still decides nothing while it is off"
);
assert!(
should_adapt(true, 1_000, 0),
"and the same evidence decides once it is on"
);
}
#[test]
fn counters_initial_state_is_zero() {
let c = AtomicCounters::new();
let snap = c.load(Ordering::SeqCst);
assert_eq!(snap.inactive_threads(), 0);
assert_eq!(snap.sleeping_threads(), 0);
assert_eq!(snap.awake_but_idle_threads(), 0);
}
#[test]
fn add_then_sub_inactive_returns_to_zero() {
let c = AtomicCounters::new();
c.add_inactive_thread();
assert_eq!(c.load(Ordering::SeqCst).inactive_threads(), 1);
c.sub_inactive_thread();
assert_eq!(c.load(Ordering::SeqCst).inactive_threads(), 0);
}
#[test]
fn jec_starts_sleepy_and_flips_active_on_increment() {
let c = AtomicCounters::new();
let snap = c.load(Ordering::SeqCst);
assert!(snap.jobs_counter().is_sleepy());
let after = c.increment_jobs_event_counter_if(|_| true);
assert!(after.jobs_counter().is_active());
}
#[test]
fn sleep_struct_constructs_with_n_workers() {
let s = Sleep::new(8);
assert_eq!(s.num_workers(), 8);
}
}