turbo_tasks/
lib.rs

1#![doc = include_str!("../README.md")]
2#![feature(trivial_bounds)]
3#![feature(min_specialization)]
4#![deny(unsafe_op_in_unsafe_fn)]
5#![feature(error_generic_member_access)]
6#![feature(arbitrary_self_types)]
7#![feature(arbitrary_self_types_pointers)]
8#![feature(ptr_metadata)]
9#![feature(exclusive_wrapper)]
10#![feature(sync_unsafe_cell)]
11#![feature(async_fn_traits)]
12#![feature(impl_trait_in_assoc_type)]
13#![feature(const_type_name)]
14#![feature(mpmc_channel)]
15
16pub mod backend;
17mod capture_future;
18mod collectibles;
19mod completion;
20pub mod debug;
21#[doc = include_str!("../FORMATTING.md")]
22pub mod display;
23pub mod duration_span;
24mod dyn_task_inputs;
25mod effect;
26mod error;
27pub mod event;
28pub mod graph;
29mod id;
30mod id_factory;
31mod invalidation;
32mod join_iter_ext;
33pub mod keyed;
34mod local_task_tracker;
35#[doc(hidden)]
36pub mod macro_helpers;
37mod manager;
38pub mod mapped_read_ref;
39mod marker_trait;
40pub mod message_queue;
41mod native_function;
42mod once_map;
43mod output;
44pub mod panic_hooks;
45pub mod parallel;
46pub mod primitives;
47mod priority_runner;
48mod read_options;
49mod read_ref;
50pub mod registry;
51pub mod scope_bounded;
52pub mod scope_unbounded;
53mod serialization_invalidation;
54pub mod small_duration;
55mod spawn;
56mod state;
57pub mod task;
58#[cfg(feature = "task_dirty_cause")]
59mod task_dirty_cause;
60mod task_execution_reason;
61pub mod task_statistics;
62mod trait_ref;
63mod triomphe_utils;
64pub mod util;
65mod value;
66mod value_type;
67mod vc;
68
69use std::hash::BuildHasherDefault;
70
71pub use anyhow::{Error, Result};
72use auto_hash_map::AutoSet;
73use rustc_hash::FxHasher;
74pub use shrink_to_fit::ShrinkToFit;
75pub use turbo_tasks_macros::{DeterministicHash, turbobail, turbofmt};
76
77#[cfg(feature = "inline_execution_stats")]
78pub use crate::manager::InlineExecutionStats;
79#[cfg(feature = "task_dirty_cause")]
80pub use crate::task_dirty_cause::TaskDirtyCause;
81pub use crate::{
82    capture_future::TurboTasksPanic,
83    collectibles::CollectiblesSource,
84    completion::{Completion, Completions},
85    display::{ValueToString, ValueToStringRef},
86    dyn_task_inputs::{
87        DynTaskInputs, DynTaskInputsStorage, HeapDynTaskInputsStorage, StackDynTaskInputsStorage,
88    },
89    effect::{
90        ApplyError, CapturedEffect, Effect, EffectError, EffectExt, EffectStateStorage, Effects,
91        EffectsError, read_strongly_consistent_and_apply_effects,
92        resolve_strongly_consistent_and_take_and_apply_effects, take_effects,
93    },
94    error::PrettyPrintError,
95    id::{
96        ExecutionId, FunctionId, LocalTaskId, TRANSIENT_TASK_BIT, TaskId, TraitTypeId, ValueTypeId,
97    },
98    invalidation::{
99        InvalidationReason, InvalidationReasonKind, InvalidationReasonSet, Invalidator,
100        get_invalidator,
101    },
102    join_iter_ext::{JoinIterExt, TryFlatJoinIterExt, TryJoinIterExt},
103    manager::{
104        CurrentCellRef, GcRoot, InputResolution, ReadCellTracking, ReadConsistency, ReadTracking,
105        ScheduleKey, TaskPersistence, TaskPriority, TurboTasks, TurboTasksApi, TurboTasksCallApi,
106        Unused, UpdateInfo, dynamic_call, emit, get_serialization_invalidator, mark_finished,
107        mark_stateful, mark_top_level_task, prevent_gc, run, run_once, run_once_with_reason,
108        trait_call, turbo_tasks, turbo_tasks_scope, turbo_tasks_weak,
109        unmark_top_level_task_may_leak_eventually_consistent_state, with_turbo_tasks,
110    },
111    mapped_read_ref::MappedReadRef,
112    output::OutputContent,
113    read_options::{ReadCellOptions, ReadOutcome, ReadOutputOptions},
114    read_ref::ReadRef,
115    serialization_invalidation::SerializationInvalidator,
116    spawn::{JoinHandle, block_for_future, block_in_place, spawn, spawn_blocking, spawn_thread},
117    state::{State, parking_lot_mutex_bincode},
118    task::{
119        SharedReference, TypedSharedReference,
120        task_input::{EitherTaskInput, TaskInput},
121    },
122    task_execution_reason::TaskExecutionReason,
123    trait_ref::TraitRef,
124    value::{TransientInstance, TransientValue},
125    value_type::{Evictability, TraitMethod, TraitType, ValueType, ValueTypePersistence},
126    vc::{
127        CellId, Dynamic, NonLocalValue, OperationValue, OperationVc, OptionVcExt, OrdResolvedVc,
128        RawVc, RawVcUnpacked, ReadRawVcFuture, ReadVcFuture, ResolveOperationVcFuture,
129        ResolveRawVcFuture, ResolveVcFuture, ResolvedVc, ToResolvedVcFuture, Upcast, UpcastStrict,
130        ValueDefault, Vc, VcCast, VcCellCompareMode, VcCellHashedCompareMode,
131        VcCellKeyedCompareMode, VcCellNewMode, VcDefaultRead, VcRead, VcTransparentRead,
132        VcValueTrait, VcValueTraitCast, VcValueType, VcValueTypeCast,
133    },
134};
135
136pub type FxIndexSet<T> = indexmap::IndexSet<T, BuildHasherDefault<FxHasher>>;
137pub type FxIndexMap<K, V> = indexmap::IndexMap<K, V, BuildHasherDefault<FxHasher>>;
138pub type FxDashMap<K, V> = dashmap::DashMap<K, V, BuildHasherDefault<FxHasher>>;
139
140// Copied from indexmap! and indexset!
141#[macro_export]
142macro_rules! fxindexmap {
143    (@single $($x:tt)*) => (());
144    (@count $($rest:expr),*) => (<[()]>::len(&[$($crate::fxindexmap!(@single $rest)),*]));
145
146    ($($key:expr => $value:expr,)+) => { $crate::fxindexmap!($($key => $value),+) };
147    ($($key:expr => $value:expr),*) => {
148        {
149            let _cap = $crate::fxindexmap!(@count $($key),*);
150            let mut _map = $crate::FxIndexMap::with_capacity_and_hasher(_cap, Default::default());
151            $(
152                _map.insert($key, $value);
153            )*
154            _map
155        }
156    };
157}
158#[macro_export]
159macro_rules! fxindexset {
160    (@single $($x:tt)*) => (());
161    (@count $($rest:expr),*) => (<[()]>::len(&[$($crate::fxindexset!(@single $rest)),*]));
162
163    ($($value:expr,)+) => { $crate::fxindexset!($($value),+) };
164    ($($value:expr),*) => {
165        {
166            let _cap = $crate::fxindexset!(@count $($value),*);
167            let mut _set = $crate::FxIndexSet::with_capacity_and_hasher(_cap, Default::default());
168            $(
169                _set.insert($value);
170            )*
171            _set
172        }
173    };
174}
175
176#[doc = include_str!("../singleton_pattern.md")]
177pub mod _singleton_pattern {}
178
179#[doc = include_str!("../function.md")]
180#[rustfmt::skip]
181pub use turbo_tasks_macros::function;
182
183/// Implements [`VcValueType`] for the given `struct` or `enum`. These value types can be used
184/// inside of a "value cell" as [`Vc<...>`][Vc].
185///
186/// A [`Vc`] represents the result of a computation. Each [`Vc`]'s value is placed into a cell
187/// associated with the current [`TaskId`]. That [`Vc`] object can be `await`ed to get [a read-only
188/// reference to the value contained in the cell][ReadRef].
189///
190/// This macro accepts multiple comma-separated arguments. For example:
191///
192/// ```
193/// # #![feature(arbitrary_self_types)]
194//  # #![feature(arbitrary_self_types_pointers)]
195/// #[turbo_tasks::value(transparent, shared)]
196/// struct Foo(Vec<u32>);
197/// ```
198///
199/// ## `cell = "..."`
200///
201/// Controls when a cell is invalidated upon recomputation of a task. Internally, this is performed
202/// by setting the [`VcValueType::CellMode`] associated type.
203///
204/// - **`"new"`:** Always overrides the value in the cell, invalidating all dependent tasks.
205/// - **`"compare"` *(default)*:** Compares with the existing value in the cell, before overriding it.
206///   Requires the value to implement [`Eq`].
207/// - **`"keyed"`:** Like `"compare"`, but uses per-key invalidation for transparent map types.
208///
209/// Avoiding unnecessary invalidation is important to reduce downstream recomputation of tasks that
210/// depend on this cell's value.
211///
212/// Use `"new"` only if a correct implementation of [`Eq`] is not possible, would be expensive (e.g.
213/// would require comparing a large collection), or if you're implementing a low-level primitive
214/// that intentionally forces recomputation.
215///
216/// ## `eq = "..."`
217///
218/// By default, we `#[derive(PartialEq, Eq)]`. [`Eq`] is required by `cell = "compare"`. This
219/// argument allows overriding that default implementation behavior.
220///
221/// - **`"manual"`:** Prevents deriving [`Eq`] and [`PartialEq`] so you can do it manually.
222///
223/// ## `serialization = "..."`
224///
225/// Affects serialization via [`bincode::Encode`] and [`bincode::Decode`]. Serialization is required
226/// for the filesystem cache of tasks.
227///
228/// - **`"auto"` *(default)*:** Derives the bincode traits and enables serialization.
229/// - **`"custom"`:** Prevents deriving the bincode traits, but still enables serialization
230///   (you must manually implement [`bincode::Encode`] and [`bincode::Decode`]).
231/// - **`"hash"`:** Like `"none"` (no bincode serialization), but instead stores a hash of the cell
232///   value so that changes can be detected even when the transient cell data has been evicted
233///   from memory or was never stored in the cache—avoiding unnecessary downstream invalidation.
234///   Only valid with `cell = "compare"`.
235///   Requires the value to implement both [`Eq`] and [`DeterministicHash`][turbo_tasks_hash::DeterministicHash].
236/// - **`"none"`:** Disables serialization and prevents deriving the traits.
237///
238/// ## `hash = "..."`
239///
240/// By default, when using `serialization = "hash"`, we `#[derive(DeterministicHash)]`. This argument allows
241/// overriding that default implementation behavior.
242///
243/// - **`"manual"`:** Prevents deriving [`DeterministicHash`][turbo_tasks_hash::DeterministicHash] so you can do it manually.
244///   Only valid with `serialization = "hash"`.
245///
246/// ## `shared`
247///
248/// This flag makes the macro-generated `.cell()` method public so everyone can use it.
249///
250/// Non-transparent types are given a `.cell()` method. That method returns a `Vc` of the type.
251///
252/// This option does not apply to wrapper types that use `transparent`. Those use the public
253/// [`Vc::cell`] function for construction.
254///
255/// ## `transparent`
256///
257/// This attribute is only valid on single-element unit structs. When this value is set:
258///
259/// 1. The struct will use [`#[repr(transparent)]`][repr-transparent].
260/// 1. Read operations (`vc.await?`) return a [`ReadRef`] containing the inner type, rather than the
261///    outer struct. Internally, this is accomplished using [`VcTransparentRead`] for the
262///    [`VcValueType::Read`] associated type.
263/// 1. Construction of the type must be performed using [`Vc::cell(inner)`][Vc::cell], rather than
264///    using the `.cell()` method on the outer type (`outer.cell()`).
265/// 1. The [`ValueDebug`][crate::debug::ValueDebug] implementation will defer to the inner type.
266///
267/// This is commonly used to create [`VcValueType`] wrappers for foreign or generic types, such as
268/// [`Vec`] or [`Option`].
269///
270/// [repr-transparent]: https://doc.rust-lang.org/nomicon/other-reprs.html#reprtransparent
271///
272/// ## `local`
273///
274/// Skip the implementation of [`NonLocalValue`] for this type.
275///
276/// If not specified, we apply the [`#[derive(NonLocalValue)]`][macro@NonLocalValue] macro, which
277/// asserts that this struct has no fields containing [`Vc`] by implementing the [`NonLocalValue`]
278/// marker trait. Compile-time assertions are generated on every field, checking that they are also
279/// [`NonLocalValue`]s.
280#[rustfmt::skip]
281pub use turbo_tasks_macros::value;
282
283/// Attribute macro for declaring a [`TaskInput`] type. Emits:
284///
285/// - `unsafe impl NonLocalValue for X {}` (unless `contains_unresolved_vcs` is set).
286/// - `impl TaskInput for X` with a field-walking `is_transient`. By default `is_resolved` and
287///   `resolve_input` use the trait defaults (`true` and a [`CloneReady`] future — 8 bytes, no
288///   async-fn envelope); when `contains_unresolved_vcs` is set, both are emitted as
289///   field-walking implementations as well.
290///
291/// Default form (most types):
292///
293/// ```ignore
294/// #[turbo_tasks::task_input]
295/// #[derive(Clone, Debug, Hash, PartialEq, Eq, Encode, Decode)]
296/// pub struct MyTaskInput { ... }
297/// ```
298///
299/// Opt out of `NonLocalValue` when the type contains `Vc<T>` fields:
300///
301/// ```ignore
302/// #[turbo_tasks::task_input(contains_unresolved_vcs)]
303/// #[derive(Clone, Debug, Hash, PartialEq, Eq, Encode, Decode)]
304/// pub struct VcCarrier { vc: Vc<...> }
305/// ```
306pub use turbo_tasks_macros::task_input;
307
308/// Allows this trait to be used as part of a trait object inside of a value cell, in the form of
309/// `Vc<Box<dyn MyTrait>>`. The annotated trait is made into a subtrait of [`VcValueTrait`].
310///
311/// ```ignore
312/// #[turbo_tasks::value_trait]
313/// pub trait MyTrait {
314///
315///     #[turbo_tasks::function]
316///     fn method(self: Vc<Self>, a: i32) -> Vc<Something>;
317///
318///     // External signature: fn method(self: Vc<Self>, a: i32) -> Vc<Something>
319///     #[turbo_tasks::function]
320///     async fn method2(&self, a: i32) -> Result<Vc<Something>> {
321///         // Default implementation
322///     }
323///
324///     // A normal trait item, not a turbo-task
325///     fn normal(&self) -> SomethingElse;
326/// }
327///
328/// #[turbo_tasks::value_trait]
329/// pub trait OtherTrait: MyTrait + ValueToString {
330///     // ...
331/// }
332///
333/// #[turbo_tasks::value_impl]
334/// impl MyTrait for MyValue {
335///     // only the external signature must match (see the docs for #[turbo_tasks::function])
336///     #[turbo_tasks::function]
337///     fn method(&self, a: i32) -> Vc<Something> {
338///         todo!()
339///     }
340///
341///     fn normal(&self) -> SomethingElse {
342///         todo!()
343///     }
344/// }
345/// ```
346///
347/// The `#[turbo_tasks::value_trait]` annotation derives [`VcValueTrait`] and registers the trait
348/// and its methods.
349///
350/// All methods annotated with [`#[turbo_tasks::function]`][function] are cached, and
351/// the external signature rewriting rules defined on that macro are applied.
352///
353/// Default implementation are supported.
354///
355/// ## Arguments
356///
357/// Example: `#[turbo_tasks::value_trait(no_debug, operation)]`
358///
359/// ### `no_debug`
360///
361/// Disables the automatic implementation of [`ValueDebug`][debug::ValueDebug].
362///
363/// Example: `#[turbo_tasks::value_trait(no_debug)]`
364///
365/// ### `Operation`
366///
367/// Adds [`OperationValue`] as a supertrait of this trait.
368///
369/// Example: `#[turbo_tasks::value_trait(operation)]`
370#[rustfmt::skip]
371pub use turbo_tasks_macros::value_trait;
372
373/// A macro used on any `impl` block for a [`VcValueType`]. This can either be an inherent
374/// implementation or a trait implementation (see [`turbo_tasks::value_trait`][value_trait] and
375/// [`VcValueTrait`]).
376///
377/// Methods should be annotated with the [`#[turbo_tasks::function]`][function] macro.
378///
379/// ```ignore
380/// #[turbo_tasks::value_impl]
381/// impl MyTrait for MyValue {
382///     #[turbo_tasks::function]
383///     fn method(&self, a: i32) -> Vc<Something> {
384///         todo!()
385///     }
386/// }
387/// ```
388#[rustfmt::skip]
389pub use turbo_tasks_macros::value_impl;
390
391/// Derives the TaskStorage struct and generates optimized storage structures.
392///
393/// This macro analyzes `field` annotations and generates:
394/// 1. A unified TaskStorage struct
395/// 2. LazyField enum for lazy_vec fields
396/// 3. Typed accessor methods on TaskStorage
397/// 4. TaskStorageAccessors trait with accessor methods
398/// 5. TaskFlags bitfield for boolean flags
399///
400/// # Field Attributes
401///
402/// All fields require two attributes:
403///
404/// ## `storage = "..."` (required)
405///
406/// Specifies how the field is stored:
407/// - `direct` - Direct field access (e.g., `Option<OutputValue>`)
408/// - `auto_set` - Uses AutoSet for small collections
409/// - `auto_map` - Uses AutoMap for key-value pairs
410/// - `counter_map` - Uses CounterMap for reference counting
411/// - `flag` - Boolean flag stored in a compact TaskFlags bitfield (field type must be `bool`)
412///
413/// ## `category = "..."` (required)
414///
415/// Specifies the data category for persistence and access:
416/// - `data` - Frequently changed, bulk I/O
417/// - `meta` - Rarely changed, small I/O
418/// - `transient` - Field is not serialized (in-memory only)
419///
420/// ## Optional Modifiers
421///
422/// - `inline` - Field is stored inline on TaskStorage (default is lazy). Only use for hot-path
423///   fields that are frequently accessed.
424/// - `default` - Use `Default::default()` semantics instead of `Option` for inline direct fields.
425/// - `filter_transient` - Filter out transient values during serialization.
426/// - Serialization methods
427#[rustfmt::skip]
428pub use turbo_tasks_macros::task_storage;
429
430pub type TaskIdSet = AutoSet<TaskId, BuildHasherDefault<FxHasher>, 2>;
turbo_tasks/lib.rs

turbo_tasks/
lib.rs
