Parallel compiler docs

Audit requirements:

No Deadlocks
  • locks held simultaneously are always acquired in same order
  • do not attempt to acquire locks reentrantly
  • good practice: statically prevent this by making functions operate “outside” or “inside” the lock and keep the two worlds separate
Correct primitive chosen
  • Use primitives from rustc_data_structures::sync
  • rustc_data_structures::sync::Once for “lazily initialized data”
  • DESIRE: an abstraction for append-only vectors, hashmaps, etc
  • rustc::data_structures::sync::Lock (Mutex) by default
  • rustc::data_structures::sync::RwLock if simultaneous readers are desired
  • this should be rare
  • Generally, do not use Atomics
  • DESIRE: abstractions common atomic-friendly situations:
  • global counters
  • whose exact value is essentially a progress meter, not a tracker for state
  • […]
State is observed within single lock
  • Avoid ABA problem by never “checking twice”
  • Do not reveal state to world before mutations finished

Documentation requirements

  • Lock acquire order for related locks (see “No Deadlocks”)


  • Single lock for all mutable state
  • “public” interface consists of methods taking lock and calling &mut self methods
  • ensure that the public interface is not called recursively to avoid deadlocks
  • refactored API to permit this separation to fully occur