[−][src]Struct salsa::Runtime
The salsa runtime stores the storage for all queries as well as tracking the query stack and dependencies between cycles.
Each new runtime you create (e.g., via Runtime::new
or
Runtime::default
) will have an independent set of query storage
associated with it. Normally, therefore, you only do this once, at
the start of your application.
Implementations
impl<DB> Runtime<DB> where
DB: Database,
[src]
DB: Database,
pub fn new() -> Self
[src]
Create a new runtime; equivalent to Self::default
. This is
used when creating a new database.
pub fn storage(&self) -> &DB::DatabaseStorage
[src]
Returns the underlying storage, where the keys/values for all queries are kept.
pub fn snapshot(&self, from_db: &DB) -> Self
[src]
Returns a "forked" runtime, suitable for use in a forked
database. "Forked" runtimes hold a read-lock on the global
state, which means that any attempt to set
an input will
block until the forked runtime is dropped. See
ParallelDatabase::snapshot
for more information.
Warning. This second handle is intended to be used from a separate thread. Using two database handles from the same thread can lead to deadlock.
pub fn synthetic_write(&mut self, durability: Durability)
[src]
A "synthetic write" causes the system to act as though some
input of durability durability
has changed. This is mostly
useful for profiling scenarios, but it also has interactions
with garbage collection. In general, a synthetic write to
durability level D will cause the system to fully trace all
queries of durability level D and below. When running a GC, then:
- Synthetic writes will cause more derived values to be retained. This is because derived values are only retained if they are traced, and a synthetic write can cause more things to be traced.
- Synthetic writes can cause more interned values to be collected. This is because interned values can only be collected if they were not yet traced in the current revision. Therefore, if you issue a synthetic write, execute some query Q, and then start collecting interned values, you will be able to recycle interned values not used in Q.
In general, then, one can do a "full GC" that retains only
those things that are used by some query Q by (a) doing a
synthetic write at Durability::HIGH
, (b) executing the query
Q and then (c) doing a sweep.
WARNING: Just like an ordinary write, this method triggers cancellation. If you invoke it while a snapshot exists, it will block until that snapshot is dropped -- if that snapshot is owned by the current thread, this could trigger deadlock.
pub fn sweep_all(&self, db: &DB, strategy: SweepStrategy)
[src]
Default implementation for Database::sweep_all
.
pub fn id(&self) -> RuntimeId
[src]
The unique identifier attached to this SalsaRuntime
. Each
snapshotted runtime has a distinct identifier.
pub fn active_query(&self) -> Option<DB::DatabaseKey>
[src]
Returns the database-key for the query that this thread is actively executing (if any).
pub fn is_current_revision_canceled(&self) -> bool
[src]
Check if the current revision is canceled. If this method ever returns true, the currently executing query is also marked as having an untracked read -- this means that, in the next revision, we will always recompute its value "as if" some input had changed. This means that, if your revision is canceled (which indicates that current query results will be ignored) your query is free to shortcircuit and return whatever it likes.
This method is useful for implementing cancellation of queries.
You can do it in one of two ways, via Result
s or via unwinding.
The Result
approach looks like this:
- Some queries invoke
is_current_revision_canceled
and return a special value, likeErr(Canceled)
, if it returnstrue
. - Other queries propagate the special value using
?
operator. - API around top-level queries checks if the result is
Ok
orErr(Canceled)
.
The panic
approach works in a similar way:
- Some queries invoke
is_current_revision_canceled
and panic with a special value, likeCanceled
, if it returns true. - The implementation of
Database
trait overrideson_propagated_panic
to throw this special value as well. This way, panic gets propagated naturally through dependant queries, even across the threads. - API around top-level queries converts a
panic
intoResult
by catching the panic (using eitherstd::panic::catch_unwind
or threads) and downcasting the payload toCanceled
(re-raising panic if downcast fails).
Note that salsa is explicitly designed to be panic-safe, so cancellation via unwinding is 100% valid approach to cancellation.
pub fn report_untracked_read(&self)
[src]
Reports that the query depends on some state unknown to salsa.
Queries which report untracked reads will be re-executed in the next revision.
pub fn report_synthetic_read(&self, durability: Durability)
[src]
Acts as though the current query had read an input with the given durability; this will force the current query's durability to be at most durability
.
This is mostly useful to control the durability level for on-demand inputs.
Trait Implementations
impl<DB> Debug for Runtime<DB> where
DB: Database,
[src]
DB: Database,
impl<DB> Default for Runtime<DB> where
DB: Database,
[src]
DB: Database,
Auto Trait Implementations
impl<DB> RefUnwindSafe for Runtime<DB> where
<DB as DatabaseStorageTypes>::DatabaseStorage: RefUnwindSafe,
<DB as DatabaseStorageTypes>::DatabaseStorage: RefUnwindSafe,
impl<DB> Send for Runtime<DB> where
<DB as DatabaseStorageTypes>::DatabaseData: Send + Sync,
<DB as DatabaseStorageTypes>::DatabaseKey: Send,
<DB as DatabaseStorageTypes>::DatabaseStorage: Send + Sync,
<DB as DatabaseStorageTypes>::DatabaseData: Send + Sync,
<DB as DatabaseStorageTypes>::DatabaseKey: Send,
<DB as DatabaseStorageTypes>::DatabaseStorage: Send + Sync,
impl<DB> !Sync for Runtime<DB>
impl<DB> Unpin for Runtime<DB> where
<DB as DatabaseStorageTypes>::DatabaseKey: Unpin,
<DB as DatabaseStorageTypes>::DatabaseKey: Unpin,
impl<DB> !UnwindSafe for Runtime<DB>
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
V: MultiLane<T>,