​​Parallel compiler docs
​​
​​Overall shared state audit

​​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”)

​​Case-studies

​​errors::Handler:
  • ​​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
​​
​​