use std::fmt;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Condvar, Mutex};
use std::time::{Duration, Instant};
use snare_interpose::{Domain, ThreadClass};
use crate::clock::{self, Clock, nanos};
use crate::readiness::readiness;
use crate::scope::SimShared;
pub use snare_interpose::{
AuditReport, BlockerKind, ClassEffect, PState, ParticipantInfo, Quiescence, QuiescenceViolation,
};
#[derive(Clone, Debug, Default)]
pub struct ExecutiveConfig {
pub audit: bool,
}
#[derive(Copy, Clone, Debug)]
pub struct Grant {
pub anchor_v: Duration,
pub anchor_wall: Instant,
pub rate: f64,
pub horizon: Duration,
}
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum AttachError {
AlreadyAttached,
NotInSim,
WallClock,
}
impl fmt::Display for AttachError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(match self {
AttachError::AlreadyAttached => "this Sim's clock is already owned by an Executive",
AttachError::NotInSim => "must be called from a thread running inside Sim::run",
AttachError::WallClock => {
"this Sim runs on the real clock (SimBuilder::wall_clock) and has no clock to own"
}
})
}
}
impl std::error::Error for AttachError {}
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub struct NotQuiescent;
impl fmt::Display for NotQuiescent {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str("the simulation is not quiescent")
}
}
impl std::error::Error for NotQuiescent {}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct TimerInfo {
pub deadline: Duration,
pub owner: Option<Arc<str>>,
}
struct Flow {
state: Mutex<FlowState>,
changed: Condvar,
}
#[derive(Default)]
struct FlowState {
started: bool,
stop: bool,
}
const FLOW_IDLE: Duration = Duration::from_millis(200);
impl Flow {
fn lock(&self) -> std::sync::MutexGuard<'_, FlowState> {
self.state.lock().unwrap_or_else(|e| e.into_inner())
}
fn changed(self: &Arc<Self>, flowing: bool, clock: &Arc<Clock>, shared: &Arc<SimShared>) {
let start = {
let mut st = self.lock();
let start = flowing && !st.started && !st.stop;
st.started |= start;
start
};
self.changed.notify_all();
if start {
let (flow, clock, shared) = (self.clone(), clock.clone(), shared.clone());
snare_interpose::real(|| {
std::thread::Builder::new()
.name("snare-executive-flow".into())
.spawn(move || {
let _service = snare_interpose::service_thread();
flow.run(&clock, &shared);
})
.expect("start the executive's flow waker")
});
}
}
fn run(&self, clock: &Clock, shared: &SimShared) {
let mut st = self.lock();
loop {
if st.stop {
return;
}
let wait = match clock.next_flow_wake() {
None => FLOW_IDLE,
Some(at) => {
let now = nanos(crate::readiness::real_now());
if at > now {
Duration::from_nanos(at - now).min(FLOW_IDLE)
} else {
drop(st);
let now = clock.peek();
let (_, wakers) = clock.fire_upto(now, now);
wakers.into_iter().for_each(std::task::Waker::wake);
shared.kick();
st = self.lock();
continue;
}
}
};
st = self
.changed
.wait_timeout(st, wait)
.unwrap_or_else(|e| e.into_inner())
.0;
}
}
fn stop(&self) {
self.lock().stop = true;
self.changed.notify_all();
}
}
pub struct Executive {
shared: Arc<SimShared>,
clock: Arc<Clock>,
domain: Domain,
cfg: ExecutiveConfig,
flow: Arc<Flow>,
warned_rate: AtomicBool,
}
fn audit_env() -> bool {
snare_interpose::real(|| std::env::var("SNARE_SCHED_AUDIT"))
.is_ok_and(|v| !v.is_empty() && v != "0")
}
pub(crate) fn attach_to(
shared: Arc<SimShared>,
domain: Domain,
cfg: ExecutiveConfig,
) -> Result<Executive, AttachError> {
let Some(clock) = shared.clock.clone() else {
return Err(AttachError::WallClock);
};
if shared.executive.swap(true, Ordering::AcqRel) {
return Err(AttachError::AlreadyAttached);
}
if !domain.attach_executive(cfg.audit || audit_env()) {
shared.executive.store(false, Ordering::Release);
return Err(AttachError::AlreadyAttached);
}
let wakers = snare_interpose::real(|| {
clock.attach_driven();
let now = clock.peek();
clock.fire_upto(now, now).1
});
wake(wakers);
shared.kick();
Ok(Executive {
shared,
clock,
domain,
cfg,
flow: Arc::new(Flow {
state: Mutex::default(),
changed: Condvar::new(),
}),
warned_rate: AtomicBool::new(false),
})
}
pub fn attach(cfg: ExecutiveConfig) -> Result<Executive, AttachError> {
let shared = crate::scope::try_here().ok_or(AttachError::NotInSim)?;
let domain = Domain::current().ok_or(AttachError::NotInSim)?;
attach_to(shared, domain, cfg)
}
fn wake(wakers: Vec<std::task::Waker>) {
if !wakers.is_empty() {
snare_interpose::real(|| wakers.into_iter().for_each(std::task::Waker::wake));
}
}
#[track_caller]
pub fn with_driver_time<R>(t: Duration, f: impl FnOnce() -> R) -> R {
assert_eq!(
snare_interpose::thread_class(),
Some(ThreadClass::Driver),
"with_driver_time runs on a driver thread of a sim (sched::mark_driver_thread)"
);
let shared = crate::scope::here();
let Some(sim_clock) = &shared.clock else {
panic!("this Sim runs on the real clock (SimBuilder::wall_clock) and has no sim time");
};
struct Restore(Option<clock::DriverTime>);
impl Drop for Restore {
fn drop(&mut self) {
clock::set_driver_time(self.0);
}
}
let _restore = Restore(clock::set_driver_time(Some(
sim_clock.driver_time_at(nanos(t)),
)));
f()
}
impl Executive {
fn at(&self, t: Duration) -> u64 {
nanos(t)
}
fn sim_time(&self, monotonic: Duration) -> Duration {
monotonic
}
fn name(&self, owner: Option<u64>) -> Arc<str> {
match owner {
Some(lineage) => self.domain.display_name(lineage),
None => snare_interpose::real(|| Arc::from("event")),
}
}
fn timer_blocker(&self, before: Option<u64>) -> Option<Arc<str>> {
let due = self.clock.due().or_else(|| {
let before = before?;
let next = self.clock.next_deadline_after(self.clock.peek())?;
(next < before).then(|| self.clock.owner_at(next))
})?;
Some(self.name(due))
}
pub fn now(&self) -> Duration {
self.clock.value()
}
pub fn config(&self) -> &ExecutiveConfig {
&self.cfg
}
pub fn grant(&self, g: Grant) {
let mut rate = if g.rate.is_nan() {
0.0
} else {
g.rate.clamp(0.0, clock::MAX_RATE)
};
if rate > 0.0 && self.clock.is_deterministic() {
if !self.warned_rate.swap(true, Ordering::Relaxed) {
eprintln!(
"snare: a deterministic Sim cannot let its clock flow with real time; the \
executive's grant at rate {rate} runs at rate 0"
);
}
rate = 0.0;
}
let anchor_real = nanos(snare_interpose::real(|| {
g.anchor_wall
.saturating_duration_since(crate::readiness::real_origin())
}));
let (before, after) = snare_interpose::real(|| {
let before = self.clock.peek();
self.clock
.grant(self.at(g.anchor_v), anchor_real, rate, self.at(g.horizon));
(before, self.clock.peek())
});
self.flow.changed(rate > 0.0, &self.clock, &self.shared);
self.release_passed(before, after);
}
fn release_passed(&self, before: u64, after: u64) -> u32 {
if after <= before && self.clock.due().is_none() {
return 0;
}
let (fired, wakers) = snare_interpose::real(|| self.clock.fire_upto(before, after));
wake(wakers);
self.shared.kick();
fired
}
pub fn freeze(&self) {
snare_interpose::real(|| self.clock.freeze());
self.flow.changed(false, &self.clock, &self.shared);
}
pub fn next_deadline(&self) -> Option<Duration> {
let next = snare_interpose::real(|| self.clock.next_deadline_after(self.clock.peek()))?;
Some(self.sim_time(Duration::from_nanos(next)))
}
pub fn jump_to(&self, t: Duration) -> Result<u32, NotQuiescent> {
let target = self.at(t);
let (fired, wakers) = readiness()
.locked(self.domain.key(), |settling| {
self.domain.if_quiescent(
settling,
|| self.timer_blocker(None),
false,
|| {
let (before, landing) = self.clock.jump_driven(target, true);
self.clock.fire_upto(before, landing)
},
)
})
.map_err(|_| NotQuiescent)?;
wake(wakers);
self.shared.kick();
Ok(fired)
}
pub fn enter_timestamp(&self, t: Duration) {
crate::sched::mark_driver_thread();
self.domain.begin_timestamp();
let target = self.at(t);
snare_interpose::real(|| {
self.clock.jump_driven(target.saturating_sub(1), false);
self.clock.set_stamp(Some(target));
});
clock::set_driver_time(Some(self.clock.driver_time_at(target)));
}
pub fn enter_timestamp_checked(&self, t: Duration) -> Result<(), NotQuiescent> {
crate::sched::mark_driver_thread();
let target = self.at(t);
readiness()
.locked(self.domain.key(), |settling| {
self.domain.if_quiescent(
settling,
|| self.timer_blocker(Some(target)),
true,
|| {
self.clock.jump_driven(target.saturating_sub(1), false);
self.clock.set_stamp(Some(target));
},
)
})
.map_err(|_| NotQuiescent)?;
clock::set_driver_time(Some(self.clock.driver_time_at(target)));
Ok(())
}
pub fn leave_timestamp(&self, t: Duration) -> u32 {
clock::set_driver_time(None);
let target = self.at(t);
let (fired, wakers, reached) = snare_interpose::real(|| {
let (before, _) = self.clock.jump_driven(target, false);
let (fired, wakers) = self.clock.fire_upto(before, target);
self.clock.set_stamp(None);
(fired, wakers, self.clock.wait_reached())
});
let woke = !wakers.is_empty();
wake(wakers);
if fired > 0 || woke || reached {
self.shared.kick();
} else {
self.domain.kick_due();
}
self.domain.end_timestamp();
fired
}
pub fn quiescence(&self) -> Quiescence {
let mut next = None;
let mut q = readiness().locked(self.domain.key(), |settling| {
self.domain.quiescence(settling, || {
next = self.next_deadline();
self.timer_blocker(None)
})
});
q.next_deadline = if q.quiescent {
next
} else {
self.next_deadline()
};
q
}
pub fn arm_notify(&self, seen_epoch: u64, f: Arc<dyn Fn() + Send + Sync>) {
self.domain.arm(seen_epoch, f);
}
pub fn participants(&self) -> Vec<ParticipantInfo> {
let mut rows = self.domain.participants();
for row in &mut rows {
row.deadline = row.deadline.map(|d| self.sim_time(d));
}
rows
}
pub fn timers(&self, n: usize) -> Vec<TimerInfo> {
let pending = snare_interpose::real(|| self.clock.pending_timers(n));
pending
.into_iter()
.map(|timer| TimerInfo {
deadline: self.sim_time(Duration::from_nanos(timer.at)),
owner: timer.owner.map(|lineage| self.domain.display_name(lineage)),
})
.collect()
}
pub fn drain_hints(&self) -> Vec<(Arc<str>, f32)> {
self.domain.take_hints()
}
pub fn held_leases(&self) -> Vec<crate::sched::LeaseInfo> {
self.domain.leases()
}
pub fn outside_wakes(&self) -> u64 {
self.domain.outside_wakes()
}
pub fn sim_id(&self) -> crate::sched::SimId {
self.domain.id()
}
pub fn thread_census(&self) -> Option<crate::sched::ThreadCensus> {
snare_interpose::census(Some(&self.domain))
}
pub fn audit(&self) -> AuditReport {
let mut report = self.domain.audit();
for effect in &mut report.class_effects {
effect.at = self.sim_time(effect.at);
}
for violation in &mut report.violations {
violation.at = self.sim_time(violation.at);
}
report
}
pub fn detach(self) {}
}
impl Drop for Executive {
fn drop(&mut self) {
self.flow.stop();
snare_interpose::real(|| self.clock.detach_driven());
self.domain.detach_executive();
self.shared.executive.store(false, Ordering::Release);
self.shared.kick();
}
}
impl fmt::Debug for Executive {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Executive")
.field("now", &self.now())
.field("cfg", &self.cfg)
.finish()
}
}