Concurrency Best Practices

Safety and operability rules for threads, processes, and bridges to async code.

How to Use This List

• Apply before increasing max_workers or task fan-out.
• Load-test shutdown paths - races appear on deploy/restart.
• Prefer message passing; treat shared memory as guilty until proven safe.

A - Model Selection

• Profile before picking asyncio vs threads vs processes. Labels deceive without timing data.
• Keep CPU work off asyncio event loop thread. to_thread or process pool.
• Use ProcessPool for CPU-bound pure Python on GIL builds. Do not expect thread linear speedup.
• Size thread pools to I/O concurrency limits. Connection pools, not cpu_count() * 5 by default.
• Document model choice in ADR. Future maintainers need the why.

B - Shared State

• Prefer queues over shared mutable structures. Producer/consumer simplifies reasoning.
• Protect multi-step invariants with locks. Single bytecode ops are not whole transactions.
• Acquire locks in fixed global order. Document order to prevent deadlocks.
• Avoid global singletons mutated by workers. Pass explicit context or use threading.local().
• Use immutable messages between stages. Snapshots, not live object graphs.

C - Processes & Pools

• Guard multiprocessing entry with if __name__ == "__main__". Required on spawn platforms.
• Keep worker targets picklable top-level functions. No lambdas in ProcessPool.
• Set maxtasksperchild for leaky C extensions. Long-running pools recycle workers.
• Cap workers by memory budget. RSS × workers must fit container limit.
• Configure logging in worker initializer. Avoid inherited broken handlers.

D - Shutdown & Errors

• Join threads with timeout during shutdown. Log stragglers; avoid daemon mid-critical-section.
• Use queue sentinels per consumer. One poison pill per worker thread/process.
• Call task_done for every queue.get in threading.Queue pipelines. Or join hangs.
• Handle Future exceptions at result(). Silent failed futures lose errors.
• Cancel outstanding futures on timeout. Do not leak background work.

E - Async Bridge

• Never call blocking I/O inside coroutines without executor. Blocks all tasks.
• Share one loop per thread. Do not call asyncio.run repeatedly in hot servers use lifespan.
• Propagate contextvars to thread workers when needed. Request ids for logs.
• Test concurrent code under stress. Timing-only tests flake; use barriers/events.
• Revisit concurrency model when dependencies go async. Thread pools may become unnecessary.

FAQs

Related

• Choosing a Concurrency Model - pick model
• threading - locks detail
• Queues & Producer/Consumer - pipelines
• Async Best Practices - async-specific rules

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.