Added some docs

Author: ranger-ross

src/cargo/core/compiler/locking.rs

@@ -1,3 +1,26 @@
+//! This module handles the locking logic during compilation.
+//!
+//! The locking scheme is based on build unit level locking.
+//! Each build unit consists of a primary and secondary lock used to represent multiple lock states.
+//!
+//! | State                  | Primary     | Secondary   |
+//! |------------------------|-------------|-------------|
+//! | Building Exclusive     | `exclusive` | `exclusive` |
+//! | Building Non-Exclusive | `shared`    | `exclusive` |
+//! | Shared                 | `shared`    | `none`      |
+//!
+//! Generally a build unit will full the following flow:
+//! 1. Acquire a "building exclusive" lock for the current build unit.
+//! 2. Acquire "shared" locks on all dependency build units.
+//! 3. Begin building with rustc
+//! 4. If we are building a library, downgrade to a "building non-exclusive" lock when the `.rmeta` has been generated.
+//! 5. Once complete release all locks.
+//!
+//! The primary reason for the complexity here it to allow dependant crates to proceed with thier
+//! compilation as possible.
+//!
+//! [`CompilationLock`] is the primary interface for locking.
+
 use std::{
     fs::{File, OpenOptions},
     path::{Path, PathBuf},
@@ -46,6 +69,7 @@ impl CompilationLock {
     }
 }
 
+/// A lock for a single build unit.
 struct UnitLock {
     primary: PathBuf,
     secondary: PathBuf,

src/cargo/core/compiler/mod.rs

@@ -363,8 +363,11 @@ fn rustc(
     return Ok(Work::new(move |state| {
         if let Some(lock) = &mut lock {
             lock.lock();
+
+            // TODO: We need to revalidate the fingerprint here as another Cargo instance could
+            // have already compiled the crate before we recv'd the lock.
+            // For large crates re-compiling here would be quiet costly.
         }
-        // let mut lock = lock.map(|v| v.lock());
 
         // Artifacts are in a different location than typical units,
         // hence we must assure the crate- and target-dependent