Struct Vc

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

A “Value Cell” (Vc for short) is a reference to a memoized computation result stored on the heap or in persistent cache, depending on the Turbo Engine backend implementation.

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();

Vcs are similar to a Future or a Promise with a few key differences:

• 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 indicies 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.

• Unlike futures (but like promises), the work that a Vc represents begins execution even if the Vc is not awaited.

For a more in-depth explanation of the concepts behind value cells, refer to the Turbopack book.

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. Exact type information of trait types (i.e. Vc<Box<dyn Trait>>) is not known because the function may not have finished execution yet. 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.

	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

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.

Function calls are neither “eager”, nor “lazy”. Even if not awaited, they 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 due to dirty task invalidation.

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.

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, Repr> Vc<T>

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

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: Upcast<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 async fn resolve(self) -> Result<Vc<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 async fn to_resolved(self) -> Result<ResolvedVc<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.

pub async fn resolve_strongly_consistent(self) -> Result<Self>

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

impl<T> Vc<T>

where T: VcValueTrait + ?Sized,

pub async fn try_resolve_sidecast<K>( vc: Self, ) -> Result<Option<Vc<K>>, ResolveTypeError>

where K: VcValueTrait + ?Sized,

Attempts to sidecast the given Vc<Box<dyn T>> to a Vc<Box<dyn K>>. This operation also resolves the Vc.

Returns None if the underlying value type does not implement K.

Note: if the trait T is required to implement K, use Vc::upcast(vc).resolve() instead. This provides stronger guarantees, removing the need for a Result return type.

pub async fn try_resolve_downcast<K>( vc: Self, ) -> Result<Option<Vc<K>>, ResolveTypeError>

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

Attempts to downcast the given Vc<Box<dyn T>> to a Vc<K>, where K is of the form Box<dyn L>, and L is a value trait. This operation also resolves the Vc.

Returns None if the underlying value type is not a K.

pub async fn try_resolve_downcast_type<K>( vc: Self, ) -> Result<Option<Vc<K>>, ResolveTypeError>

where K: Upcast<T> + VcValueType,

Attempts to downcast the given Vc<Box<dyn T>> to a Vc<K>, where K is a value type. This operation also resolves the Vc.

Returns None if the underlying value type is not a K.

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.

Trait Implementations

impl<T> Clone for Vc<T>

where T: ?Sized,

fn clone(&self) -> Self

Returns a copy 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> 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> 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> IntoTraitRef for Vc<T>

where T: VcValueTrait + ?Sized,

type ValueTrait = T

type Future = ReadVcFuture<T, VcValueTraitCast<T>>

fn into_trait_ref(self) -> Self::Future

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

fn is_transient(&self) -> bool

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

impl<T> TaskOutput for Vc<T>

where T: Send + ?Sized,

type Return = Vc<T>

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

fn try_into_raw_vc(self) -> Result<RawVc>

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: Upcast<Box<dyn ValueDebug>> + Send + Sync + ?Sized,

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,