Unverified Commit fc6bd9ea authored by Benjamin Woodruff's avatar Benjamin Woodruff Committed by GitHub

docs(turbopack): Merge task input docs from mdbook into rustdocs (#91136)

Copying content from https://turbopack-rust-docs.vercel.sh/turbo-engine/task_inputs.html

Removed some AI slop and some outdated stuff (`Value` is gone, we implemented `TaskInput` on `Arc`). Added a note about serialization of reference counted types.

Rendered:

![Screenshot 2026-03-09 at 21-07-44 TaskInput in turbo_tasks - Rust.png](https://app.graphite.com/user-attachments/assets/9035cabc-8781-485a-bb0c-155de8c4a8b3.png)
parent 0b1604a8
......@@ -71,7 +71,7 @@ pub use anyhow::{Error, Result};
use auto_hash_map::AutoSet;
use rustc_hash::FxHasher;
pub use shrink_to_fit::ShrinkToFit;
pub use turbo_tasks_macros::{TaskInput, turbobail, turbofmt, value_impl};
pub use turbo_tasks_macros::{turbobail, turbofmt, value_impl};
pub use crate::{
capture_future::TurboTasksPanic,
......@@ -309,6 +309,10 @@ pub use turbo_tasks_macros::value_trait;
#[rustfmt::skip]
pub use turbo_tasks_macros::task_storage;
/// Refer to [the trait documentation][trait@TaskInput] for usage.
#[rustfmt::skip]
pub use turbo_tasks_macros::TaskInput;
pub type TaskIdSet = AutoSet<TaskId, BuildHasherDefault<FxHasher>, 2>;
pub mod test_helpers {
......
......@@ -31,20 +31,89 @@ use crate::{
/// Trait to implement in order for a type to be accepted as a
/// [`#[turbo_tasks::function]`][crate::function] argument.
///
/// ## Serialization
///
/// For persistent caching of a task, arguments must be serializable. All `TaskInput`s 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
/// `TaskInput`s 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>`][Vc]
///
/// A [`Vc`] is a pointer to a cell. It implements `TaskInput` and serves as a "pass by reference"
/// argument:
///
/// - **Memoization**: [`Vc`] is 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][singleton].
///
/// [singleton]: https://turbopack-rust-docs.vercel.sh/turbo-engine/singleton.html
///
/// ## Deriving `TaskInput`
///
/// Structs or enums can be made into task inputs by deriving `TaskInput`:
///
/// ```rust
/// #[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.
pub trait TaskInput:
Send + Sync + Clone + Debug + PartialEq + Eq + Hash + TraceRawVcs + Encode + Decode<()>
{
/// This method should resolve any [`Vc`]s 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.
fn resolve_input(&self) -> impl Future<Output = Result<Self>> + Send + '_ {
async { Ok(self.clone()) }
}
/// This should return `true` if there are any unresolved [`Vc`]s in the type.
///
/// Note that [`Vc`]s 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][Clone] instead of resolved, and
/// the function's task will be spawned directly without a resolution step.
fn is_resolved(&self) -> bool {
true
}
/// 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`][crate::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`][crate::TRANSIENT_TASK_BIT] mask.
fn is_transient(&self) -> bool;
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment