odem-rs-core 0.1.0

//! Provides type-erased and object-safe traits that can be used to dynamically
//! dispatch over [`Simulators`], regardless of their [configuration].
//!
//! [`Simulators`]: crate::simulator::Simulator
//! [configuration]: Config

pub use crate::continuation::erased::State;

use core::{any::Any, fmt, marker::PhantomData, ptr::NonNull, task::RawWaker};

use crate::{
	config::Config,
	continuation,
	ptr::{IntrusivelyCounted, Irc},
	simulator::{Prec, SimBox},
};

/// Type-erased trait for [Simulation contexts](crate::simulator::Sim).
pub trait Sim: Any + IntrusivelyCounted<Inner = SimBox> {
	/// Returns the currently active and config-erased version of a [`Puck`].
	///
	/// [`Puck`]: crate::Puck
	fn active(&self) -> Option<ContPuck>;

	/// Returns the current time as a displayable object.
	fn now(&self) -> &dyn fmt::Display;

	/// Returns the global (shared) data of the simulator.
	fn global(&self) -> &dyn Any;

	/// Constructs a [`RawWaker`] for the currently active process.
	fn waker(&self) -> RawWaker;

	/// Defers the currently active process.
	fn defer(&self);
}

/// Type-erased trait for [continuations](continuation::Continuation).
pub trait Continuation:
	Any + IntrusivelyCounted<Inner = continuation::ContBox> + fmt::Debug
{
	/// Returns a type-erased reference to the shared agent data.
	fn subject(&self) -> &dyn Any;

	/// Returns the continuation's [`Label`](continuation::Label).
	fn label(&self) -> continuation::Label;

	/// Returns the continuation's [precedence](Prec).
	fn prec(&self) -> Prec;

	/// Returns the continuation's [`State`].
	fn state(&self) -> State;
}

/// [`Config`]-erased type for [pucks](continuation::Puck).
#[derive(Clone)]
pub struct ContPuck(Irc<dyn Continuation>);

impl ContPuck {
	/// Converts a [`Config`]-erased [`ContPuck`] into a `Config`-dependent
	/// [Puck](continuation::Puck) or returns the original object if the
	/// configuration didn't agree with the actual type.
	pub fn downcast<C: Config>(self) -> Result<continuation::Puck<C>, Self> {
		match self.0.downcast::<continuation::Continuation<'static, C>>() {
			Ok(task) => Ok(continuation::Puck::checked(task).unwrap()),
			Err(old) => Err(ContPuck(old)),
		}
	}

	/// Returns a reference to the instance shared among all the [jobs]
	/// associated with the same agent as this one.
	///
	/// [jobs]: crate::job::Job
	pub fn shared(&self) -> &dyn Any {
		self.0.subject()
	}

	/// Returns the name of the underlying [`Agent`](crate::agent::Agent).
	pub fn label(&self) -> continuation::Label {
		self.0.label()
	}

	/// Returns the current [precedence] of the underlying [Job].
	///
	/// [precedence]: Prec
	/// [Job]: crate::job::Job
	pub fn prec(&self) -> Prec {
		self.0.prec()
	}

	/// Returns a copy of this continuation's [`State`].
	pub fn state(&self) -> State {
		self.0.state()
	}
}

impl<C: Config> From<continuation::Puck<C>> for ContPuck {
	fn from(task: continuation::Puck<C>) -> Self {
		let coerced = Irc::into_raw(task.into_inner()) as NonNull<dyn Continuation>;
		ContPuck(unsafe { Irc::from_raw(coerced) })
	}
}

impl fmt::Debug for ContPuck {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		self.0.fmt(f)
	}
}

/// Currently active thread-local and type-erased [simulation context].
///
/// [simulation context]: Sim
use shared::SIMULATOR;

/// Sets the passed [simulation context](crate::simulator::Sim)-reference as the
/// new active simulator, returning a [Guard] that resets the active simulator
/// on drop.
#[must_use = "dropping this guard restores the previous thread-local simulator"]
pub(crate) fn hook(sim: Irc<impl Sim>) -> impl Drop {
	Guard::new(sim)
}

/// Executes a closure receiving a type-erased [simulation context].
/// Returns `None` if no simulator is currently active.
///
/// [simulation context]: crate::simulator::Sim
pub fn with<R>(f: impl FnOnce(&dyn Sim) -> R) -> Option<R> {
	SIMULATOR.with(|inner| {
		let sim = inner.take()?;
		let res = f(&*sim);
		inner.set(Some(sim));
		Some(res)
	})
}

/// Returns a [`ContPuck`] for the currently active continuation, if this thread
/// is currently running a simulation.
pub fn active() -> Option<ContPuck> {
	SIMULATOR.with(|inner| {
		let sim = inner.take()?;
		let res = sim.active();
		inner.set(Some(sim));
		res
	})
}

/// Guards the currently active [`Simulator`] in this thread, restoring the
/// previous state when this guard is dropped.
///
/// Guard-instances form an implicit chain over the stack, allowing nested
/// simulation runs within the same thread.
///
/// [`Simulator`]: crate::simulator::Simulator
struct Guard {
	/// The previous type-erased simulator.
	prev: Option<Irc<dyn Sim>>,
}

impl Guard {
	/// Creates a new Guard, pushing it on top of the implicit simulator-stack.
	fn new(sim: Irc<impl Sim>) -> Self {
		Guard {
			prev: SIMULATOR.replace(Some(Irc::map(sim, |inner| -> &dyn Sim { inner }))),
		}
	}
}

impl Drop for Guard {
	fn drop(&mut self) {
		SIMULATOR.replace(self.prev.take());
	}
}

/* *************************************************************** Model Time */

/// Helper that allows displaying the model time of the currently active
/// simulator in human-readable format.
pub struct ModelTime<W>(pub W)
where
	W: Fn(&mut dyn fmt::Write, &dyn Sim) -> fmt::Result;

impl<W> fmt::Display for ModelTime<W>
where
	W: Fn(&mut dyn fmt::Write, &dyn Sim) -> fmt::Result,
{
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		with(move |sim| self.0(f, sim)).unwrap_or(Ok(()))
	}
}

/// Constructs a constant [`ModelTime`] instance that may be used to return the
/// model time of the currently active simulator for this thread.
///
/// The macro accepts a format string and optional, additional arguments as
/// specified for the [format_args]-macro. The format string may reference the
/// `time`-variable.
///
/// This is really meant in combination with the `tracing`-crate, but it is
/// possible to be used independently through the [`Display`]-trait.
///
/// # Example
/// ```
/// # use odem_rs_core::{simulator::{Sim, simulation}, model_time};
/// # async fn sim_main(sim: &Sim) {}
/// fn main() {
///     tracing_subscriber::fmt()
///         .with_timer(model_time!("[{time:#}]"))
///         .init();
///
///     simulation(sim_main).unwrap();
///}
/// ```
///
/// [`Display`]: fmt::Display
#[macro_export]
macro_rules! model_time {
	() => { $crate::model_time!("[{time}]") };

	($($arg:tt)*) => {
		$crate::erased::ModelTime(
			move |w,s| ::core::fmt::write(w, ::core::format_args!($($arg)*, time = s.now()))
		)
	};
}

// make ModelTime compatible to the FormatTime-trait from tracing-subscriber
#[cfg(feature = "tracing")]
impl<W> tracing_subscriber::fmt::time::FormatTime for ModelTime<W>
where
	W: Fn(&mut dyn fmt::Write, &dyn Sim) -> fmt::Result,
{
	fn format_time(&self, w: &mut tracing_subscriber::fmt::format::Writer<'_>) -> fmt::Result {
		with(move |sim| self.0(w, sim)).unwrap_or(Ok(()))
	}
}

/* **************************************************** Normalized Model Time */

/// Helper for displaying normalized model-time in digital-clock-format.
#[derive(Copy, Clone)]
pub struct ClockTime<U> {
	/// The value-part of the time.
	value: isize,
	/// Indicator of the unit of time.
	_unit: PhantomData<U>,
}

impl ClockTime<()> {
	/// Constructs a [displayable](fmt::Display) clock time in seconds.
	pub const fn seconds(value: isize) -> impl fmt::Display {
		ClockTime::<Seconds> {
			value,
			_unit: PhantomData,
		}
	}

	/// Constructs a [displayable](fmt::Display) clock time in minutes.
	pub const fn minutes(value: isize) -> impl fmt::Display {
		ClockTime::<Minutes> {
			value,
			_unit: PhantomData,
		}
	}

	/// Constructs a [displayable](fmt::Display) clock time in hours.
	pub const fn hours(value: isize) -> impl fmt::Display {
		ClockTime::<Hours> {
			value,
			_unit: PhantomData,
		}
	}

	/// Constructs a [displayable](fmt::Display) clock time in days.
	pub const fn days(value: isize) -> impl fmt::Display {
		ClockTime::<Days> {
			value,
			_unit: PhantomData,
		}
	}

	/// Constructs a [displayable](fmt::Display) clock time in weeks.
	pub const fn years(value: isize) -> impl fmt::Display {
		ClockTime::<Years> {
			value,
			_unit: PhantomData,
		}
	}
}

impl<U> ClockTime<U> {
	/// Private method that prints the time's sign.
	fn write_sign(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		if self.value < 0 {
			write!(f, "-")
		} else if f.sign_plus() {
			write!(f, "+")
		} else {
			Ok(())
		}
	}
}

impl fmt::Display for ClockTime<Years> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		self.write_sign(f)?;
		Years(self.value.unsigned_abs()).fmt(f)
	}
}

impl fmt::Display for ClockTime<Days> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		self.write_sign(f)?;
		Days(self.value.unsigned_abs()).fmt(f)
	}
}

impl fmt::Display for ClockTime<Hours> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		self.write_sign(f)?;
		Hours(self.value.unsigned_abs()).fmt(f)
	}
}

impl fmt::Display for ClockTime<Minutes> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		self.write_sign(f)?;
		Minutes(self.value.unsigned_abs()).fmt(f)
	}
}

impl fmt::Display for ClockTime<Seconds> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		self.write_sign(f)?;
		Seconds(self.value.unsigned_abs()).fmt(f)
	}
}

/// Marks the inner quantity as 'in seconds'.
struct Seconds(usize);
/// Marks the inner quantity as 'in minutes'.
struct Minutes(usize);
/// Marks the inner quantity as 'in hours'.
struct Hours(usize);
/// Marks the inner quantity as 'in days'.
struct Days(usize);
/// Marks the inner quantity as 'in years'.
struct Years(usize);

impl fmt::Display for Years {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		self.0.fmt(f).and_then(|_| f.write_str("a"))
	}
}

impl fmt::Display for Days {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		let mut quantity = self.0;

		if quantity >= 365 || f.precision().map(|w| w > 4).unwrap_or(false) {
			Years(quantity / 365).fmt(f)?;
			quantity %= 365;
			f.write_str(" ")?;
		}

		write!(f, "{quantity}d")
	}
}

impl fmt::Display for Hours {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		let mut quantity = self.0;

		if quantity >= 24 || f.precision().map(|w| w > 3).unwrap_or(false) {
			Days(quantity / 24).fmt(f)?;
			quantity %= 24;
			f.write_str(" ")?;
		}

		write!(f, "{quantity:02}h")
	}
}

impl fmt::Display for Minutes {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		let mut quantity = self.0;

		if quantity >= 60 || f.precision().map(|w| w > 2).unwrap_or(false) {
			Hours(quantity / 60).fmt(f)?;
			quantity %= 60;
			f.write_str(" ")?;
		}

		write!(f, "{quantity:02}m")
	}
}

impl fmt::Display for Seconds {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		let mut quantity = self.0;

		if quantity >= 60 || f.precision().map(|w| w > 1).unwrap_or(false) {
			Minutes(quantity / 60).fmt(f)?;
			quantity %= 60;
			f.write_str(" ")?;
		}

		write!(f, "{quantity:02}s")
	}
}

/* ****************************************** Shared Simulator Helper Modules */

#[cfg(feature = "std")]
mod shared {
	use super::{Irc, Sim};
	use std::cell::Cell;

	thread_local! {
		pub static SIMULATOR: Cell<Option<Irc<dyn Sim>>> = const { Cell::new(None) };
	}
}

#[cfg(not(feature = "std"))]
mod shared {
	use super::{Irc, Sim};
	use core::{
		cell::Cell,
		sync::atomic::{AtomicBool, Ordering},
	};

	pub static SIMULATOR: LocalKey = LocalKey::new();

	pub struct LocalKey {
		sim: Cell<Option<Irc<dyn Sim>>>,
		lock: AtomicBool,
	}

	impl LocalKey {
		const fn new() -> Self {
			Self {
				sim: Cell::new(None),
				lock: AtomicBool::new(true),
			}
		}

		pub fn with<R>(&self, f: impl FnOnce(&Cell<Option<Irc<dyn Sim>>>) -> R) -> R {
			assert!(
				self.lock.swap(false, Ordering::SeqCst),
				"detected multiple threads running simulators"
			);

			let res = f(&self.sim);

			self.lock.store(true, Ordering::SeqCst);
			res
		}

		pub fn replace(&self, sim: Option<Irc<dyn Sim>>) -> Option<Irc<dyn Sim>> {
			assert!(
				self.lock.swap(false, Ordering::SeqCst),
				"detected multiple threads running simulators"
			);

			let res = self.sim.replace(sim);

			self.lock.store(true, Ordering::SeqCst);
			res
		}
	}

	unsafe impl Sync for LocalKey {}
}