pub trait TaskInput:
Send
+ Sync
+ Clone
+ Debug
+ PartialEq
+ Eq
+ Hash
+ TraceRawVcs
+ Encode
+ Decode<()> {
// Required method
fn is_transient(&self) -> bool;
// Provided methods
fn resolve_input(&self) -> impl Future<Output = Result<Self>> + Send + '_ { ... }
fn is_resolved(&self) -> bool { ... }
}Expand description
Trait to implement in order for a type to be accepted as a
#[turbo_tasks::function] argument.
§Serialization
For persistent caching of a task, arguments must be serializable. All TaskInputs must
implement the bincode Encode and Decode traits.
Transient task inputs are required to implement Encode and Decode, but are allowed to
panic at runtime. This requirement could be lifted in the future.
Bincode encoding must be deterministic and compatible with Eq comparisons. If two
TaskInputs compare equal they must also encode to the same bytes.
§Hash and Eq
Arguments are used as part of keys in a HashMap, so they must implement of PartialEq,
Eq, and Hash traits.
§Vc<T>
A Vc is a pointer to a cell. It implements TaskInput and serves as a “pass by reference”
argument:
- Memoization:
Vcis keyed by pointer for memoization purposes. Identical values in different cells are treated as distinct. - Singleton Pattern: To ensure memoization efficiency, the singleton pattern can be employed
to guarantee that identical values yield the same
Vc. For more info see Singleton Pattern Guide.
§Deriving TaskInput
Structs or enums can be made into task inputs by deriving TaskInput:
#[derive(TaskInput)]
struct MyStruct {
// Fields go here...
}Derived TaskInput types passed by value. When called, arguments are moved into a Box,
and then cloned before being passed into the function. If the task is invalidated, the
TaskInput is cloned again to allow the function to be re-executed. It’s recommended to ensure
that these types are cheap to clone.
Reference-counted types like Arc are cheap to clone, but each reference contained in a
TaskInput will be serialized independently in the persistent cache, and may consume extra disk
space. If an Arc points to a large type, consider wrapping that type in Vc, so that only
one copy of the value will be serialized.
Required Methods§
Sourcefn is_transient(&self) -> bool
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.
Any function called with a transient TaskInput will be transient. Any Vc constructed
in a transient task or in a top-level run_once closure will be
transient.
Internally, a Vc can be determined to be transient by comparing the owning task’s id
with the TRANSIENT_TASK_BIT mask.
Provided Methods§
Sourcefn resolve_input(&self) -> impl Future<Output = Result<Self>> + Send + '_
fn resolve_input(&self) -> impl Future<Output = Result<Self>> + Send + '_
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.
Sourcefn is_resolved(&self) -> bool
fn is_resolved(&self) -> bool
This should return true if there are any unresolved Vcs in the type.
Note that Vcs can sometimes be internally resolved, so you should call
Vc::is_resolved (or rely on the derive macro for this trait) instead of returning true
for any Vc. ResolvedVc::is_resolved always returns true.
If this returns true, a “local” resolution task calling TaskInput::resolve_input will
be spawned before the function accepting the arguments is run.
If this returns false, the TaskInput will be cloned instead of resolved, and
the function’s task will be spawned directly without a resolution step.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.