Commit 2bc712c0 authored by Tobias Koppers's avatar Tobias Koppers Committed by Tobias Koppers

docs(turbo-tasks-backend): add README and documentation comments

parent 62393b04
# turbo-tasks-backend
The execution and persistence backend for `turbo-tasks`, the incremental computation framework that powers Turbopack. It manages task scheduling, dependency tracking, invalidation propagation, and persistent caching of computation results.
## Architecture
The crate is organized in three layers:
```
TurboTasksBackend<B> Public API, implements the Backend trait
|
TurboTasksBackendInner<B> Core engine
- In-memory task storage (FxDashMap-based concurrent cache)
- Operation queue (resumable, snapshot-aware operations)
- Snapshot coordination (atomic pause/resume for persistence)
- Dependency tracking (output, cell, and collectible edges)
|
BackingStorage (trait) Pluggable persistence
|-- TurboKeyValueDatabase (turbo-persistence, recommended)
|-- LmdbKeyValueDatabase (LMDB, for debugging/reproduction)
+-- NoopKvDb (in-memory only, for tests)
```
## Task Storage
Each task's state is stored in a `TaskStorage` struct generated by the `#[task_storage]` macro from a schema definition. Fields are organized into three categories:
- **Meta** — Rarely-changed metadata (output value, aggregation number, upper nodes, flags). Persisted.
- **Data** — Frequently-changed bulk data (dependencies, cell contents, leaf distance). Persisted.
- **Transient** — Never serialized (execution state, in-progress cells, events). Memory-only.
Fields can be stored **inline** (always allocated, for hot-path access) or **lazily** (in a `Vec<LazyField>`, for memory efficiency). Boolean flags are packed into a `TaskFlags` bitfield.
## Operations
All graph mutations go through the operation system. Operations are enums that implement `Encode`/`Decode`, making them **resumable**: they can be serialized mid-execution at a suspension point and resumed after a snapshot or restart.
Key operations:
| Operation | Purpose |
|-----------|---------|
| `InvalidateOperation` | Marks tasks dirty, schedules recomputation |
| `UpdateCellOperation` | Updates cell content, invalidates dependents |
| `UpdateCollectibleOperation` | Tracks emitted collectible resources |
| `ConnectChildOperation` | Links a child task to a parent |
| `CleanupOldEdgesOperation` | Removes stale dependency edges after re-execution |
| `AggregationUpdateQueue` | Propagates dirty/clean state through the aggregation tree |
| `LeafDistanceUpdateQueue` | Recomputes scheduling priority distances |
Operations run inside an `ExecuteContext` that provides task locking, storage access, and suspension-point coordination.
## Aggregation Tree
Tasks form a hierarchical aggregation tree used for efficient dirty-state propagation:
- **Leaf nodes** (aggregation number 0..15): Tracked individually by their parent aggregation nodes.
- **Intermediate nodes** (16+): Aggregate dirty counts from their subgraph. Dirty/clean state propagates up through aggregated counters rather than touching every leaf.
- **Root nodes** (`u32::MAX`): Represent the top of the tree.
The aggregation number `{base, distance, effective}` determines a task's position. When a task becomes dirty, the change propagates upward through `aggregated_dirty_container_count` fields, stopping at aggregation boundaries. This avoids O(n) traversal of the entire graph.
## Persistence
Persistence uses **snapshot-based batch writes** rather than write-ahead logging:
1. The backend accumulates modifications in memory during normal operation.
2. When idle, a snapshot is requested: the high bit of `in_progress_operations` is set as a signal.
3. Active operations check `operation_suspend_point()` at safe points and pause.
4. Once all operations are suspended, modified task data is serialized and batch-written to the backing storage.
5. Operations resume after the snapshot completes.
This design minimizes I/O overhead compared to per-operation persistence. Tasks are lazily restored from disk on first access, reducing startup time and memory usage.
### Backing Storage Implementations
**TurboKeyValueDatabase** (default): Uses the `turbo-persistence` crate, a custom high-performance embedded database with adaptive compaction. Supports concurrent write batches and session-aware compaction strategies.
**LmdbKeyValueDatabase** (feature-gated): Uses LMDB (Lightning Memory-Mapped Database). Slower but proven stable — useful for reproducing user-reported bugs in isolation. Augmented with read transaction caching, startup pre-loading, and fresh-database optimizations.
**NoopKvDb**: In-memory only, no persistence. Used for testing.
## Task IDs
Task IDs are split into two ranges:
- `0..TRANSIENT_TASK_BIT` — **Persistent tasks**: Cached across process restarts.
- `TRANSIENT_TASK_BIT..u32::MAX` — **Transient tasks**: Root tasks and one-shot tasks that are never persisted. Filtered out during snapshot serialization.
## Feature Flags
Notable cargo features:
- `lmdb` — Enables the LMDB-based backing storage
- `verify_aggregation_graph` — Runtime verification of aggregation tree invariants
- `verify_determinism` — Detects non-deterministic task re-execution
- `trace_aggregation_update`, `trace_task_dirty`, `trace_find_and_schedule`, etc. — Feature-gated tracing spans for debugging specific subsystems
//! A reference-counting map used for tracking graph edges and collectible counts.
//!
//! [`CounterMap`] automatically removes entries when their count reaches zero, providing
//! memory-efficient storage for sparse counter data such as aggregation tree edges and
//! collectible reference counts.
use std::{
hash::{BuildHasherDefault, Hash},
ops::{Add, AddAssign, Sub},
......
//! Core backend engine for turbo-tasks.
//!
//! This module contains [`TurboTasksBackend`], the primary `Backend` trait implementation. It
//! manages the full lifecycle of tasks: scheduling, execution, dependency tracking, invalidation,
//! and snapshot-based persistence.
//!
//! The backend uses an atomic snapshot coordination protocol: the high bit of an
//! `in_progress_operations` counter signals snapshot requests, and operations pause at
//! suspension points to allow batch persistence writes.
mod counter_map;
mod operation;
mod storage;
......@@ -112,6 +122,7 @@ impl SnapshotRequest {
}
}
/// Controls how the backend interacts with the persistent backing storage.
pub enum StorageMode {
/// Queries the storage for cache entries that don't exist locally.
ReadOnly,
......@@ -123,6 +134,7 @@ pub enum StorageMode {
ReadWriteOnShutdown,
}
/// Configuration options for [`TurboTasksBackend`].
pub struct BackendOptions {
/// Enables dependency tracking.
///
......@@ -160,11 +172,18 @@ impl Default for BackendOptions {
}
}
/// Background jobs scheduled by the backend for snapshot persistence.
pub enum TurboTasksBackendJob {
InitialSnapshot,
FollowUpSnapshot,
}
/// The primary backend implementation for turbo-tasks.
///
/// Generic over a [`BackingStorage`] implementation that provides persistent caching.
/// Create one using [`TurboTasksBackend::new`] with [`BackendOptions`] and a backing storage
/// instance from [`crate::turbo_backing_storage`], [`crate::lmdb_backing_storage`], or
/// [`crate::noop_backing_storage`].
pub struct TurboTasksBackend<B: BackingStorage>(Arc<TurboTasksBackendInner<B>>);
type TaskCacheLog = Sharded<ChunkedVec<(Arc<CachedTaskType>, TaskId)>>;
......
//! Aggregation tree update algorithm.
//!
//! Tasks form a hierarchical aggregation tree where dirty/clean state and collectible counts
//! propagate upward through aggregated counters. This module implements the incremental update
//! algorithm that maintains these aggregated values as the task graph changes.
//!
//! The aggregation number determines a node's role:
//! - Leaf nodes (`< LEAF_NUMBER`): Tracked individually by parent aggregation nodes.
//! - Aggregating nodes (`>= LEAF_NUMBER`): Aggregate dirty counts from their subgraph.
//! - Root nodes (`u32::MAX`): Represent the top of the aggregation tree.
//!
//! Updates are processed through an [`AggregationUpdateQueue`] that batches and deduplicates
//! jobs for efficient graph traversal.
use std::{
cmp::max,
collections::{VecDeque, hash_map::Entry as HashMapEntry},
......@@ -89,6 +103,7 @@ pub fn get_aggregation_number(task: &impl TaskGuard) -> u32 {
.unwrap_or_default()
}
/// Input for computing how a task's dirty/clean state change affects aggregated counters.
#[derive(Debug)]
pub struct ComputeDirtyAndCleanUpdate {
pub old_dirty_container_count: i32,
......@@ -101,6 +116,7 @@ pub struct ComputeDirtyAndCleanUpdate {
pub new_current_session_self_clean: bool,
}
/// The computed delta to propagate upward through the aggregation tree.
pub struct ComputeDirtyAndCleanUpdateResult {
pub dirty_count_update: i32,
pub current_session_clean_update: i32,
......@@ -162,6 +178,7 @@ impl ComputeDirtyAndCleanUpdateResult {
}
}
/// Job: notify upper nodes that an inner node has gained new followers.
#[derive(Encode, Decode, Clone, Debug)]
pub struct InnerOfUppersHasNewFollowersJob {
#[bincode(with = "turbo_bincode::smallvec")]
......@@ -176,6 +193,7 @@ impl From<InnerOfUppersHasNewFollowersJob> for AggregationUpdateJob {
}
}
/// Job: notify upper nodes that an inner node has lost followers.
#[derive(Encode, Decode, Clone, Debug)]
pub struct InnerOfUppersLostFollowersJob {
#[bincode(with = "turbo_bincode::smallvec")]
......@@ -190,6 +208,7 @@ impl From<InnerOfUppersLostFollowersJob> for AggregationUpdateJob {
}
}
/// Job: propagate an aggregated data update to the given upper nodes.
#[derive(Encode, Decode, Clone, Debug)]
pub struct AggregatedDataUpdateJob {
pub upper_ids: TaskIdVec,
......@@ -317,6 +336,10 @@ impl AggregationUpdateJob {
}
}
/// A value that is session-dependent: it is not serialized across restarts.
///
/// On deserialization, the value is reset to `T::default()`. This is used for counters
/// that track per-session state (e.g., "clean in current session" counts).
#[derive(Default, Encode, Decode, Clone, Copy, Debug)]
#[bincode(decode_bounds = "T: Default", borrow_decode_bounds = "T: Default")]
pub struct SessionDependent<T> {
......
//! Removal of stale dependency edges after task re-execution.
//!
//! When a task is re-executed, its new set of dependencies may differ from the old set.
//! [`CleanupOldEdgesOperation`] removes outdated output dependencies, cell dependencies,
//! collectible dependencies, and child edges, updating the aggregation tree accordingly.
use std::mem::take;
use bincode::{Decode, Encode};
......@@ -20,6 +26,9 @@ use crate::{
data::{CellRef, CollectibleRef, CollectiblesRef},
};
/// Resumable operation that removes stale edges from a task after re-execution.
///
/// Progress states: `RemoveEdges` -> `AggregationUpdate` -> `Done`.
#[derive(Encode, Decode, Clone, Default)]
pub enum CleanupOldEdgesOperation {
RemoveEdges {
......
//! Connecting a single child task to a parent in the task graph.
//!
//! [`ConnectChildOperation`] establishes a parent-child relationship between tasks,
//! updating the aggregation tree to incorporate the child's data into the parent's
//! aggregated state.
use std::sync::Arc;
use bincode::{Decode, Encode};
......@@ -16,6 +22,9 @@ use crate::{
utils::arc_or_owned::ArcOrOwned,
};
/// Resumable operation that connects a child task to a parent.
///
/// Progress states: `UpdateAggregation` -> `Done`.
#[derive(Encode, Decode, Clone, Default)]
#[allow(clippy::large_enum_variant)]
pub enum ConnectChildOperation {
......
//! Batch connecting multiple children to a parent task.
//!
//! [`connect_children`] adds a set of new child tasks to a parent, updating the aggregation
//! tree in bulk. For large batches, work is parallelized across worker threads.
use rustc_hash::FxHashSet;
use smallvec::SmallVec;
use turbo_tasks::{
......@@ -12,6 +17,7 @@ use crate::backend::operation::{
get_uppers, is_aggregating_node,
};
/// Connects a set of new children to a parent task, updating the aggregation tree in bulk.
pub fn connect_children(
ctx: &mut impl ExecuteContext<'_>,
parent_task_id: TaskId,
......
//! Task invalidation and dirty propagation.
//!
//! [`InvalidateOperation`] marks tasks as dirty and schedules them for re-execution.
//! After marking tasks dirty, it triggers aggregation updates to propagate the dirty
//! state through the aggregation tree to upper nodes.
use bincode::{Decode, Encode};
use smallvec::SmallVec;
use turbo_tasks::{TaskExecutionReason, TaskId, event::EventDescription};
......@@ -15,6 +21,9 @@ use crate::{
data::{Dirtyness, InProgressState, InProgressStateInner},
};
/// Resumable operation that marks tasks dirty and propagates the change through aggregation.
///
/// Progress states: `MakeDirty` -> `AggregationUpdate` -> `Done`.
#[derive(Encode, Decode, Clone, Default)]
#[allow(clippy::large_enum_variant)]
pub enum InvalidateOperation {
......
//! Leaf distance recomputation for task scheduling priority.
//!
//! The leaf distance is a monotonically increasing metric representing how far a task is from
//! leaf nodes in the dependency graph. Tasks closer to leaves are prioritized for scheduling.
//! Updates use a buffer zone to avoid frequent propagation of small distance changes.
use std::{
cmp::Reverse,
collections::{BinaryHeap, hash_map::Entry},
......
//! Resumable task graph operations.
//!
//! All mutations to the task graph go through operations defined in this module. Operations
//! implement [`Encode`]/[`Decode`] so they can be serialized mid-execution at snapshot suspension
//! points and resumed after a restart. Each operation is an enum whose variants represent
//! progress states (e.g., `MakeDirty` -> `AggregationUpdate` -> `Done`).
//!
//! The [`ExecuteContext`] trait provides task locking, storage access, and suspension-point
//! coordination. [`TaskGuard`] provides safe access to a single task's storage fields.
mod aggregation_update;
mod cleanup_old_edges;
mod connect_child;
......@@ -29,10 +39,18 @@ use crate::{
data::{ActivenessState, CollectibleRef, Dirtyness, InProgressState, TransientTask},
};
/// A resumable, serializable task graph operation.
///
/// Operations encode their progress state via `Encode`/`Decode`, allowing them to be
/// suspended at snapshot boundaries and resumed later (or after a restart).
pub trait Operation: Encode + Decode<()> + Default + TryFrom<AnyOperation, Error = ()> {
fn execute(self, ctx: &mut impl ExecuteContext<'_>);
}
/// Execution environment for operations.
///
/// Provides task locking, batch prefetching from backing storage, scheduling, and
/// snapshot suspension points. Operations interact with task data exclusively through this trait.
pub trait ExecuteContext<'e>: Sized {
type TaskGuardImpl: TaskGuard + 'e;
fn child_context<'l, 'r>(&'r self) -> impl ChildExecuteContext<'l> + use<'e, 'l, Self>
......@@ -94,6 +112,7 @@ pub trait ExecuteContext<'e>: Sized {
fn task_by_type(&mut self, task_type: &CachedTaskType) -> Option<TaskId>;
}
/// A lightweight context factory for creating child [`ExecuteContext`]s on worker threads.
pub trait ChildExecuteContext<'e>: Send + Sized {
fn create(self) -> impl ExecuteContext<'e>;
}
......@@ -151,6 +170,10 @@ impl TaskLockCounter {
}
}
/// Concrete [`ExecuteContext`] implementation backed by [`TurboTasksBackendInner`].
///
/// Manages a read transaction for lazy restoration from backing storage, and holds an
/// operation guard that participates in snapshot coordination.
pub struct ExecuteContextImpl<'e, B: BackingStorage> {
backend: &'e TurboTasksBackendInner<B>,
turbo_tasks: &'e dyn TurboTasksBackendApi<TurboTasksBackend<B>>,
......@@ -647,6 +670,7 @@ impl<'e, B: BackingStorage> ChildExecuteContext<'e> for ChildExecuteContextImpl<
}
}
/// Borrowed reference to a task's type (cached function or transient root/once task).
pub enum TaskTypeRef<'l> {
Cached(&'l Arc<CachedTaskType>),
Transient(&'l Arc<TransientTask>),
......@@ -670,6 +694,7 @@ impl Display for TaskTypeRef<'_> {
}
}
/// Owned variant of [`TaskTypeRef`].
pub enum TaskType {
Cached(Arc<CachedTaskType>),
Transient(Arc<TransientTask>),
......@@ -684,6 +709,10 @@ impl Display for TaskType {
}
}
/// Safe access to a single task's storage fields within an operation.
///
/// Provides methods for reading and writing task state (activeness, in-progress status,
/// scheduling) while holding the appropriate storage lock.
pub trait TaskGuard: Debug + TaskStorageAccessors {
fn id(&self) -> TaskId;
......@@ -910,6 +939,7 @@ pub trait TaskGuard: Debug + TaskStorageAccessors {
}
}
/// Concrete [`TaskGuard`] implementation holding a [`StorageWriteGuard`].
pub struct TaskGuardImpl<'a> {
task_id: TaskId,
task: StorageWriteGuard<'a>,
......@@ -1066,6 +1096,11 @@ macro_rules! impl_operation {
};
}
/// Type-erased operation enum encompassing all operation types.
///
/// Used for serializing in-progress operations during snapshots and restoring them on startup.
/// Operations that were interrupted mid-execution are stored as `AnyOperation` in the backing
/// storage and replayed on the next session.
#[derive(Encode, Decode, Clone)]
pub enum AnyOperation {
ConnectChild(connect_child::ConnectChildOperation),
......
//! Preparation of aggregation numbers before connecting new children.
//!
//! [`prepare_new_children`] adjusts the parent's aggregation number based on the number of
//! children being added, ensuring the aggregation tree remains balanced. It also enqueues
//! aggregation number updates for children that need adjustment.
use std::{cmp::max, num::NonZeroU32};
use rustc_hash::FxHashSet;
......@@ -9,6 +15,7 @@ use crate::backend::operation::{
const AGGREGATION_NUMBER_BUFFER_SPACE: u32 = 3;
/// Adjusts the parent's aggregation number for the incoming children and enqueues updates.
pub fn prepare_new_children(
parent_task_id: TaskId,
parent_task: &mut impl TaskGuard,
......
//! Cell content updates and dependent invalidation.
//!
//! [`UpdateCellOperation`] handles writing new content to a task's cell, comparing the new
//! value against the old one, and invalidating dependent tasks when the content has changed.
use std::mem::take;
use bincode::{Decode, Encode};
......@@ -23,6 +28,7 @@ use crate::{
data::CellRef,
};
/// Resumable operation that updates a cell's content and invalidates dependents.
#[derive(Encode, Decode, Clone, Default)]
#[allow(clippy::large_enum_variant)]
pub enum UpdateCellOperation {
......
//! Collectible resource tracking updates.
//!
//! [`UpdateCollectibleOperation`] updates the reference count of a collectible resource
//! emitted by a task and propagates the change through the aggregation tree so that
//! collectible readers can observe the updated counts.
use std::cmp::min;
use smallvec::SmallVec;
......@@ -15,6 +21,7 @@ use crate::{
data::CollectibleRef,
};
/// Updates a collectible's reference count on a task and propagates through aggregation.
pub struct UpdateCollectibleOperation;
impl UpdateCollectibleOperation {
......
//! In-memory task storage with snapshot support.
//!
//! [`Storage`] is a concurrent map from [`TaskId`] to [`TaskStorage`] that supports atomic
//! snapshots for persistence. During normal operation, mutations are tracked via modified flags.
//! When a snapshot is requested, accessed items create copy-on-write snapshots so the persistence
//! layer can serialize a consistent view while mutations continue.
use std::{
cell::Cell,
hash::Hash,
......@@ -20,6 +27,9 @@ use crate::{
},
};
/// Selects which categories of task data to load or operate on.
///
/// `Meta` and `Data` correspond to the two persistent storage categories. `All` loads both.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum TaskDataCategory {
Meta,
......@@ -45,6 +55,7 @@ impl TaskDataCategory {
}
}
/// A non-composite task data category (either `Meta` or `Data`, but not `All`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum SpecificTaskDataCategory {
Meta,
......@@ -76,6 +87,10 @@ enum ModifiedState {
Snapshot(Option<Box<TaskStorage>>),
}
/// Concurrent in-memory store for task data with copy-on-write snapshot support.
///
/// Uses sharded `FxDashMap` for lock-free concurrent reads and fine-grained write locking.
/// Tracks which tasks have been modified since the last snapshot via a separate `modified` map.
pub struct Storage {
snapshot_mode: AtomicBool,
modified: FxDashMap<TaskId, ModifiedState>,
......@@ -289,6 +304,9 @@ impl Storage {
}
}
/// A write guard for a single task's storage entry.
///
/// Tracks modifications for snapshot persistence. Derefs to [`TaskStorage`] for direct access.
pub struct StorageWriteGuard<'a> {
storage: &'a Storage,
inner: RefMut<'a, TaskId, Box<TaskStorage>>,
......@@ -455,6 +473,10 @@ impl Drop for SnapshotGuard<'_> {
}
}
/// An iterator over modified tasks in a single shard during snapshot processing.
///
/// Yields serialized task data for each modified task. Holds a reference to the snapshot guard
/// to keep snapshot mode active until all shards have been processed.
pub struct SnapshotShard<'l, P> {
direct_snapshots: Vec<(TaskId, Box<TaskStorage>)>,
modified: SmallVec<[TaskId; 4]>,
......
//! Core data types for task state representation.
//!
//! This module defines the fundamental types used to represent task state in the backend:
//! cell references, collectible references, output values, task execution state, and
//! aggregation metadata. Types are either persistent (serializable via `Encode`/`Decode`)
//! or transient (memory-only, using the `transient_traits!` macro for placeholder impls).
use std::{
fmt::{self, Debug, Display},
pin::Pin,
......@@ -38,6 +45,7 @@ macro_rules! transient_traits {
};
}
/// A reference to a specific cell within a task.
#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq, Encode, Decode)]
pub struct CellRef {
pub task: TaskId,
......@@ -51,6 +59,7 @@ impl CellRef {
}
}
/// A reference to a collectible resource (a typed cell emitted by a task).
#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq, Encode, Decode)]
pub struct CollectibleRef {
pub collectible_type: TraitTypeId,
......@@ -64,6 +73,7 @@ impl CollectibleRef {
}
}
/// A reference to all collectibles of a specific trait type within a task's subgraph.
#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq, Encode, Decode)]
pub struct CollectiblesRef {
pub task: TaskId,
......@@ -77,6 +87,7 @@ impl CollectiblesRef {
}
}
/// The result of a task execution: a cell reference, a forwarded output, or an error.
#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
pub enum OutputValue {
Cell(CellRef),
......@@ -98,6 +109,10 @@ impl OutputValue {
}
}
/// Tracks whether a task's subgraph is "active" (i.e., should be kept up-to-date).
///
/// A task is active when any of: it is a root/once task, its `active_counter` is positive
/// (incremented by dependents), or `active_until_clean` is set (caching activeness while dirty).
#[derive(Debug)]
pub struct ActivenessState {
/// When this counter is > 0, the task is active.
......@@ -212,12 +227,18 @@ impl Display for TransientTask {
transient_traits!(TransientTask);
/// Whether a task needs re-execution.
///
/// `Dirty(priority)` means the task is unconditionally dirty and should be scheduled.
/// `SessionDependent` means the task was clean in a previous session but may be dirty in
/// the current one (needs evaluation at scheduling time).
#[derive(Debug, Clone, Copy, Encode, Decode, PartialEq, Eq)]
pub enum Dirtyness {
Dirty(TaskPriority),
SessionDependent,
}
/// The type of root task that makes a task unconditionally active.
#[derive(Debug, Clone, Copy)]
pub enum RootType {
RootTask,
......@@ -233,6 +254,7 @@ impl Display for RootType {
}
}
/// Detailed state for a task that is currently executing.
#[derive(Debug)]
pub struct InProgressStateInner {
pub stale: bool,
......@@ -250,6 +272,7 @@ pub struct InProgressStateInner {
pub new_children: FxHashSet<TaskId>,
}
/// The execution lifecycle state of a task.
#[derive(Debug)]
pub enum InProgressState {
Scheduled {
......@@ -265,6 +288,8 @@ pub enum InProgressState {
transient_traits!(InProgressState);
/// State for a cell that is being computed. Holds an event to notify readers when the cell
/// content becomes available.
#[derive(Debug)]
pub struct InProgressCellState {
pub event: Event,
......@@ -282,6 +307,10 @@ impl InProgressCellState {
}
}
/// A task's position in the aggregation tree hierarchy.
///
/// `base` is set explicitly (e.g., root tasks get `u32::MAX`). `distance` is computed from
/// the number of children. `effective = max(base, distance)` determines the actual behavior.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Encode, Decode)]
pub struct AggregationNumber {
pub base: u32,
......
//! Abstract key-value database trait.
//!
//! [`KeyValueDatabase`] defines the interface for low-level storage backends. Implementations
//! must support read transactions, key-space-scoped reads, and write batches (serial or
//! concurrent). The trait is used by
//! [`KeyValueDatabaseBackingStorage`](crate::KeyValueDatabaseBackingStorage) to bridge to the
//! [`BackingStorage`](crate::BackingStorage) trait.
use anyhow::Result;
use smallvec::SmallVec;
use turbo_persistence::{FamilyConfig, FamilyKind};
use crate::database::write_batch::ConcurrentWriteBatch;
/// Logical key namespaces within the database, stored as separate families/tables.
#[derive(Debug, Clone, Copy)]
pub enum KeySpace {
Infra = 0,
......@@ -26,6 +35,10 @@ impl KeySpace {
}
}
/// A low-level key-value database supporting transactional reads and batched writes.
///
/// Implementations provide the storage layer for [`BackingStorage`](crate::BackingStorage).
/// The database operates on four [`KeySpace`]s (Infra, TaskMeta, TaskData, TaskCache).
pub trait KeyValueDatabase {
fn is_empty(&self) -> bool {
false
......
//! Database layer providing pluggable key-value storage backends.
//!
//! This module defines the [`KeyValueDatabase`](key_value_database::KeyValueDatabase) trait
//! and provides concrete implementations:
//! - [`turbo`] — High-performance backend using `turbo-persistence` (default)
//! - [`lmdb`] — LMDB backend for debugging/reproduction (feature-gated)
//! - [`noop_kv`] — No-op in-memory backend for tests
//!
//! Supporting modules handle database versioning, cache invalidation, startup caching,
//! and write batch abstractions.
pub mod db_invalidation;
pub mod db_versioning;
pub mod key_value_database;
......
//! [`KeyValueDatabase`] implementation backed by `turbo-persistence`.
//!
//! [`TurboKeyValueDatabase`] is the default high-performance storage backend. It uses the
//! `turbo_persistence` crate, a custom embedded database optimized for the turbo-tasks
//! workload of large batch writes followed by random reads. Supports adaptive compaction:
//! short sessions skip compaction, CI runs perform full compaction for smaller disk footprint.
use std::{
cmp::max,
path::PathBuf,
......@@ -40,6 +47,10 @@ const COMPACT_CONFIG: CompactConfig = CompactConfig {
max_merge_segment_count: 16,
};
/// High-performance [`KeyValueDatabase`] backed by `turbo_persistence::TurboPersistence`.
///
/// Supports concurrent write batches and background compaction. The compaction strategy adapts
/// to usage: short sessions and CI have different compaction behaviors.
pub struct TurboKeyValueDatabase {
db: Arc<TurboPersistence<TurboTasksParallelScheduler, FAMILIES>>,
is_ci: bool,
......
//! Write batch abstractions for key-value database operations.
//!
//! Provides [`ConcurrentWriteBatch`] for thread-safe batched writes to the key-value database.
//! This allows database implementations to support concurrent writes from multiple threads
//! while presenting a consistent interface to the backing storage layer.
use std::{borrow::Cow, ops::Deref};
use anyhow::Result;
......@@ -5,6 +11,7 @@ use smallvec::SmallVec;
use crate::database::key_value_database::KeySpace;
/// A buffer for write batch keys/values, supporting borrowed, heap-allocated, and inline storage.
pub enum WriteBuffer<'a> {
Borrowed(&'a [u8]),
Vec(Vec<u8>),
......@@ -42,6 +49,7 @@ impl<'l> From<Cow<'l, [u8]>> for WriteBuffer<'l> {
}
}
/// A thread-safe write batch that allows concurrent `&self` writes from multiple threads.
pub trait ConcurrentWriteBatch<'a>: Sync + Send {
type ValueBuffer<'l>: std::borrow::Borrow<[u8]>
where
......
//! [`BackingStorage`] implementation backed by a [`KeyValueDatabase`].
//!
//! [`KeyValueDatabaseBackingStorage`] wraps any [`KeyValueDatabase`] implementation into the
//! [`BackingStorage`] trait expected by [`TurboTasksBackend`](crate::TurboTasksBackend).
//! It handles versioned on-disk storage, cache invalidation, panic hook registration,
//! and serialization of task data and operations into key-value pairs.
use std::{
borrow::Borrow,
env,
......@@ -71,6 +78,8 @@ fn should_invalidate_on_panic() -> bool {
*SHOULD_INVALIDATE
}
/// Inner state for [`KeyValueDatabaseBackingStorage`], wrapped in an `Arc` so that the panic
/// hook can hold a `Weak` reference without creating a reference cycle.
pub struct KeyValueDatabaseBackingStorageInner<T: KeyValueDatabase> {
database: T,
/// Used when calling [`BackingStorage::invalidate`]. Can be `None` in the memory-only/no-op
......@@ -83,6 +92,10 @@ pub struct KeyValueDatabaseBackingStorageInner<T: KeyValueDatabase> {
_panic_hook_guard: Option<PanicHookGuard>,
}
/// A [`BackingStorage`] implementation that delegates to a [`KeyValueDatabase`].
///
/// Handles serialization of task data, versioned on-disk directories, cache invalidation on
/// panic, and batch snapshot writes.
pub struct KeyValueDatabaseBackingStorage<T: KeyValueDatabase> {
// wrapped so that `register_panic_hook` can hold a weak reference to `inner`.
inner: Arc<KeyValueDatabaseBackingStorageInner<T>>,
......
//! The execution and persistence backend for `turbo-tasks`.
//!
//! This crate provides [`TurboTasksBackend`], the primary implementation of the `Backend` trait
//! from `turbo-tasks`. It manages task scheduling, dependency tracking, invalidation propagation,
//! and persistent caching of computation results for Turbopack's incremental computation framework.
//!
//! # Getting started
//!
//! Create a backend by combining [`BackendOptions`] with a [`BackingStorage`] implementation:
//!
//! - [`turbo_backing_storage`] — High-performance storage using `turbo-persistence` (recommended)
//! - [`lmdb_backing_storage`] — LMDB-based storage for debugging (requires `lmdb` feature)
//! - [`noop_backing_storage`] — In-memory only, no persistence (for tests)
//! - [`default_backing_storage`] — Picks the best available implementation
//!
//! # Architecture
//!
//! The backend uses snapshot-based persistence: modifications accumulate in memory during normal
//! operation, then are batch-written to disk when the system is idle. Operations are resumable
//! (serializable as enums) and can suspend at safe points during snapshots.
//!
//! Tasks form an aggregation tree for efficient dirty-state propagation. Each task's state is
//! stored in a generated `TaskStorage` struct with fields organized into meta (persisted, rarely
//! changed), data (persisted, frequently changed), and transient (memory-only) categories.
#![feature(anonymous_lifetime_in_impl_trait)]
#![feature(associated_type_defaults)]
#![feature(iter_collect_into)]
......
......@@ -7,6 +7,8 @@ use bincode::{
impl_borrow_decode_with_context,
};
/// Either an `Arc<T>` or an owned `T`, avoiding unnecessary indirection when ownership
/// is already available.
#[derive(Clone)]
pub enum ArcOrOwned<T> {
Arc(Arc<T>),
......
/// A growable vector organized into geometrically-sized chunks to avoid large reallocations.
///
/// Each chunk doubles in size, so appending N items requires O(log N) allocations total.
/// Iteration yields items across all chunks in order.
pub struct ChunkedVec<T> {
chunks: Vec<Vec<T>>,
}
......
//! Utility data structures and helpers used throughout the backend.
pub mod arc_or_owned;
pub mod chunked_vec;
pub mod dash_map_drop_contents;
......
......@@ -4,6 +4,9 @@ use std::{
sync::Arc,
};
/// An `Arc<T>` wrapper that uses pointer equality for `Eq`/`Hash` instead of value equality.
///
/// Useful for identity-based deduplication (e.g., tracking in-progress operations by pointer).
pub struct PtrEqArc<T>(Arc<T>);
impl<T> PtrEqArc<T> {
......
......@@ -3,6 +3,8 @@ use std::hash::{BuildHasher, BuildHasherDefault, Hash};
use parking_lot::{Mutex, MutexGuard};
use rustc_hash::FxHasher;
/// A sharded data structure that distributes items across multiple mutex-protected slots
/// to reduce lock contention in concurrent access patterns.
pub struct Sharded<T, H = BuildHasherDefault<FxHasher>> {
data: Box<[Mutex<T>]>,
hasher: H,
......
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