Deadlock Prevention#

LanceDB (and the underlying Lance core library) has two distinct deadlock failure modes: a CPU blocking-pool deadlock during FTS index construction on resource-constrained hosts, and a fork/background-thread deadlock when PyTorch DataLoader workers are created with the fork start method. Both are silent hangs at 0% CPU with no error or timeout.

1. FTS Index Build — CPU Blocking-Pool Deadlock#

Root Cause#

lance_core::utils::tokio::spawn_cpu dispatches CPU-intensive work to a dedicated blocking thread pool. The pool is sized to get_num_compute_intensive_cpus(), which returns max(1, num_cpus − LANCE_IO_CORE_RESERVATION) 1. IO_CORE_RESERVATION defaults to 2, so any host with ≤ 3 visible CPUs — 1-vCPU VMs, CPU-limited Kubernetes pods — has exactly one blocking worker 1.

The FTS posting-list pipeline in rust/lance-index/src/scalar/inverted/builder.rs uses a bounded channel (LANCE_FTS_WRITE_QUEUE_SIZE, default 1) to stream batches from a producer to a writer. When the pool has only one thread 2:

1. Producer calls send_blocking(batch) → channel is full → parks the sole blocking thread.
2. Writer receives the batch and calls do_flush → spawn_cpu → needs the same pool → no free worker.
3. Neither side can make progress. The process sits at 0% CPU indefinitely. 3

This surfaces with create_fts_index(..., base_tokenizer="ngram", prefix_only=False) once the input is large enough to produce more than one posting-list output batch 3.

Immediate Workaround#

Set LANCE_CPU_THREADS=2 (or higher) in the environment before running LanceDB. This forces the pool to have ≥ 2 workers and breaks the deadlock cycle 3.

LANCE_CPU_THREADS=2 python your_script.py

Proper Fix#

The spawn_cpu contract forbids any waiting inside the closure — no blocking channel sends, no I/O, no lock acquisition 1. The correct pattern is to keep the channel send in the async caller: build each batch with spawn_cpu, then dispatch it with tx.send(batch).await so the producer yields rather than parking a pool thread 2. The upstream issue also recommends ensuring get_num_compute_intensive_cpus() returns at least 2 and making CPU sizing cgroup-quota aware 3.

Relevant Environment Variables#

2. PyTorch DataLoader — Fork/Background-Thread Deadlock#

Root Cause#

LanceDB drives async Rust work through a Tokio runtime in a background thread. On Linux, PyTorch DataLoader with num_workers > 0 uses fork by default to create worker processes. The background runtime thread does not survive fork(): the child process inherits the runtime's file descriptors and state, but the worker thread is gone, so any subsequent async call in the child blocks forever (see the PyO3 Async Runtime Bridge article for the full fork-safety story). 4

Test Guards and Subprocess Timeout Mitigation#

python/python/tests/test_torch.py contains two tests that exercise fork-based DataLoader workers:

• test_permutation_dataloader_fork_workers — native table
• test_remote_permutation_dataloader_fork_workers — remote table over a mock HTTP server

Both are skipped on non-Linux platforms via 5:

@pytest.mark.skipif(
    sys.platform != "linux",
    reason=(
        "fork() is unavailable on Windows and unsafe on macOS "
        "(Apple frameworks/TLS are not fork-safe)"
    ),
)

To avoid a test suite hang if the deadlock regresses, both tests run the forking code inside a subprocess launched with mp.get_context("spawn") and joined with timeout=30 seconds. If the subprocess is still alive after the timeout, it is terminated and the test fails with an explicit message 6:

proc.join(timeout=30)
if proc.is_alive():
    proc.terminate()
    ...
    pytest.fail("Permutation hung when iterated in a fork-based DataLoader worker")

The subprocess itself uses multiprocessing_context="fork" for its DataLoader workers — this is what exercises the real deadlock path 7.

Using spawn Instead of fork#

The recommended fix is to always pass multiprocessing_context="spawn" to DataLoader when using LanceDB datasets. The spawn start method creates a fresh Python interpreter in each worker without inheriting the parent's Tokio runtime state, eliminating the deadlock. Multiprocessing tests that are not exercising the fork-safety path already use this 8 9.

Key Files & References#