Struct Sim

Source

pub struct Sim<C: ?Sized + Config = ()> { /* private fields */ }

Expand description

Simulation context that can be used to advance the model-time, spawn additional Processes or Jobs, access global data, the current model-time and the active process, among other things.

It can only be accessed during a simulation run.

Implementations§

Source §

impl<C: Config> Sim<C>

Source

pub fn from_context(context: &Context<'_>) -> Option<Irc<Self>>

Gets a simulation context from a waker.

This can be used to recover the current simulation context from the context argument if the configuration is known, making it possible to distribute the simulation context by piggybacking on Rust’s implicit Context.

Source §

impl<C: ?Sized + Config> Sim<C>

Source

pub fn config(&self) -> &C

Returns a shared reference to the configuration.

Source

pub fn global(&self) -> &C::Data

Returns a reference to the shared data.

Source

pub fn active(&self) -> ContPuck<C>

Returns the Puck of the currently active continuation.

Source

pub fn update_rank(&self, rank: C::Rank)

Changes the rank of the currently active Agent.

The new rank takes immediate effect and causes the rearrangement of all jobs currently scheduled for the active agent, both in the present and future.

Lowering the rank of the active Agent can lead to another Agent gaining control if one with a (now) higher rank has jobs scheduled at the current model time. This change takes effect once the currently active agent suspends.

Source

pub fn now(&self) -> C::Time

Returns the current model time.

Source

pub fn advance(&self, dt: impl Into<C::Time>) -> impl Future<Output = ()> + '_
where C::Time: Add<Output = C::Time>,

Schedules the currently active continuation at a later model time.

Panics if no continuation is currently active or if the proposed model time has already passed. For a non-panicking version of this method, see try_advance.

Source

pub fn advance_to( &self, time: impl Into<C::Time>, ) -> impl Future<Output = ()> + '_

Schedules the currently active continuation at a later model time.

This method has the same function as advance but takes an absolute time-point for the proposed reactivation time rather than a relative one.

For a non-panicking alternative, see try_advance_to.

Source

pub fn try_advance( &self, dt: impl Into<C::Time>, ) -> impl Future<Output = Result<(), CausalityError<C::Time>>> + '_
where C::Time: Add<Output = C::Time>,

Attempts to advance the currently active continuation to a later model time.

Fails with an Err-result if either no continuation is active or if the proposed model time has already passed.

Source

pub fn try_advance_to( &self, time: impl Into<C::Time>, ) -> impl Future<Output = Result<(), CausalityError<C::Time>>> + '_

Attempts to advance the currently active continuation to a later model time.

This method has the same function as try_advance but takes an absolute time-point for the proposed reactivation time rather than a relative one.

Source

pub fn activate<'a, A>(&'a self, actions: Pin<LeasedMut<'a, A>>) -> A::Puck<'a>
where A: Active<C>,

Activates a new continuation by binding it to the simulation context, scheduling it at the current model time, and returning a Puck to it.

§Example Usage

You will usually want to pin the active object to pass it into the function like this:

let job = pin!(Job::new(async { /* do important work */ }));
let puck = sim.activate(job);

§Note

The function expects a pinned mutable reference to a Lease to an active object to utilize the borrow-checker to prevent certain usage errors statically. Without going into too much technical detail, the argument is made into the equivalent of a reference with move semantics. Once this function has been called, it is as if the value has been moved into the function, preventing access to it from the caller’s context, even though only a reference has been moved.

Specifically, the following error is prevented:

let mut job = pin!(Job::new(async { /* do important work */ }));
sim.activate(job.as_mut()); // allowed
// later
sim.activate(job);          // error: cannot move out of `job` because it is borrowed

Please refer to the documentation of Lease for technical details.

Source

pub fn schedule<'a, A>( &'a self, actions: Pin<LeasedMut<'a, A>>, dt: impl Into<C::Time>, ) -> A::Puck<'a>
where A: Active<C>, C::Time: Add<Output = C::Time>,

Activates a new continuation by binding it to the simulation context, scheduling it at a future model time, and returning a Puck to it.

The function panics if the model time for activation has already passed. For a non-panicking version of this method, see try_schedule.

§Example Usage

You will usually want to pin the active object to pass it into the function like this:

let job = pin!(Job::new(async { /* do important work */ }));
let puck = sim.schedule(job, 2.0); // schedule in 2 units of time

§Note

The notes from Self::activate apply here as well.

Source

pub fn try_schedule<'a, A>( &'a self, actions: Pin<LeasedMut<'a, A>>, dt: impl Into<C::Time>, ) -> Result<A::Puck<'a>, CausalityError<C::Time>>
where A: Active<C>, C::Time: Add<Output = C::Time>,

Activates a new continuation, schedule it at a later model time, and returns a Puck to it.

Doesn’t panic if the proposed model time has already passed, returning a CausalityError instead. For the panicking version, see schedule.

Source

pub fn defer(&self) -> impl Future<Output = ()> + '_

Returns an awaitable Future that will suspend the currently executed continuation and reschedule it after every other continuation scheduled at the current model time had a chance to run.

The free function defer has the same semantics but reconstructs the simulation context through dynamic dispatching.