Struct stakker::Core

pub struct Core { /* fields omitted */ }

Core operations available from both Stakker and Cx objects

Both Stakker and Cx references auto-dereference to a Core reference, so typically either of those can be used wherever a Core reference is required.

Implementations

impl Core

pub fn now(&self) -> Instant

Our view of the current time. Actors should use this in preference to Instant::now() for speed and in order to work in virtual time.

pub fn systime(&self) -> SystemTime

Get the current SystemTime. Normally this returns the same as SystemTime::now(), but if running in virtual time, it would return the virtual SystemTime instead (as provided to Stakker::set_systime by the virtual time main loop). Note that this time is not suitable for timing things, as it may go backwards if the user or a system process adjusts the clock. It is just useful for showing or recording "human time" for the user, and for recording times that are meaningful on a longer scale, e.g. from one run of a process to the next.

pub fn defer(&mut self, f: impl FnOnce(&mut Stakker) + 'static)

Defer an operation to be executed later. It is put on the main queue, and run as soon all operations preceding it have been executed.

pub fn lazy(&mut self, f: impl FnOnce(&mut Stakker) + 'static)

Defer an operation to executed soon, but lazily. It goes onto a lower priority queue executed once the normal defer queue has been completely cleared (including any further deferred items added whilst clearing that queue). This can be used for flushing data generated in this batch of processing, for example.

pub fn idle(&mut self, f: impl FnOnce(&mut Stakker) + 'static)

Defer an operation to be executed when this process next becomes idle, i.e. when all other queues are empty and there is no I/O to process. This can be used to implement backpressure on incoming streams, i.e. only fetch more data once there is nothing else left to do.

pub fn after(
    &mut self,
    dur: Duration,
    f: impl FnOnce(&mut Stakker) + 'static
) -> FixedTimerKey

Delay an operation to be executed after a duration has passed. This is the same as adding it as a fixed timer. Returns a key that can be used to delete the timer.

pub fn timer_add(
    &mut self,
    expiry: Instant,
    f: impl FnOnce(&mut Stakker) + 'static
) -> FixedTimerKey

Add a fixed timer that expires at the given time. Returns a key that can be used to delete the timer.

pub fn timer_del(&mut self, key: FixedTimerKey) -> bool

Delete a fixed timer. Returns true on success, false if timer no longer exists (i.e. it expired or was deleted)

pub fn timer_max_add(
    &mut self,
    expiry: Instant,
    f: impl FnOnce(&mut Stakker) + 'static
) -> MaxTimerKey

Add a "Max" timer, which expires at the greatest (latest) expiry time provided. See MaxTimerKey for the characteristics of this timer. Returns a key that can be used to delete or modify the timer.

See also the timer_max! macro, which may be more convenient as it combines Core::timer_max_add and Core::timer_max_upd.

pub fn timer_max_upd(&mut self, key: MaxTimerKey, expiry: Instant) -> bool

Update a "Max" timer with a new expiry time. It will be used as the new expiry time only if it is greater than the current expiry time. This call is designed to be very cheap to call frequently.

Returns true on success, false if timer no longer exists (i.e. it expired or was deleted)

See also the timer_max! macro, which may be more convenient as it combines Core::timer_max_add and Core::timer_max_upd.

pub fn timer_max_del(&mut self, key: MaxTimerKey) -> bool

Delete a "Max" timer. Returns true on success, false if timer no longer exists (i.e. it expired or was deleted)

pub fn timer_max_active(&mut self, key: MaxTimerKey) -> bool

Check whether a "Max" timer is active. Returns true if it exists and is active, false if it expired or was deleted or never existed

pub fn timer_min_add(
    &mut self,
    expiry: Instant,
    f: impl FnOnce(&mut Stakker) + 'static
) -> MinTimerKey

Add a "Min" timer, which expires at the smallest (earliest) expiry time provided. See MinTimerKey for the characteristics of this timer. Returns a key that can be used to delete or modify the timer.

See also the timer_min! macro, which may be more convenient as it combines Core::timer_min_add and Core::timer_min_upd.

pub fn timer_min_upd(&mut self, key: MinTimerKey, expiry: Instant) -> bool

Update a "Min" timer with a new expiry time. It will be used as the new expiry time only if it is earlier than the current expiry time. This call is designed to be very cheap to call frequently, so long as the change is within the wiggle-room allowed. Otherwise it causes the working timer to be deleted and added again, readjusting the wiggle-room accordingly.

Returns true on success, false if timer no longer exists (i.e. it expired or was deleted)

See also the timer_min! macro, which may be more convenient as it combines Core::timer_min_add and Core::timer_min_upd.

pub fn timer_min_del(&mut self, key: MinTimerKey) -> bool

Delete a "Min" timer. Returns true on success, false if timer no longer exists (i.e. it expired or was deleted)

pub fn timer_min_active(&mut self, key: MinTimerKey) -> bool

Check whether a "Min" timer is active. Returns true if it exists and is active, false if it expired or was deleted or never existed

pub fn anymap_get<T: Clone + 'static>(&mut self) -> T

Gets a clone of a value from the Stakker anymap. This is intended to be used to access certain global instances, for example the I/O poll implementation that this Stakker is running inside. Panics if the value is not found.

pub fn anymap_try_get<T: Clone + 'static>(&mut self) -> Option<T>

Tries to get a clone of a value from the Stakker anymap. This is intended to be used to access certain global instances, for example the I/O poll implementation that this Stakker is running inside. Returns None if the value is missing.

pub fn shutdown(&mut self, cause: StopCause)

Request that the event loop terminate. For this to work, the event loop must check Core::not_shutdown each time through the loop. See also the ret_shutdown! macro which can be used as the StopCause handler for an actor, to shut down the event loop when that actor terminates. The event loop code can obtain the StopCause using Core::shutdown_reason.

pub fn not_shutdown(&self) -> bool

Should the event loop continue running? Returns true if there is no active shutdown in progress.

pub fn shutdown_reason(&mut self) -> Option<StopCause>

Get the reason for shutdown, if shutdown was requested. After calling this, the shutdown flag is cleared, i.e. Core::not_shutdown will return false and the event loop could continue to run.

pub fn deferrer(&self) -> Deferrer

Get a new Deferrer instance which can be used to defer calls to the main queue from contexts in the same thread which don't have access to Core, for example drop handlers.

pub fn waker(&mut self, cb: impl FnMut(&mut Stakker, bool) + 'static) -> Waker

Register a wake handler callback, and obtain a Waker instance which can be passed to another thread. The wake handler will always be executed in the main thread. When Waker::wake is called in another thread, a wake-up is scheduled to occur in the main thread, using the wake-up mechanism provided by the I/O poller. Then when that wake-up is received, the corresponding wake handler is executed. Note that this is efficient -- if many wake handlers are scheduled around the same time, they share the same main thread wake-up.

The wake handler is called in the main thread with arguments of (stakker, deleted). Note that there is a small chance of a spurious wake call happening occasionally, so the wake handler code must be ready for that. If deleted is true then the Waker was dropped, and this wake handler is also just about to be dropped.

This call panics if no I/O poller has yet set up a waker using Stakker::set_poll_waker.

pub fn access_core(&mut self) -> &mut Core

Used in macros to get a Core reference

pub fn access_deferrer(&self) -> &Deferrer

Used in macros to get a Deferrer reference