odem-rs-core 0.1.0

//! The `job` module supplies integrated threads of execution, known as
//! [`Job`], within the context of the simulation library.
//!
//! # Overview
//!
//! Jobs represent the combination of a [`Continuation`] and a [`Future`],
//! allowing them to share state with other related jobs of the same [`Agent`].
//! Unlike continuations, which only support simple *success*/*failure* return
//! values, jobs record their actual return value. This enables their creator
//! to retrieve it upon termination.
//!
//! Jobs may also be terminated prematurely, removing them from the simulation
//! calendar, releasing resources, and recording their result as a *failure* for
//! any interested parties.
//!
//! # Examples
//!
//! Creating and activating a simple job in a simulation context:
//!
//! ```
//! # use odem_rs_core::{simulator::Sim, job::Job};
//! # use core::pin::pin;
//! async fn sim_main(sim: &Sim) {
//!     // create and initialize a local variable
//!     let c = 3;
//!
//!     // create a job referring to it and the simulation context
//!     let fib = pin!(Job::new(async {
//!         for i in 0..c {
//!             println!("Hello {i}");
//!             sim.advance(1.0).await;
//!         }
//!     }));
//!
//!     // activate the job
//!     sim.activate(fib);
//!
//!     // pass time
//!     sim.advance((c + 1) as f64).await;
//! }
//! ```
//!
//! [`Agent`]: crate::agent::Agent

use core::{
	any::Any,
	cell::RefCell,
	fmt,
	future::{Future, IntoFuture, Pending},
	marker::PhantomData,
	mem::ManuallyDrop,
	panic::Location,
	pin::Pin,
	task::{Context, Poll},
};

use crate::{
	Active, Dispatch, ExitStatus,
	config::{Config, DefaultConfig},
	continuation::{Continuation, Label, Share, erased::State, token},
	error,
	fsm::*,
	ptr::{AsIrc, IntrusivelyCounted, Irc, IrcBox, Lease, LeasedMut},
	simulator::{Prec, Sim},
};

/* ******************************************************************** Job */

/// Light-weight thread of execution that shares state with other jobs
/// within the same [`Agent`].
///
/// Jobs are fundamentally ([`Continuation`], [`Future`]) pairs that can
/// reference shared state and each other, as long as that state outlives them.
/// Since continuations don't support return values other than a simple
/// *success*/*failure*, jobs erase their actual return value but record it,
/// allowing their parent to retrieve it upon their termination.
///
/// Jobs may also be terminated before completion, which will remove them from
/// the calendar, release all of their resources and record their result as
/// *failure* to any interested party.
///
/// # Examples
/// As stated, Jobs are light-weight and can easily refer to the variables
/// in their lexical scope.
/// ```
/// # use {odem_rs_core::{simulator::Sim, job::Job}, core::pin::pin};
/// async fn sim_main(sim: &Sim) {
///     // create and initialize a local variable
///     let c = 3;
///     
///     // create a job referring to it and the simulation context
///     let job = pin!(Job::new(async {
///         for i in 0..c {
///             println!("Hello {i}");
///             sim.advance(1.0).await;
///         }
///     }));
///     
///     // activate the job
///     sim.activate(job);
///     
///     // pass time
///     sim.advance((c + 1) as f64).await;
/// }
/// ```
///
/// [`Agent`]: crate::agent::Agent
#[pin_project::pin_project(PinnedDrop, !Unpin)]
pub struct Job<'brand, C: ?Sized + Config, F: Future, T = Unchecked> {
	/// A type-erased handle to the future contained within this job.
	#[pin]
	cont: Continuation<'brand, C>,
	/// The return-type-erased future instance representing the inner state
	/// of this job.
	#[pin]
	state: RefCell<Inner<F, T>>,
}

impl<C: ?Sized + Config, F: Future> Job<'static, C, F> {
	/// Creates a new job with a sequence of actions, expressed as a [`Future`].
	#[track_caller]
	pub fn new<'p, A>(actions: A) -> Lease<'p, Self>
	where
		A: IntoFuture<IntoFuture = F>,
	{
		Job::build().with_actions(actions).finish()
	}
}

impl Job<'static, DefaultConfig, Pending<()>> {
	/// Creates and returns a [Builder] for jobs, that is useful if complex
	/// initialization is required.
	pub const fn build() -> Builder {
		Builder::new()
	}
}

impl<C: ?Sized + Config, F: Future, T> Job<'static, C, F, T> {
	/// Used during startup of a simulation run to initialize the root job.
	pub(crate) fn boot<'p>(
		this: Pin<LeasedMut<'p, Self>>,
		share: Pin<&'p Share<C>>,
	) -> Puck<'p, C, F, T>
	where
		T: Settle<F::Output>,
	{
		// create a reference counted type
		let mut this = Irc::new(this);

		// set the most-specialized vptr for the continuation
		unsafe {
			let vptr = Irc::into_raw(this);
			this = Irc::from_raw(vptr);
			this.cont.set_vptr(vptr);
		}

		this.get_pin_mut().unwrap().brand(move |job, once| {
			let born = job.token(once).into_born().unwrap();

			// bind the shared agent data to it
			unsafe { job.bind(born, share.get_ref()) };
		});

		// initialize the pinned job reference
		Puck(this, PhantomData)
	}
}

impl<'brand, C: ?Sized + Config, F: Future, T> Job<'brand, C, F, T> {
	/// Sets the precedence of the job.
	pub fn set_prec(&self, prec: Prec) {
		self.cont.set_prec(prec);
	}

	/// Returns a copy of the job's [`State`].
	pub fn state(&self) -> State {
		self.cont.state().borrow().erased()
	}

	/// Extracts the return value if the job is terminated.
	pub fn result(&self) -> Result<F::Output, error::NotDone> {
		self.brand(|job, once| Ok(job.inner_result(job.token(once).into_done()?).1))
	}

	/// Aborts the execution of this job, removing it from the calendar,
	/// dropping the inner future and the return value if applicable.
	pub fn abort(&self) {
		self.brand(|job, once| {
			job.inner_abort(job.token(once));
		});
	}

	/// Converts the specific brand into a generic brand, breaking the
	/// connection with the equally branded token.
	pub fn detach(&self) -> &Job<'static, C, F, T> {
		// SAFETY: the branding has no impact regarding the object layout
		// and over-counting the number of token can not be source of unsafety.
		unsafe { core::mem::transmute(self) }
	}

	/// Returns an enumeration copy of the internal [State](token::State).
	pub fn token(&self, once: Ephemeral<'brand>) -> token::State<'brand> {
		self.cont.token(once)
	}

	/// Returns an exclusive reference to the finalizer if in state [`Born`].
	///
	/// [`Born`]: token::Born
	pub fn finalizer(self: Pin<&mut Self>, born: &token::Born<'brand>) -> Pin<&mut T> {
		let _ = born;

		// SAFETY: mutable access to the finalizer is unproblematic as long as
		// the job hasn't been activated.
		unsafe { self.map_unchecked_mut(move |job| &mut *job.state.get_mut().future.1) }
	}

	/// Aborts the execution of this job, removing it from the calendar,
	/// dropping the inner future and the return value if applicable.
	fn inner_abort(&self, state: token::State<'brand>) -> token::Gone<'brand> {
		use token::State::*;

		// drop impls should not be able to perform further continuation transitions
		// but we better check to be sure
		let task = &self.cont;

		// set the correct span
		let _span = task.enter_span();

		// analyze the state
		let once: Ephemeral<'_> = match state {
			// the future has already been dropped -> quit
			Gone(gone) => return gone,
			// the return value is pending -> drop it and quit
			Done(done) => return self.inner_result(done).0,
			// the job is scheduled -> remove it from the calendar
			Next(next) => task.deschedule(next).into(),
			// the job is active -> remove it from the active slot
			Busy(busy) => task.deactivate(busy).into(),
			// the job is born or idle -> drop the future and transition
			state @ (Born(_) | Idle(_)) => state.into(),
		};

		// drop the future before performing extra transitions to prevent
		// undefined behavior in user-defined drop impls that rely on the
		// current continuation state
		let (once, ()) = self.debrand(once, |job| unsafe {
			job.state.borrow_mut().unchecked_drop();
		});

		// perform the final transition into the `Gone`-state
		let gone = match task.token(once) {
			Born(born) => task.state().transition(born, Err(crate::Failure)),
			Idle(idle) => task.state().transition(idle, Err(crate::Failure)),
			state => unreachable!(
				"expected task to be 'Born' or 'Idle' but it is \
				 in state '{:?}' instead",
				state.erased()
			),
		};

		// now reactivate pending continuations
		task.wake_pending();

		// return the corresponding token to the caller
		gone
	}

	/// Extracts the return value of a terminated job.
	fn inner_result(&self, done: token::Done<'brand>) -> (token::Gone<'brand>, F::Output) {
		let task = &self.cont;
		let rc = task.branded_result(&done);

		// set the correct span
		let _span = task.enter_span();

		// SAFETY: we know that the result has been written and not been read
		// in state 'Done'
		unsafe {
			(
				task.state().transition(done, rc),
				self.state
					.borrow_mut()
					.unchecked_result()
					.unwrap_unchecked(),
			)
		}
	}

	/// Binds shared data to an unbound job.
	///
	/// # Safety
	/// The caller has to ensure that the shared-data-reference outlives the
	/// (active) part of the continuations' life.
	pub(crate) unsafe fn bind(
		self: Pin<&mut Self>,
		born: token::Born<'brand>,
		share: &Share<C>,
	) -> token::Idle<'brand> {
		unsafe { self.project().cont.bind(born, share) }
	}
}

impl<'b, C: ?Sized + Config, F: Future, T> Stateful for Job<'b, C, F, T> {
	type Brand = &'b ();

	unsafe fn enter(&self) {
		unsafe {
			self.cont.enter();
		}
	}

	unsafe fn leave(&self) {
		unsafe {
			self.cont.leave();
		}
	}
}

impl<'b, C: ?Sized + Config, F: Future, T> Rebrand<'b> for Job<'b, C, F, T> {
	type Kind<'a> = Job<'a, C, F, T>;
}

impl<C: ?Sized + Config, F: Future, T> fmt::Debug for Job<'_, C, F, T> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		let mut s = f.debug_struct("Job");
		s.field("continuation", &self.cont)
			.field("future", &core::any::type_name::<F>())
			.finish()
	}
}

impl<C: ?Sized + Config, F: Future, T: Settle<F::Output>> Dispatch for Job<'_, C, F, T> {
	fn poll(self: Pin<&Self>, cx: &mut Context<'_>) -> Poll<ExitStatus> {
		assert!(
			self.state().is_busy(),
			"only active continuations can be polled"
		);

		let mut state = self.state.borrow_mut();

		// SAFETY: self is pinned and access to future is defined in state Busy
		unsafe { Pin::new_unchecked(&mut *state.future.0) }
			.poll(cx)
			.map(move |rv| {
				// SAFETY: the future just terminated
				unsafe { state.unchecked_terminate(rv) }
			})
	}
}

impl<C: ?Sized + Config, F: Future, T: Settle<F::Output>> Active<C> for Job<'static, C, F, T> {
	type Output = F::Output;
	type Puck<'p>
		= Puck<'p, C, F, T>
	where
		Self: 'p;

	fn bind<'p>(this: Pin<LeasedMut<'p, Self>>, sctx: &'p Share<C>) -> Self::Puck<'p> {
		let mut irc = Irc::new(this);

		irc.get_pin_mut().unwrap().brand(move |mut job, once| {
			let born = job.token(once).into_born().unwrap();

			// SAFETY: the shared data of the root-job outlives the
			// newly bound job, because jobs have to terminate
			// before their agent does, which is enforced by the
			// borrow-checker
			unsafe {
				job.as_mut().bind(born, sctx);
			}
		});

		Puck(irc, PhantomData)
	}
}

// SAFETY: the `IrcBox`-method points to an inner `IrcBox`.
unsafe impl<'brand, C, F, T> IntrusivelyCounted for Job<'brand, C, F, T>
where
	C: ?Sized + Config,
	F: Future,
{
	type Inner = <Continuation<'brand, C> as IntrusivelyCounted>::Inner;

	fn irc_box(&self) -> &IrcBox<Self::Inner> {
		self.cont.irc_box()
	}
}

impl<'brand, C, F, T> AsRef<Continuation<'brand, C>> for Job<'brand, C, F, T>
where
	C: ?Sized + Config,
	F: Future,
{
	fn as_ref(&self) -> &Continuation<'brand, C> {
		&self.cont
	}
}

#[pin_project::pinned_drop]
impl<C: ?Sized + Config, F: Future, T> PinnedDrop for Job<'_, C, F, T> {
	fn drop(self: Pin<&mut Self>) {
		// prevent `reclaim` from being called, even if the reference counter
		// drops to zero due to `abort`; creating the mutable reference would be
		// undefined behavior, even if it isn't used
		self.cont.clear_vptr();

		// abort the execution without running reclaim
		self.abort();
	}
}

/* ********************************************************************* Puck */

/// An exclusive reference to a pinned [`Job`].
///
/// The underlying [`Continuation`] does not expire at the end of its scope but
/// is continued until it either terminates normally or its destructor is
/// executed. This is safe because pinning guarantees that the job will not be
/// moved before it is dropped.
pub struct Puck<'p, C: ?Sized + Config, F: Future, T = Unchecked>(
	Irc<Job<'static, C, F, T>>,
	PhantomDrop<Pin<&'p mut Job<'static, C, F, T>>>,
);

impl<C: ?Sized + Config, F: Future, T> Puck<'_, C, F, T> {
	/// Returns a reference to the [shared context](Share) bound to this job.
	pub fn share(&self) -> &Share<C> {
		// SAFETY: Pucks can only be created during initialization, after
		// which they have shared data bound to them
		unsafe { self.0.cont.share().unwrap_unchecked() }
	}

	/// Terminates the referenced job prematurely.
	///
	/// This method consumes the reference to prevent it from being called twice
	/// or used to extract the return value later.
	pub fn abort(self) {
		self.0.abort();
	}
}

impl<C, F, T> fmt::Debug for Puck<'_, C, F, T>
where
	C: ?Sized + Config,
	F: Future,
	T: Settle<F::Output>,
{
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		self.0.fmt(f)
	}
}

impl<C, F, T> crate::Puck<C> for Puck<'_, C, F, T>
where
	C: ?Sized + Config,
	F: Future,
	T: Settle<F::Output>,
{
	fn result(&mut self) -> Option<Self::Output> {
		self.0.result().ok()
	}

	fn wake(&mut self) -> Result<(), error::NotIdle> {
		Continuation::wake(Irc::map(self.0.clone(), |inner| &inner.cont))
	}

	fn subject(&self) -> &dyn Any {
		self.share().item()
	}

	fn sim(&self) -> &Sim<C> {
		self.share().sim()
	}

	fn label(&self) -> Label {
		self.share().label()
	}

	fn time(&self) -> Option<C::Time> {
		self.0.cont.time()
	}

	fn rank(&self) -> C::Rank {
		self.share().rank()
	}
	
	fn prec(&self) -> Prec {
		self.0.cont.prec()
	}

	fn state(&self) -> State {
		self.0.cont.state().borrow().erased()
	}

	fn location(&self) -> &'static Location<'static> {
		self.0.cont.location()
	}
}

impl<C, F, T> From<Puck<'_, C, F, T>> for Irc<Job<'static, C, F, T>>
where
	C: ?Sized + Config,
	F: Future,
	T: Settle<F::Output>,
{
	fn from(value: Puck<'_, C, F, T>) -> Self {
		value.0
	}
}

impl<C, F, T> AsRef<Continuation<'static, C>> for Puck<'_, C, F, T>
where
	C: ?Sized + Config,
	F: Future,
	T: Settle<F::Output>,
{
	fn as_ref(&self) -> &Continuation<'static, C> {
		&self.0.cont
	}
}

impl<C, F, T> AsIrc<Continuation<'static, C>> for Puck<'_, C, F, T>
where
	C: ?Sized + Config,
	F: Future,
	T: Settle<F::Output>,
{
	fn as_irc(&self) -> Irc<Continuation<'static, C>> {
		Irc::map(self.0.clone(), |inner| &inner.cont)
	}
}

impl<C, F, T> IntoFuture for Puck<'_, C, F, T>
where
	C: ?Sized + Config,
	F: Future,
	T: Settle<F::Output>,
{
	type Output = F::Output;
	type IntoFuture = crate::ops::Join<C, Self>;

	#[inline]
	fn into_future(self) -> Self::IntoFuture {
		crate::ops::join(self)
	}
}

/* **************************************** Return-Type-Erased Future Adapter */

/// Internal helper type erasing the return type of future.
///
/// This generic type is used to implement the [`Future`] trait with an
/// [`Output`](Future::Output) of `Result<(),()>` but allows extraction of the
/// result using its methods.
///
/// The type is implemented as a union to save space, because either the future
/// is still pending (and there is no result yet) or it is ready (and it doesn't
/// need a future anymore).
union Inner<F: Future, T> {
	/// A future and finalization routine.
	///
	/// The future still contains a user-defined return type but the [`Settle`]
	/// routine knows how to convert it into a result of type [`ExitStatus`].
	/// The pair is used to erase the return-type of the future.
	future: (ManuallyDrop<F>, ManuallyDrop<T>),
	/// The result of the future stored after its termination.
	result: ManuallyDrop<Option<F::Output>>,
}

impl<F: Future, T> Inner<F, T> {
	/// Initializes a new return-type-erased instance from a future returning
	/// a `Result`.
	#[inline]
	const fn new(actions: F, settle: T) -> Self {
		Inner {
			future: (ManuallyDrop::new(actions), ManuallyDrop::new(settle)),
		}
	}

	/// Unconditionally (and unsafely) drops the inner future.
	///
	/// # Safety
	/// The caller is responsible for calling this method not more than once
	/// and only if the future hasn't terminated.
	#[inline]
	unsafe fn unchecked_drop(&mut self) {
		unsafe {
			ManuallyDrop::drop(&mut self.future.0);
			ManuallyDrop::drop(&mut self.future.1);
		}
	}

	/// Unconditionally (and unsafely) returns the result of the inner future.
	///
	/// # Safety
	/// The caller is responsible for calling this method only after the future
	/// has terminated, but it is allowed to be called multiple times.
	#[inline]
	unsafe fn unchecked_result(&mut self) -> Option<F::Output> {
		unsafe { self.result.take() }
	}

	/// Unconditionally (and unsafely) drops the inner future and writes out
	/// the result.
	///
	/// # Safety
	/// The caller is responsible for only calling this method once at the end
	/// of the future's life.
	#[inline]
	unsafe fn unchecked_terminate(&mut self, result: F::Output) -> ExitStatus
	where
		T: Settle<F::Output>,
	{
		unsafe {
			// prepare a drop guard to ensure that the result is written back even
			// in case of a panic by `settle` or `drop`
			let mut guard = scopeguard::guard((self, result), |(this, result)| {
				this.result = ManuallyDrop::new(Some(result));
			});

			// move the finalizer out of the state before calling any functions
			// that may panic in order to prevent resource leaks
			let term = ManuallyDrop::take(&mut guard.0.future.1);

			// carefully drop the pinned future without moving it
			ManuallyDrop::drop(&mut guard.0.future.0);

			// call the finalizer
			term.settle(&mut guard.1)
		}
	}
}

/* ************************************************ Canonical Future Adapters */

/// A trait for converting the result of a [Job] into an [ExitStatus].
///
/// The trait has a blanket implementation for [`FnOnce`]-closures but can
/// also be further specialized for user-defined types if needed.
pub trait Settle<R> {
	/// Method hook that is called once a job completes with a return value.
	/// The return value of this method indicates whether the result is counted
	/// as success (`Ok`) or failure (`Err`).
	fn settle(self, result: &mut R) -> ExitStatus;
}

// blanket implementation for closures
impl<R, F> Settle<R> for F
where
	F: FnOnce(&mut R) -> ExitStatus,
{
	fn settle(self, result: &mut R) -> ExitStatus {
		self(result)
	}
}

/// Finalization adapter that converts `Poll::Ready` values into the `Ok`
/// variant of a `Result<Success,Failure>`.
pub struct Unchecked;

impl<R> Settle<R> for Unchecked {
	fn settle(self, _result: &mut R) -> ExitStatus {
		Ok(crate::Success)
	}
}

/// Finalization adapter that converts `Poll::Ready` values into an
/// [`ExitStatus`] for `bool`, [`Option`], and [`Result`], using the
/// `Ok`-variant for `true`, `Some`, and `Ok` respectively, and the `Err`
/// variant otherwise.
pub struct Checked;

impl Settle<bool> for Checked {
	fn settle(self, result: &mut bool) -> ExitStatus {
		if *result {
			Ok(crate::Success)
		} else {
			Err(crate::Failure)
		}
	}
}

impl<R, T> Settle<Result<R, T>> for Checked {
	fn settle(self, result: &mut Result<R, T>) -> ExitStatus {
		if result.is_ok() {
			Ok(crate::Success)
		} else {
			Err(crate::Failure)
		}
	}
}

impl<T> Settle<Option<T>> for Checked {
	fn settle(self, result: &mut Option<T>) -> ExitStatus {
		if result.is_some() {
			Ok(crate::Success)
		} else {
			Err(crate::Failure)
		}
	}
}

/* ************************************************************ Job Builder */

/// Builder-type providing support to configuring jobs in more detail.
///
/// # Examples
/// ```
/// # use {odem_rs_core::{simulator::{Sim, Prec}, job::Job}, core::pin::pin};
/// # async fn sim_main(sim: &Sim) {
///     # let job =
/// Job::build()                       // create builder
///     .with_actions(async { true })  // specify lifecycle
///     .with_precedence(Prec::new())  // initialize precedence
///     .checked()                     // store result as exit code
///     .finish()                      // instantiate job
///     # ;
///     # sim.activate(pin!(job));
/// # }
/// ```
pub struct Builder<const R: bool = false, F = (), S = Unchecked> {
	future: F,
	location: Option<&'static Location<'static>>,
	finalizer: S,
	precedence: Prec,
}

impl Builder {
	/// Constructs a new (default) Builder.
	pub const fn new() -> Self {
		Builder {
			future: (),
			location: None,
			finalizer: Unchecked,
			precedence: Prec::new(),
		}
	}

	/// Constructs a new (default) Builder
	pub const fn root() -> Builder<true> {
		Builder {
			future: (),
			location: None,
			finalizer: Unchecked,
			precedence: Prec::new(),
		}
	}
}

impl<const R: bool, S> Builder<R, (), S> {
	/// Sets a future for the lifecycle of the [`Job`].
	///
	/// This method also sets the source code [`Location`] if it isn't set
	/// explicitly through [`with_location`].
	///
	/// [`with_location`]: Builder::with_location
	#[track_caller]
	pub fn with_actions<F: IntoFuture>(self, future: F) -> Builder<R, F, S> {
		let Builder {
			location,
			finalizer,
			precedence,
			..
		} = self;

		Builder {
			future,
			location: Some(location.unwrap_or(Location::caller())),
			finalizer,
			precedence,
		}
	}
}

impl<const R: bool, F> Builder<R, F> {
	/// Sets a user-defined [`Settle`] that is run once the lifecycle of the
	/// [`Job`] terminates.
	pub fn with_finalizer<S>(self, finalizer: S) -> Builder<R, F, S> {
		let Builder {
			future,
			location,
			precedence,
			..
		} = self;

		Builder {
			future,
			location,
			finalizer,
			precedence,
		}
	}

	/// Sets a specific [`Settle`] routine that is used to convert a `bool`,
	/// [`Option`], or [`Result`] return type into an [`ExitStatus`] that may
	/// be observed by other agents or jobs.
	pub fn checked(self) -> Builder<R, F, Checked> {
		self.with_finalizer(Checked)
	}
}

impl<const R: bool, F, S> Builder<R, F, S> {
	/// Sets the [Precedence](Prec) of the [`Job`].
	pub const fn with_precedence(mut self, precedence: Prec) -> Self {
		self.precedence = precedence;
		self
	}

	/// Sets an explicit source-code [`Location`] for the [`Job`].
	///
	/// Not setting the location will use the location during [`with_actions`].
	///
	/// [`with_actions`]: Builder::with_actions
	pub const fn with_location(mut self, location: &'static Location<'static>) -> Self {
		self.location = Some(location);
		self
	}
}

impl<const R: bool, F: IntoFuture, S: Settle<F::Output>> Builder<R, F, S> {
	/// Finalizes the construction of the [`Job`] and returns it.
	pub fn finish<'p, C>(self) -> Lease<'p, Job<'static, C, F::IntoFuture, S>>
	where
		C: ?Sized + Config,
	{
		let location = self.location.unwrap();

		// create a new span if it's not a root fiber
		#[cfg(feature = "tracing")]
		let _span = if R {
			tracing::Span::current()
		} else {
			tracing::error_span!("Job", line = location.line()).or_current()
		}
		.entered();

		Lease::new(Job {
			cont: Continuation::new(self.precedence, location),
			state: RefCell::new(Inner::new(self.future.into_future(), self.finalizer)),
		})
	}
}

impl Default for Builder {
	fn default() -> Self {
		Self::new()
	}
}

/* ******************************************************* PhantomDrop helper */

/// This type-alias combines [`PhantomData`] with a Drop-check, ensuring that
/// even phantom types that don't implement the Drop traits themselves present
/// like they would. This is necessary to prevent code like in the following
/// example to compile which would lead to a runtime error due to increased
/// reference counts during drop.
///
/// ```compile_fail,E0716
/// # use odem_rs_core::{simulator::Sim, job::Job};
/// # use core::pin::pin;
///
/// async fn sim_main(sim: &Sim) {
///     let puck = sim.activate(pin!(Job::new(async {})));
/// }
/// ```
type PhantomDrop<T> = PhantomData<PhantomDropInner<T>>;

/// Newtype wrapping a `T` and explicitly implementing the [Drop]-trait.
struct PhantomDropInner<T: ?Sized>(T);

impl<T: ?Sized> Drop for PhantomDropInner<T> {
	fn drop(&mut self) {}
}