eviction

Author: lukesandberg

crates/next-napi-bindings/src/next_api/turbopack_ctx.rs

@@ -249,6 +249,7 @@ pub fn create_turbo_tasks(
                 }),
                 dependency_tracking,
                 num_workers: Some(tokio::runtime::Handle::current().metrics().num_workers()),
+                evict_after_snapshot: std::env::var("TURBO_ENGINE_EVICT_AFTER_SNAPSHOT").is_ok(),
                 ..Default::default()
             },
             Either::Left(backing_storage),

test/e2e/filesystem-cache/evict-after-snapshot.test.ts

@@ -0,0 +1,89 @@
+import { nextTestSetup } from 'e2e-utils'
+import { retry, waitFor } from 'next-test-utils'
+
+describe('evict-after-snapshot', () => {
+  const envVars = [
+    'ENABLE_CACHING=1',
+    'TURBO_ENGINE_IGNORE_DIRTY=1',
+    'TURBO_ENGINE_SNAPSHOT_IDLE_TIMEOUT_MILLIS=1000',
+    'TURBO_ENGINE_EVICT_AFTER_SNAPSHOT=1',
+  ].join(' ')
+
+  const { skipped, next } = nextTestSetup({
+    files: __dirname,
+    skipDeployment: true,
+    patchFileDelay: 500,
+    packageJson: {
+      scripts: {
+        dev: `${envVars} next dev`,
+      },
+    },
+    installCommand: 'npm i',
+    startCommand: 'npm run dev',
+  })
+
+  if (skipped) {
+    return
+  }
+
+  async function waitForSnapshotAndEviction() {
+    // The idle timeout is 1s, give extra time for snapshot + eviction to complete
+    await waitFor(5000)
+  }
+
+  // Turbopack-only: eviction requires persistent caching
+  ;(process.env.IS_TURBOPACK_TEST ? it : it.skip)(
+    'should serve correct content after eviction and HMR',
+    async () => {
+      const browser = await next.browser('/')
+      await retry(async () => {
+        expect(await browser.elementByCss('p').text()).toBe('hello world')
+      })
+
+      for (let cycle = 1; cycle <= 3; cycle++) {
+        await waitForSnapshotAndEviction()
+
+        await next.patchFile(
+          'app/page.tsx',
+          (content) => content.replace('hello world', `cycle ${cycle}`),
+          async () => {
+            await retry(async () => {
+              expect(await browser.elementByCss('p').text()).toBe(
+                `cycle ${cycle}`
+              )
+            }, 10000)
+          }
+        )
+      }
+
+      await browser.close()
+    },
+    90000
+  )
+  ;(process.env.IS_TURBOPACK_TEST ? it : it.skip)(
+    'should handle client component HMR after eviction',
+    async () => {
+      const browser = await next.browser('/client')
+      await retry(async () => {
+        expect(await browser.elementByCss('p').text()).toBe('hello world')
+      })
+
+      await waitForSnapshotAndEviction()
+
+      await next.patchFile(
+        'app/client/page.tsx',
+        (content) => content.replace('hello world', 'hello eviction'),
+        async () => {
+          await retry(async () => {
+            expect(await browser.elementByCss('p').text()).toBe(
+              'hello eviction'
+            )
+          }, 10000)
+        }
+      )
+
+      await browser.close()
+    },
+    90000
+  )
+})

turbopack/crates/turbo-tasks-backend/src/backend/mod.rs

@@ -47,7 +47,7 @@ use turbo_tasks::{
 
 pub use self::{
     operation::AnyOperation,
-    storage::{SpecificTaskDataCategory, TaskDataCategory},
+    storage::{EvictionCounts, SpecificTaskDataCategory, TaskDataCategory},
 };
 #[cfg(feature = "trace_task_dirty")]
 use crate::backend::operation::TaskDirtyCause;
@@ -86,13 +86,13 @@ const DEPENDENT_TASKS_DIRTY_PARALLIZATION_THRESHOLD: usize = 10000;
 const SNAPSHOT_REQUESTED_BIT: usize = 1 << (usize::BITS - 1);
 
 /// Configurable idle timeout for snapshot persistence.
-/// Defaults to 2 seconds if not set or if the value is invalid.
+/// Defaults to 10 seconds if not set or if the value is invalid.
 static IDLE_TIMEOUT: LazyLock<Duration> = LazyLock::new(|| {
     std::env::var("TURBO_ENGINE_SNAPSHOT_IDLE_TIMEOUT_MILLIS")
         .ok()
         .and_then(|v| v.parse::<u64>().ok())
         .map(Duration::from_millis)
-        .unwrap_or(Duration::from_secs(2))
+        .unwrap_or(Duration::from_secs(10))
 });
 
 struct SnapshotRequest {
@@ -143,6 +143,11 @@ pub struct BackendOptions {
 
     /// Avoid big preallocations for faster startup. Should only be used for testing purposes.
     pub small_preallocation: bool,
+
+    /// When enabled, evict all evictable tasks from in-memory storage after every snapshot.
+    /// This reclaims memory by clearing persisted data that can be re-loaded from disk on demand.
+    /// This is an EXPERIMENTAL FEATURE under development
+    pub evict_after_snapshot: bool,
 }
 
 impl Default for BackendOptions {
@@ -153,6 +158,7 @@ impl Default for BackendOptions {
             storage_mode: Some(StorageMode::ReadWrite),
             num_workers: None,
             small_preallocation: false,
+            evict_after_snapshot: false,
         }
     }
 }
@@ -220,6 +226,19 @@ impl<B: BackingStorage> TurboTasksBackend<B> {
     pub fn backing_storage(&self) -> &B {
         &self.0.backing_storage
     }
+
+    /// Perform a snapshot and then evict all evictable tasks from memory.
+    ///
+    /// This is exposed for integration tests that need to verify the
+    /// snapshot → evict → restore cycle works correctly.
+    ///
+    /// Returns `(snapshot_had_new_data, eviction_counts)`.
+    pub fn snapshot_and_evict(
+        &self,
+        turbo_tasks: &dyn TurboTasksBackendApi<TurboTasksBackend<B>>,
+    ) -> (bool, EvictionCounts) {
+        self.0.snapshot_and_evict(turbo_tasks)
+    }
 }
 
 impl<B: BackingStorage> TurboTasksBackendInner<B> {
@@ -339,6 +358,38 @@ impl<B: BackingStorage> TurboTasksBackendInner<B> {
         )
     }
 
+    fn should_evict(&self) -> bool {
+        self.options.evict_after_snapshot && self.should_persist()
+    }
+
+    /// Perform a snapshot and then evict all evictable tasks from memory.
+    ///
+    /// This is exposed for integration tests that need to verify the
+    /// snapshot → evict → restore cycle works correctly.
+    ///
+    /// Returns `(snapshot_had_new_data, eviction_counts)`.
+    pub fn snapshot_and_evict(
+        &self,
+        turbo_tasks: &dyn TurboTasksBackendApi<TurboTasksBackend<B>>,
+    ) -> (bool, EvictionCounts) {
+        assert!(
+            self.should_persist(),
+            "snapshot_and_evict requires persistence"
+        );
+        let snapshot_result = self.snapshot_and_persist(None, "test", turbo_tasks);
+        let had_new_data = match snapshot_result {
+            Some((_, new_data)) => new_data,
+            None => {
+                // Snapshot/persist failed — skip eviction since the data may not
+                // be on disk yet. Evicting now could lose in-memory state that
+                // can't be restored.
+                return (false, EvictionCounts::default());
+            }
+        };
+        let counts = self.storage.evict_after_snapshot();
+        (had_new_data, counts)
+    }
+
     fn should_restore(&self) -> bool {
         self.options.storage_mode.is_some()
     }
@@ -2775,6 +2826,8 @@ impl<B: BackingStorage> TurboTasksBackendInner<B> {
                     let mut last_snapshot = self.start_time + Duration::from_millis(last_snapshot);
                     let mut idle_start_listener = self.idle_start_event.listen();
                     let mut idle_end_listener = self.idle_end_event.listen();
+                    // Whether to immediately set an idle timeout if possible
+                    // set to false if we don't persist anything in a cycle.
                     let mut fresh_idle = true;
                     loop {
                         const FIRST_SNAPSHOT_WAIT: Duration = Duration::from_secs(300);
@@ -2809,7 +2862,7 @@ impl<B: BackingStorage> TurboTasksBackendInner<B> {
                                         idle_start_listener = self.idle_start_event.listen()
                                     },
                                     _ = &mut idle_end_listener => {
-                                        idle_time = until + idle_timeout;
+                                        idle_time = far_future();
                                         idle_end_listener = self.idle_end_event.listen()
                                     },
                                     _ = tokio::time::sleep_until(until) => {
@@ -2836,6 +2889,41 @@ impl<B: BackingStorage> TurboTasksBackendInner<B> {
                         if let Some((snapshot_start, new_data)) = snapshot {
                             last_snapshot = snapshot_start;
 
+                            // Evict persisted tasks from memory to reclaim space.
+                            // Like compaction, this runs after snapshot_and_persist
+                            // as a separate concern.
+
+                            // TODO: should we only run if we stored new data? syncing data to disk
+                            // implies that some of it is eligible for eviction, but if nothing was
+                            // stored then that isn't true.   on the other hand pre-fetching might
+                            // bring unused data into the heap.
+                            if this.should_evict() && new_data {
+                                let idle_ended = tokio::select! {
+                                    biased;
+                                    _ = &mut idle_end_listener => {
+                                        idle_end_listener = self.idle_end_event.listen();
+                                        true
+                                    },
+                                    _ = std::future::ready(()) => false,
+                                };
+                                if !idle_ended {
+                                    let evict_span = tracing::info_span!(
+                                        parent: background_span.id(),
+                                        "evict tasks",
+                                        full = tracing::field::Empty,
+                                        data_and_meta = tracing::field::Empty,
+                                        data_only = tracing::field::Empty,
+                                        meta_only = tracing::field::Empty,
+                                    );
+                                    let _guard = evict_span.enter();
+                                    let counts = this.storage.evict_after_snapshot();
+                                    evict_span.record("full", counts.full);
+                                    evict_span.record("data_and_meta", counts.data_and_meta);
+                                    evict_span.record("data_only", counts.data_only);
+                                    evict_span.record("meta_only", counts.meta_only);
+                                }
+                            }
+
                             // Compact while idle (up to limit), regardless of
                             // whether the snapshot had new data.
                             // `background_span` is not entered here because

turbopack/crates/turbo-tasks-backend/src/backend/operation/mod.rs

@@ -18,7 +18,7 @@ use turbo_tasks::{
     TurboTasksCallApi, TypedSharedReference, backend::CachedTaskType,
 };
 
-use self::aggregation_update::ComputeDirtyAndCleanUpdate;
+pub use self::aggregation_update::ComputeDirtyAndCleanUpdate;
 use crate::{
     backend::{
         EventDescription, OperationGuard, TaskDataCategory, TurboTasksBackend,
@@ -266,18 +266,22 @@ impl<'e, B: BackingStorage> ExecuteContextImpl<'e, B> {
         for (i, &(task_id, category, _, _)) in tasks.iter().enumerate() {
             self.task_lock_counter.acquire();
 
-            let task = self.backend.storage.access_mut(task_id);
+            let mut task = self.backend.storage.access_mut(task_id);
             let mut ready = true;
             if matches!(category, TaskDataCategory::Data | TaskDataCategory::All)
                 && !task.flags.is_restored(TaskDataCategory::Data)
             {
+                // Mark as restoring so eviction backs off while we do I/O
+                // without the lock held.
+                task.flags.set_data_restoring(true);
                 tasks_to_restore_for_data.push(task_id);
                 tasks_to_restore_for_data_indicies.push(i);
                 ready = false;
             }
             if matches!(category, TaskDataCategory::Meta | TaskDataCategory::All)
                 && !task.flags.is_restored(TaskDataCategory::Meta)
             {
+                task.flags.set_meta_restoring(true);
                 tasks_to_restore_for_meta.push(task_id);
                 tasks_to_restore_for_meta_indicies.push(i);
                 ready = false;
@@ -355,13 +359,15 @@ impl<'e, B: BackingStorage> ExecuteContextImpl<'e, B> {
             {
                 task.restore_from(storage, TaskDataCategory::Data);
                 task.flags.set_restored(TaskDataCategory::Data);
+                task.flags.set_data_restoring(false);
                 task_type = task.get_persistent_task_type().cloned()
             }
             if let Some(storage) = storage_for_meta
                 && !task.flags.is_restored(TaskDataCategory::Meta)
             {
                 task.restore_from(storage, TaskDataCategory::Meta);
                 task.flags.set_restored(TaskDataCategory::Meta);
+                task.flags.set_meta_restoring(false);
             }
             self.task_lock_counter.release();
             prepared_task_callback(self, task_id, category, task);
@@ -487,6 +493,21 @@ impl<'e, B: BackingStorage> ExecuteContext<'e> for ExecuteContextImpl<'e, B> {
             category.includes_meta() && !task2.flags.is_restored(TaskDataCategory::Meta);
 
         if needs_data1 || needs_meta1 || needs_data2 || needs_meta2 {
+            // Mark as restoring so eviction backs off while we release
+            // the locks to do I/O.
+            if needs_data1 {
+                task1.flags.set_data_restoring(true);
+            }
+            if needs_meta1 {
+                task1.flags.set_meta_restoring(true);
+            }
+            if needs_data2 {
+                task2.flags.set_data_restoring(true);
+            }
+            if needs_meta2 {
+                task2.flags.set_meta_restoring(true);
+            }
+
             // Avoid holding the lock too long since this can also affect other tasks
             // Drop locks once, do all I/O, then re-acquire once
             drop(task1);
@@ -505,30 +526,35 @@ impl<'e, B: BackingStorage> ExecuteContext<'e> for ExecuteContextImpl<'e, B> {
             task1 = t1;
             task2 = t2;
 
-            // Merge results, handling race conditions
+            // Merge results, handling race conditions — only clear restoring
+            // flag if we win the race (see comment in task() above).
             if let Some(storage) = storage_data1
                 && !task1.flags.is_restored(TaskDataCategory::Data)
             {
                 task1.restore_from(storage, TaskDataCategory::Data);
                 task1.flags.set_restored(TaskDataCategory::Data);
+                task1.flags.set_data_restoring(false);
             }
             if let Some(storage) = storage_meta1
                 && !task1.flags.is_restored(TaskDataCategory::Meta)
             {
                 task1.restore_from(storage, TaskDataCategory::Meta);
                 task1.flags.set_restored(TaskDataCategory::Meta);
+                task1.flags.set_meta_restoring(false);
             }
             if let Some(storage) = storage_data2
                 && !task2.flags.is_restored(TaskDataCategory::Data)
             {
                 task2.restore_from(storage, TaskDataCategory::Data);
                 task2.flags.set_restored(TaskDataCategory::Data);
+                task2.flags.set_data_restoring(false);
             }
             if let Some(storage) = storage_meta2
                 && !task2.flags.is_restored(TaskDataCategory::Meta)
             {
                 task2.restore_from(storage, TaskDataCategory::Meta);
                 task2.flags.set_restored(TaskDataCategory::Meta);
+                task2.flags.set_meta_restoring(false);
             }
         }
         (
@@ -658,6 +684,7 @@ impl Display for TaskTypeRef<'_> {
     }
 }
 
+#[derive(Debug)]
 pub enum TaskType {
     Cached(Arc<CachedTaskType>),
     Transient(Arc<TransientTask>),
@@ -956,12 +983,12 @@ pub trait TaskGuard: Debug + TaskStorageAccessors {
     fn get_task_desc_fn(&self) -> impl Fn() -> String + Send + Sync + 'static {
         let task_type = self.get_task_type().to_owned();
         let task_id = self.id();
-        move || format!("{task_id:?} {task_type}")
+        move || format!("{task_id:?} {task_type:?}")
     }
     fn get_task_description(&self) -> String {
         let task_type = self.get_task_type().to_owned();
         let task_id = self.id();
-        format!("{task_id:?} {task_type}")
+        format!("{task_id:?} {task_type:?}")
     }
     fn get_task_name(&self) -> String {
         let task_type = self.get_task_type().to_owned();