Attribute Macro value

#[value]

Implements VcValueType for the given struct or enum. These value types can be used inside of a “value cell” as Vc<...>.

A Vc represents a (potentially lazy) memoized computation. Each Vc’s value is placed into a cell associated with the current TaskId. That Vc object can be awaited to get a read-only reference to the value contained in the cell.

This macro accepts multiple comma-separated arguments. For example:

#[turbo_tasks::value(transparent, into = "shared")]
struct Foo(Vec<u32>);

cell = "..."

Controls when a cell is invalidated upon recomputation of a task. Internally, this is performed by setting the VcValueType::CellMode associated type.

• "new": Always overrides the value in the cell, invalidating all dependent tasks.
• "shared" (default): Compares with the existing value in the cell, before overriding it. Requires the value to implement Eq.

Avoiding unnecessary invalidation is important to reduce downstream recomputation of tasks that depend on this cell’s value.

Use "new" only if a correct implementation of Eq is not possible, would be expensive (e.g. would require comparing a large collection), or if you’re implementing a low-level primitive that intentionally forces recomputation.

eq = "..."

By default, we #[derive(PartialEq, Eq)]. Eq is required by cell = "shared". This argument allows overriding that default implementation behavior.

• "manual": Prevents deriving Eq and PartialEq so you can do it manually.

into = "..."

This macro always implements a .cell() method on your type with the signature:

/// Wraps the value in a cell.
fn cell(self) -> Vc<Self>;

This argument controls the visibility of the .cell() method, as well as whether a From<T> for Vc<T> implementation is generated.

• "new" or "shared": Exposes both .cell() and From/Into implementations. Both of these values ("new" or "shared") do the same thing (for legacy reasons).
• "none" (default): Makes .cell() private and prevents implementing From/Into.

You should use the default value of "none" when providing your own public constructor methods.

The naming of this field and it’s values are due to legacy reasons.

serialization = "..."

Affects serialization via serde::Serialize and serde::Deserialize. Serialization is required for persistent caching of tasks to disk.

• "auto" (default): Derives the serialization traits and enables serialization.
• "auto_for_input": Same as "auto", but also adds the marker trait TypedForInput.
• "custom": Prevents deriving the serialization traits, but still enables serialization (you must manually implement serde::Serialize and serde::Deserialize).
• "custom_for_input": Same as "custom", but also adds the marker trait TypedForInput.
• "none": Disables serialization and prevents deriving the traits.

shared

Sets both cell = "shared" (already the default) and into = "shared", exposing the .cell() method and adding a From/Into implementation.

transparent

This attribute is only valid on single-element unit structs. When this value is set:

1. The struct will use #[repr(transparent)].
2. Read operations (vc.await?) return a ReadRef containing the inner type, rather than the outer struct. Internally, this is accomplished using VcTransparentRead for the VcValueType::Read associated type.
3. Construction of the type must be performed using Vc::cell(inner), rather than using the .cell() method on the outer type (outer.cell()).
4. The ValueDebug implementation will defer to the inner type.

This is commonly used to create VcValueType wrappers for foreign or generic types, such as Vec or Option.

local

Skip the implementation of NonLocalValue for this type.

If not specified, we apply the #[derive(NonLocalValue)] macro, which asserts that this struct has no fields containing Vc by implementing the NonLocalValue marker trait. Compile-time assertions are generated on every field, checking that they are also NonLocalValues.