feat: memory prefetching by dobrac · Pull Request #1705 · e2b-dev/runtime

dobrac · 2026-01-09T13:36:45Z

Note

Introduces build-time memory access mapping and runtime prefetching to reduce sandbox startup latency.

Adds PrefetchTracker and extends UFFD to record page-fault order/types and expose PrefetchData; adds Prefault API to proactively map pages
New runtime prefetcher (uffd/prefetch) that fetches/copies pages in the background during resume; worker counts driven by feature flags
New build phase optimize collects memory access data by resuming the template multiple times, intersects results, and writes ordered prefetch mapping to template metadata; invalidates template cache after upload
Extends metadata schema with prefetch.memory { indices, access_types, block_size }
Refactors sandbox resume/init with utils.Promise; replaces async channel networking with getNetworkSlot promise
Improves cleanup behavior (late Add executes immediately), makes UFFD ready signaling robust and fdexit/UFFD Close idempotent; adds Cache.Invalidate
Adds tests for promise and prefetch mapping; minor cleanup (remove unused NewTrackerFromBitset)

^{Written by Cursor Bugbot for commit be2a21c. This will update automatically on new commits. Configure here.}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f8af9d9f85

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Co-authored-by: ValentaTomas <valenta.and.thomas@gmail.com>

also fix span names

## Fix Prefault/Close race causing ENOTTY/EBADF ### Motivation Since **2026-04-26** the orchestrator has been logging `UFFD serve uffdio copy error: inappropriate ioctl for device` (ENOTTY) and `bad file descriptor` (EBADF) from the UFFD prefetch path. The error rate increased sharply on **2026-05-27** after #2522 landed. The root cause is a race between the prefetcher and sandbox teardown: ``` Prefault goroutine Close() (teardown) ──────────────────────────────── ────────────────────────────── (about to acquire RLock) syscall.Close(uffd fd) ← fd freed ← OS recycles fd number to an unrelated file acquires RLock calls UFFDIO_COPY(recycled fd) → ENOTTY (or EBADF if not yet recycled) ``` `Close()` held no lock when it freed the uffd fd. The prefetcher runs on a non-cancellable `execCtx` and has no way to observe that `Close()` has run. If the OS recycled the fd number before the prefetcher's `UFFDIO_COPY` ioctl fired, the kernel returned ENOTTY because the fd now referred to a non-uffd file. The error was benign at the sandbox level (the sandbox was already being torn down) but noisy and misleading in logs. The bug was latent from when the prefetcher was introduced in January 2026 (#1705) but only started firing after the ubuntu24 template rebuild in April populated `Prefetch.Memory` data, causing the prefetcher to actually run. ### Fix `Close()` now holds `settleRequests.Lock()` for the **entire** close sequence and is idempotent: ```go func (u *Userfaultfd) Close() error { u.settleRequests.Lock() defer u.settleRequests.Unlock() if u.closed { return nil } u.closed = true syscall.Close(u.wakeupPipe[0]) syscall.Close(u.wakeupPipe[1]) return u.fd.close() } ``` `Prefault()` checks the flag immediately after acquiring `settleRequests.RLock()`: ```go u.settleRequests.RLock() defer u.settleRequests.RUnlock() if u.closed { return nil } ``` This gives three safety guarantees: 1. Any `Prefault` caller already holding `RLock` when `Close()` runs will complete its `UFFDIO_COPY` against the still-valid fd before `Close()` can acquire the write lock. 2. Any `Prefault` call that starts after `Close()` returns will see `closed == true` and return nil without touching the fd. 3. `Close()` is idempotent: a second call returns immediately without touching already-freed fds, preventing accidental double-close of the wakeup pipe fds (and any unrelated fd the OS may have recycled those numbers to). `settleRequests` already existed for exactly this kind of serialisation (guarding the lookup→install→state-update sequence against REMOVE batches), so no new lock is introduced. In production `Serve()` drains all workers via `u.wg.Wait()` before returning, so by the time the deferred `Close()` fires the lock is always uncontended. ### Test `TestPrefaultConcurrentWithClose` deterministically reproduces the race using a `faultPhaseBeforePrefaultRLock` test hook. The goroutine is parked before it acquires `RLock`, `Close()` is called to completion, then the goroutine is released. Without the fix the test fails with `failed to fault page: failed uffdio copy: bad file descriptor`; with the fix it returns nil. --------- Signed-off-by: Nikita Kalyazin <nikita.kalyazin@e2b.dev>

dobrac added the improvement Improvement for current functionality label Jan 9, 2026

dobrac requested review from ValentaTomas and jakubno as code owners January 9, 2026 13:36

e2b-request-same-site-reviewers Bot assigned jakubno Jan 9, 2026