Struct Vc 

pub struct Vc<T>
where
    T: ?Sized,
{ /* private fields */ }

Value cells represent the pending result of a computation, similar to a cell in a spreadsheet. When a Vc’s contents change, the change is propagated by invalidating dependent tasks.

In order to get a reference to the pointed value, you need to .await the Vc<T> to get a ReadRef<T>:

let some_vc: Vc<T>;
let some_ref: ReadRef<T> = some_vc.await?;
some_ref.some_method_on_t();

The returned ReadRef<T> represents a [reference-counted][triomphe::Arc] snapshot of a cell’s value at a given point in time.

Understanding Cells

A cell is a storage location for data associated with a task. Cells provide:

• Immutability: Once a value is stored in a cell, it becomes immutable until that task is re-executed.
• Recomputability: If invalidated or cache evicted, a cell’s contents can be re-computed by re-executing its associated task.
• Dependency Tracking: When a cell’s contents are read (with .await), the reading task is marked as dependent on the cell.
• Persistence: Cells owned by persisted tasks are serializable using the bincode crate.

Cells are stored in arrays associated with the task that constructed them. A Vc can either point to a specific cell (this is a “resolved” cell), or the return value of a function (this is an “unresolved” cell).

TaskOutputs point to a specific task, and refer to the output cell for that task. TaskCells point to a specific cell within a task. Task cells are stored in a table (conceptually a Map<ValueTypeId, Vec<SharedReference>>) and are referenced by a pair of a type id and a sequentially allocated index.

Constructing a Cell

Most types using the #[turbo_tasks::value] macro are given a .cell() method. This method returns a Vc of the type.

Transparent wrapper types that use #[turbo_tasks::value(transparent)] cannot define methods on their wrapped type, so instead the Vc::cell function can be used to construct these types.

Updating a Cell

Every time a task runs, its cells are re-constructed.

When .cell() or Vc::cell is called, the cell counter for the ValueTypeId is incremented, and the value is compared to the previous execution’s using PartialEq. If the value with that index differs, the cell is updated, and all dependent tasks are invalidated.

The compare-then-update behavior can be overridden to always update and invalidate using the cell = "new" argument.

Because cells are keyed by a combination of their type and construction order, task functions should have a deterministic execution order. A function with inconsistent ordering may result in wasted work by invalidating additional cells, though it will still give correct results:

• You should use types with deterministic behavior. If you plan to iterate over a collection, use IndexMap, BTreeMap, or FrozenMap in place of types like HashMap (which gives randomized iteration order).
• If you perform work in parallel within a single turbo-task, be careful not to construct cells inside the parts of your function that are executed across multiple threads. That can lead to accidentally non-deterministic behavior. Instead, collect results in parallel, and construct cells in the main thread after sorting the results.

Reading Vcs

Vcs implement IntoFuture and can be awaited, but there are few key differences compared to a normal Future:

• The value pointed to by a Vc can be invalidated by changing dependencies or cache evicted, meaning that awaiting a Vc multiple times can give different results. A ReadRef is snapshot of the underlying cell at a point in time.

• Reading (awaiting) Vcs causes the current task to be tracked a dependent of the Vc’s task or task cell. When the read task or task cell changes, the current task may be re-executed.

• Vc types are always Copy. Most Futures are not. This works because Vcs are represented as a few ids or indices into data structures managed by the turbo-tasks framework. Vc types are not reference counted, but do support tracing for a hypothetical (unimplemented) garbage collector.

• An uncached turbo_tasks::function that returns a Vc begins after being called, even if the Vc is not awaited.

Subtypes

There are a couple of explicit “subtypes” of Vc. These can both be cheaply converted back into a Vc.

• ResolvedVc: (aka RawVc::TaskCell) A reference to a cell constructed within a task, as part of a Vc::cell or value_type.cell() constructor. As the cell has been constructed at least once, the concrete type of the cell is known (allowing downcasting). This is stored as a combination of a task id, a type id, and a cell id.

• OperationVc: (aka RawVc::TaskOutput) The synchronous return value of a turbo_tasks::function. Internally, this is stored using a task id. OperationVcs must first be connected before being read.

ResolvedVc is almost always preferred over the more awkward OperationVc API, but OperationVc can be useful when dealing with collectibles, when you need to read the result of a function with strong consistency, or with State.

These many representations are stored internally using a type-erased RawVc. Type erasure reduces the monomorphization (and therefore binary size and compilation time) required to support Vc and its subtypes.

This means that Vc often uses the same in-memory representation as a ResolvedVc or an OperationVc, but it does not expose the same methods (e.g. downcasting) because the exact memory representation is not statically defined.

	Representation	Equality	Downcasting	Strong Consistency	Collectibles	Non-Local
Vc	One of many	❌ Broken	⚠️ After resolution	❌ Eventual	❌ No	❌ No
ResolvedVc	Task Id + Type Id + Cell Id	✅ Yes*	✅ Yes, cheaply	❌ Eventual	❌ No	✅ Yes
OperationVc	Task Id	✅ Yes*	⚠️ After resolution	✅ Supported	✅ Yes	✅ Yes

* see the type’s documentation for details

Equality & Hashing

Because Vcs can be equivalent but have different representation, it’s not recommended to compare Vcs by equality. Instead, you should convert a Vc to an explicit subtype first (likely ResolvedVc). Future versions of Vc may not implement Eq, PartialEq, or Hash.

Execution Model

While task functions are expected to be side-effect free, their execution behavior is still important for performance reasons, or to code using collectibles to represent issues or side-effects.

Even if not awaited, uncached function calls are guaranteed to execute (potentially emitting collectibles) before the root task finishes or before the completion of any strongly consistent read containing their call. However, the exact point when that execution begins is an implementation detail. Functions may execute more than once if one of their dependencies is invalidated.

Eventual Consistency

Because turbo_tasks is eventually consistent, two adjacent .awaits of the same Vc<T> may return different values. If this happens, the task will eventually be invalidated and re-executed by a strongly consistent root task. Top-level tasks will panic if they attempt to perform an eventually consistent read of a Vc.

Tasks affected by a read inconsistency can return errors. These errors will be discarded by the strongly consistent root task. Tasks should never panic due to a potentially-inconsistent value stored in a Vc.

Currently, all inconsistent tasks are polled to completion. Future versions of the turbo_tasks library may drop tasks that have been identified as inconsistent after some time. As non-root tasks should not perform side-effects, this should be safe, though it may introduce some issues with cross-process resource management.

Optimization: Local Outputs

In addition to the potentially-explicit “resolved” and “operation” representations of a Vc, there’s another internal representation of a Vc, known as a “Local Vc”, or RawVc::LocalOutput.

This is a special case of the synchronous return value of a turbo_tasks::function when some of its arguments have not yet been resolved. These are stored in task-local state that is freed after their parent non-local task exits.

We prevent potentially-local Vcs from escaping the lifetime of a function using the NonLocalValue marker trait alongside some fallback runtime checks. We do this to avoid some ergonomic challenges that would come from using lifetime annotations with Vc.

Implementations

impl<T, Inner> Vc<T>

where T: VcValueType<Read = VcTransparentRead<T, Inner>>, Inner: Any + Send + Sync,

pub fn cell(inner: Inner) -> Self

impl<T> Vc<T>

where T: ?Sized,

pub async fn debug_identifier(vc: Self) -> Result<String>

Returns a debug identifier for this Vc.

pub fn into_raw(vc: Self) -> RawVc

Returns the RawVc corresponding to this Vc.

pub fn upcast<K>(vc: Self) -> Vc<K>

where T: UpcastStrict<K>, K: VcValueTrait + ?Sized,

Upcasts the given Vc<T> to a Vc<Box<dyn K>>.

This is also available as an Into/From conversion.

pub fn upcast_non_strict<K>(vc: Self) -> Vc<K>

where T: Upcast<K>, K: VcValueTrait + ?Sized,

Upcasts the given Vc<T> to a Vc<Box<dyn K>>

This has a loose type constraint which would allow upcasting to the same type, prefer using Vc::upcast when possible. This is useful for extension traits and other more generic usecases.

Example

// In generic code where T might be the same as K
fn process_foo(vc: ResolvedVc<impl Upcast<Box<dyn MyTrait>>>) -> Vc<Foo> {
   let my_trait: ResolvedVc<Box<dyn MyTrait>> = Vc::upcast_non_strict(vc);
   my_trait.do_something()
}

Using generics you could allow users to pass any compatible type, but if you specified UpcastStrict<...> instead of Upcast<...> you would disallow calling this function if you already had a ResolvedVc<Box<dyn MyTrait>>. So this function has a looser type constraint to make these functions easier to write and use.

pub async fn as_side_effect(self) -> Result<()>

Runs the operation, but ignores the returned Vc. Use that when only interested in running the task for side effects.

pub fn resolve(self) -> ResolveVcFuture<T>

Do not use this: Use Vc::to_resolved instead. If you must have a resolved Vc type and not a ResolvedVc type, simply deref the result of Vc::to_resolved.

pub fn to_resolved(self) -> ToResolvedVcFuture<T>

Resolve the reference until it points to a cell directly, and wrap the result in a ResolvedVc, which statically guarantees that the Vc was resolved.

pub fn is_resolved(self) -> bool

Returns true if the reference is resolved, meaning the underlying RawVc uses the RawVc::TaskCell representation.

If you need resolved Vc value, it’s typically better to use the ResolvedVc type to enforce your requirements statically instead of dynamically at runtime.

See also ResolvedVc::to_resolved and RawVc::is_resolved.

pub fn is_local(self) -> bool

Returns true if the Vc was by a local function call (e.g. one who’s arguments were not fully resolved) and has not yet been resolved.

Aside from differences in caching, a function’s behavior should not be changed by using local or non-local cells, so this function is mostly useful inside tests and internally in turbo-tasks.

impl<T> Vc<T>

where T: VcValueType,

pub fn strongly_consistent(self) -> ReadVcFuture<T>

Do not use this: Use OperationVc::read_strongly_consistent instead.

pub fn untracked(self) -> ReadVcFuture<T>

Returns a untracked read of the value. This will not invalidate the current function when the read value changed.

pub fn final_read_hint(self) -> ReadVcFuture<T>

Read the value with the hint that this is the final read of the value. This might drop the cell content. Future reads might need to recompute the value.

impl<T> Vc<T>

where T: VcValueType, <<T as VcValueType>::Read as VcRead<T>>::Target: Clone,

pub fn owned(self) -> ReadOwnedVcFuture<T>

Read the value and returns a owned version of it. It might clone the value.

impl<T> Vc<T>

where T: VcValueType, <<T as VcValueType>::Read as VcRead<T>>::Target: KeyedEq,

pub fn get<'l, Q>(self, key: &'l Q) -> ReadKeyedVcFuture<'l, T, Q>

where Q: Hash + ?Sized, <<T as VcValueType>::Read as VcRead<T>>::Target: KeyedAccess<Q>,

Read the value and selects a keyed value from it. Only depends on the used key instead of the full value.

pub fn contains_key<'l, Q>( self, key: &'l Q, ) -> ReadContainsKeyedVcFuture<'l, T, Q>

where Q: Hash + ?Sized, <<T as VcValueType>::Read as VcRead<T>>::Target: KeyedAccess<Q>,

Read the value and checks if it contains the given key. Only depends on the used key instead of the full value.

impl<T> Vc<T>

where T: VcValueTrait + ?Sized,

pub fn into_trait_ref(self) -> ReadVcFuture<T, VcValueTraitCast<T>>

Converts this trait vc into a trait reference.

The signature is similar to IntoFuture::into_future, but we don’t want trait vcs to have the same future-like semantics as value vcs when it comes to producing refs. This behavior is rarely needed, so in most cases, .awaiting a trait vc is a mistake.

Trait Implementations

impl<'__de, T, __Context> BorrowDecode<'__de, __Context> for Vc<T>

where T: ?Sized,

fn borrow_decode<__D: BorrowDecoder<'__de, Context = __Context>>( decoder: &mut __D, ) -> Result<Self, DecodeError>

Attempt to decode this type with the given BorrowDecode.

impl<T> Clone for Vc<T>

where T: ?Sized,

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for Vc<T>

where T: ?Sized,

Generates an opaque debug representation of the Vc itself, but not the data inside of it.

This is implemented to allow types containing Vc to implement the synchronous Debug trait, but in most cases users should use the ValueDebug implementation to get a string representation of the contents of the cell.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T, __Context> Decode<__Context> for Vc<T>

where T: ?Sized,

fn decode<__D: Decoder<Context = __Context>>( decoder: &mut __D, ) -> Result<Self, DecodeError>

Attempt to decode this type with the given Decode.

impl<T> Default for Vc<T>

where T: ValueDefault,

fn default() -> Self

Returns the “default value” for a type.

impl<'de, T> Deserialize<'de> for Vc<T>

where T: ?Sized,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T> Encode for Vc<T>

where T: ?Sized,

fn encode<__E: Encoder>(&self, encoder: &mut __E) -> Result<(), EncodeError>

Encode a given type.

impl<T> From<RawVc> for Vc<T>

where T: ?Sized,

fn from(node: RawVc) -> Self

Converts to this type from the input type.

impl<T> Hash for Vc<T>

where T: ?Sized,

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T> IntoFuture for &Vc<T>

where T: VcValueType,

type Output = <ReadVcFuture<T> as Future>::Output

The output that the future will produce on completion.

type IntoFuture = ReadVcFuture<T>

Which kind of future are we turning this into?

fn into_future(self) -> Self::IntoFuture

Creates a future from a value.

impl<T> IntoFuture for &mut Vc<T>

where T: VcValueType,

type Output = <ReadVcFuture<T> as Future>::Output

The output that the future will produce on completion.

type IntoFuture = ReadVcFuture<T>

Which kind of future are we turning this into?

fn into_future(self) -> Self::IntoFuture

Creates a future from a value.

impl<T> IntoFuture for Vc<T>

where T: VcValueType,

type Output = <ReadVcFuture<T> as Future>::Output

The output that the future will produce on completion.

type IntoFuture = ReadVcFuture<T>

Which kind of future are we turning this into?

fn into_future(self) -> Self::IntoFuture

Creates a future from a value.

impl<T> PartialEq for Vc<T>

where T: ?Sized,

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> Serialize for Vc<T>

where T: ?Sized,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<T> TaskInput for Vc<T>

where T: Send + Sync + ?Sized,

fn is_resolved(&self) -> bool

This should return true if there are any unresolved Vcs in the type.

fn is_transient(&self) -> bool

This should return true if this object contains a Vc (or any subtype of Vc) pointing to a cell owned by a transient task.

async fn resolve_input(&self) -> Result<Self>

This method should resolve any Vcs nested inside of this object, cloning the object in the process. If the input is unresolved (TaskInput::is_resolved) a “local” resolution task is created that runs this method.

impl<T> TaskOutput for Vc<T>

where T: Send + ?Sized,

type Return = T

fn try_into_raw_vc(self) -> Result<RawVc>

fn try_from_raw_vc(raw_vc: RawVc) -> Vc<Self::Return>

impl<T> TraceRawVcs for Vc<T>

where T: ?Sized,

fn trace_raw_vcs(&self, trace_context: &mut TraceRawVcsContext)

fn get_raw_vcs(&self) -> Vec<RawVc>

impl<T> ValueDebugFormat for Vc<T>

where T: UpcastStrict<Box<dyn ValueDebug>> + Send + Sync + ?Sized,

Available on debug-assertions enabled only.

fn value_debug_format(&self, depth: usize) -> ValueDebugFormatString<'_>

impl<T> Copy for Vc<T>

where T: ?Sized,

impl<T> Eq for Vc<T>

where T: ?Sized,

impl<T> Unpin for Vc<T>

where T: ?Sized,