Unverified Commit 6a733742 authored by Tobias Koppers's avatar Tobias Koppers Committed by GitHub

Improve unsafe code safety documentation in turbo-tasks-backend (#90755)

### What?

Improves safety documentation for all `unsafe` code in the
`turbo-tasks-backend` crate (6 files, comment-only changes).

### Why?

A comprehensive audit of all 14 files containing `unsafe` code in
`turbo-tasks-backend` found **no soundness bugs**, but identified
several safety comments that were incorrect, misleading, or missing
entirely. Correct safety documentation is critical for maintaining
unsafe code over time — reviewers and future contributors rely on these
comments to understand invariants.

### How?

**Fixes applied (comment-only, no behavior changes):**

1. **`backend/operation/mod.rs`** — Fixed transmute safety comment that
referenced wrong lifetime names (`'a`/`'l` → `'e`/`'tx`)
2. **`database/read_transaction_cache.rs`** — Fixed reference to wrong
struct name (`LmdbBackingStorage` → `ReadTransactionCache`); added
struct-level doc explaining the field-ordering invariant required for
drop safety
3. **`database/startup_cache.rs`** — Added struct-level doc explaining
the self-referential pattern and field-ordering invariant; improved
inline safety comment
4. **`utils/dash_map_multi.rs`** — Added safety justification for
`unsafe impl Send/Sync` on `RefMut` explaining bucket pointer
exclusivity
5. **`backing_storage.rs`** — Added `// Safety:` comments to 6 `unsafe`
blocks in the `Either` impl that were missing them
6. **`kv_backing_storage.rs`** — Made the `flush()` safety comment more
specific about what "finished processing" means

**Audit summary (14 files reviewed):**

| Risk | Category | Files | Verdict |
|------|----------|-------|---------|
| HIGH | Lifetime transmutation | 3 | Sound ✓ — comments fixed |
| MEDIUM | DashMap raw bucket access | 3 | Sound ✓ — Send/Sync docs
added |
| LOW | Unsafe trait method contracts | 8 | Sound ✓ — missing comments
added |
| NEGLIGIBLE | Test code | 1 | No issues |
parent 9c939729
......@@ -144,7 +144,11 @@ where
}
let tx = self.backend.backing_storage.start_read_transaction();
let tx = tx.map(|tx| {
// Safety: self is actually valid for 'a, so it's safe to transmute 'l to 'a
// Safety: `self.backend.backing_storage` lives for at least `'e`. The
// transaction returned by `start_read_transaction()` borrows it for `'e`.
// Since `'tx: 'e`, transmuting to `'tx` is sound because the transaction
// is stored in `self.transaction` (as `Owned`) and dropped with `self`,
// while `self.backend` remains alive for `'e`.
unsafe { transmute::<B::ReadTransaction<'_>, B::ReadTransaction<'tx>>(tx) }
});
self.transaction = TransactionState::Owned(tx);
......
......@@ -165,10 +165,12 @@ where
match self {
Either::Left(this) => {
let tx = tx.map(|tx| read_transaction_left_or_panic(tx.as_ref()));
// Safety: `tx` is unwrapped from `Either::Left`, so it originated from `this`.
unsafe { this.lookup_task_candidates(tx, key) }
}
Either::Right(this) => {
let tx = tx.map(|tx| read_transaction_right_or_panic(tx.as_ref()));
// Safety: `tx` is unwrapped from `Either::Right`, so it originated from `this`.
unsafe { this.lookup_task_candidates(tx, key) }
}
}
......@@ -184,10 +186,12 @@ where
match self {
Either::Left(this) => {
let tx = tx.map(|tx| read_transaction_left_or_panic(tx.as_ref()));
// Safety: `tx` is unwrapped from `Either::Left`, so it originated from `this`.
unsafe { this.lookup_data(tx, task_id, category, storage) }
}
Either::Right(this) => {
let tx = tx.map(|tx| read_transaction_right_or_panic(tx.as_ref()));
// Safety: `tx` is unwrapped from `Either::Right`, so it originated from `this`.
unsafe { this.lookup_data(tx, task_id, category, storage) }
}
}
......@@ -202,10 +206,12 @@ where
match self {
Either::Left(this) => {
let tx = tx.map(|tx| read_transaction_left_or_panic(tx.as_ref()));
// Safety: `tx` is unwrapped from `Either::Left`, so it originated from `this`.
unsafe { this.batch_lookup_data(tx, task_ids, category) }
}
Either::Right(this) => {
let tx = tx.map(|tx| read_transaction_right_or_panic(tx.as_ref()));
// Safety: `tx` is unwrapped from `Either::Right`, so it originated from `this`.
unsafe { this.batch_lookup_data(tx, task_ids, category) }
}
}
......
......@@ -31,9 +31,17 @@ impl<T: KeyValueDatabase> ThreadLocalReadTransactionsContainer<T> {
// Safety: It's safe to send RoTransaction between threads, but the types don't allow that.
unsafe impl<T: KeyValueDatabase> Send for ThreadLocalReadTransactionsContainer<T> {}
/// Caches read transactions in thread-local storage to avoid creating new ones for every operation.
///
/// # Safety invariant (field ordering)
///
/// `read_transactions_cache` must be declared before `database` so that Rust's field drop order
/// (declaration order) drops the cached transactions before the database. The cached transactions
/// store `T::ReadTransaction<'static>` where the `'static` is a transmuted lie — the true
/// lifetime is tied to `database`. Dropping the cache first ensures all transactions are released
/// before the database they borrow from.
pub struct ReadTransactionCache<T: KeyValueDatabase + 'static> {
// Safety: `read_transactions_cache` need to be dropped before `database` since it will end the
// transactions.
// Safety: Must be declared before `database` — see struct-level safety invariant above.
read_transactions_cache: ArcSwap<ThreadLocal<ThreadLocalReadTransactionsContainer<T>>>,
database: T,
}
......@@ -120,10 +128,11 @@ impl<T: KeyValueDatabase> Drop for CachedReadTransaction<'_, T> {
let container = self
.thread_locals
.get_or(|| ThreadLocalReadTransactionsContainer(UnsafeCell::new(Default::default())));
// Safety: We cast it to 'static lifetime, but it will be casted back to 'env when
// taken. It's safe since this will not outlive the environment. We need to
// be careful with Drop, but `read_transactions_cache` is before `env` in the
// LmdbBackingStorage struct, so it's fine.
// Safety: We cast to 'static because the thread-local cache stores transactions
// with an erased lifetime. The transaction will be cast back to the database's
// actual lifetime when popped in `begin_read_transaction`. This is sound because
// `ReadTransactionCache` declares `read_transactions_cache` before `database`,
// so Rust drops the cache (releasing all stored transactions) before the database.
let tx = unsafe {
transmute::<T::ReadTransaction<'_>, T::ReadTransaction<'static>>(
self.tx.take().unwrap(),
......
......@@ -42,6 +42,14 @@ impl<T: KeyValueDatabase> Borrow<[u8]> for ValueBuffer<'_, T> {
type Cache = ByKeySpace<FxDashMap<Vec<u8>, Option<Vec<u8>>>>;
/// A caching layer that stores recently-read key-value pairs for fast startup.
///
/// # Safety invariant (self-referential struct, field ordering)
///
/// `restored_map` contains `&'static [u8]` slices that actually point into the `_restored`
/// `Vec<u8>` buffer. The `'static` lifetime is a transmuted lie. This is sound because
/// `restored_map` is declared before `_restored`, so Rust drops the map (releasing the dangling
/// references) before dropping the backing buffer. **Do not reorder these fields.**
pub struct StartupCacheLayer<T: KeyValueDatabase> {
database: T,
path: PathBuf,
......@@ -49,7 +57,8 @@ pub struct StartupCacheLayer<T: KeyValueDatabase> {
cache_size: AtomicUsize,
cache: Cache,
restored_map: ByKeySpace<FxHashMap<&'static [u8], &'static [u8]>>,
// Need to be kept around to keep the restored_map reference alive
// Safety: Must be declared AFTER `restored_map` — `restored_map` contains references into this
// buffer. See struct-level safety invariant above.
_restored: Vec<u8>,
}
......@@ -65,8 +74,9 @@ impl<T: KeyValueDatabase> StartupCacheLayer<T> {
let (key_space, key, value) = read_key_value_pair(&restored, &mut pos)?;
let map = restored_map.get_mut(key_space);
unsafe {
// Safety: This is a self reference, it's valid as long the `restored`
// buffer is alive
// Safety: Self-referential pattern — these slices point into `restored`
// (which becomes `_restored`). See struct-level safety invariant on
// `StartupCacheLayer` for why the field ordering makes this sound.
map.insert(
transmute::<&'_ [u8], &'static [u8]>(key),
transmute::<&'_ [u8], &'static [u8]>(value),
......
......@@ -280,8 +280,10 @@ impl<T: KeyValueDatabase + Send + Sync + 'static> BackingStorageSealed
&[KeySpace::TaskMeta, KeySpace::TaskData],
|&key_space| {
let _span = span.clone().entered();
// Safety: We already finished all processing of the task data and task
// meta
// Safety: `process_task_data` has returned, so no concurrent `put` or
// `delete` on `TaskMeta`/`TaskData` key spaces are in-flight. The
// `parallel::try_for_each` below flushes disjoint key spaces, so
// concurrent flushes on different key spaces are safe.
unsafe { batch.flush(key_space) }
},
)?;
......
......@@ -21,6 +21,14 @@ pub enum RefMut<'a, K, V> {
},
}
// SAFETY: `RefMut` contains a raw `Bucket` pointer into a `DashMap` shard's `RawTable`.
// Sending/sharing is safe because:
// - `Simple` variant: The `Bucket` is accessed under an exclusive `RwLockWriteGuard` on a single
// shard. The guard provides exclusive access to all data in that shard.
// - `Shared` variant: The `Bucket` is accessed under an `Arc<RwLockWriteGuard>`. The
// `get_multiple_mut` function asserts that bucket pointers do not alias, so each `RefMut` has
// exclusive access to its bucket even when sharing a guard.
// - `K: Sync + V: Sync` bounds ensure the key and value types are safe to share across threads.
unsafe impl<K: Eq + Hash + Sync, V: Sync> Send for RefMut<'_, K, V> {}
unsafe impl<K: Eq + Hash + Sync, V: Sync> Sync for RefMut<'_, K, V> {}
......
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