Skip to content

Commit 889558f

Browse files
committed
Extend cache_lock documentation.
1 parent df2e2a3 commit 889558f

File tree

1 file changed

+50
-7
lines changed

1 file changed

+50
-7
lines changed

src/cargo/util/cache_lock.rs

Lines changed: 50 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,29 @@
22
//!
33
//! This implements locking on the package and index caches (source files,
44
//! `.crate` files, and index caches) to coordinate when multiple cargos are
5-
//! running at the same time. There are three styles of locks:
5+
//! running at the same time.
6+
//!
7+
//! ## Usage
8+
//!
9+
//! There is a global [`CacheLocker`] held inside cargo's venerable
10+
//! [`Config`]. The `CacheLocker` manages creating and tracking the locks
11+
//! being held. There are methods on `Config` for managing the locks:
12+
//!
13+
//! - [`Config::acquire_package_cache_lock`] --- Acquires a lock. May block if
14+
//! another process holds a lock.
15+
//! - [`Config::try_acquire_package_cache_lock`] --- Acquires a lock, returning
16+
//! immediately if it would block.
17+
//! - [`Config::assert_package_cache_locked`] --- This is used to ensure the
18+
//! proper lock is being held.
19+
//!
20+
//! Lower-level code that accesses the package cache typically just use
21+
//! `assert_package_cache_locked` to ensure that the correct lock is being
22+
//! held. Higher-level code is responsible for acquiring the appropriate lock,
23+
//! and holding it during the duration that it is performing its operation.
24+
//!
25+
//! ## Types of locking
26+
//!
27+
//! There are three styles of locks:
628
//!
729
//! * [`CacheLockMode::DownloadExclusive`] -- This is an exclusive lock
830
//! acquired while downloading packages and doing resolution.
@@ -17,9 +39,14 @@
1739
//! cargo is reading from the cache.
1840
//!
1941
//! Importantly, a `DownloadExclusive` lock does *not* interfere with a
20-
//! `Shared` lock. The download process generally does not modify source
21-
//! files, so other cargos should be able to safely proceed in reading source
22-
//! files[^1].
42+
//! `Shared` lock. The download process generally does not modify source files
43+
//! (it only adds new ones), so other cargos should be able to safely proceed
44+
//! in reading source files[^1].
45+
//!
46+
//! See the [`CacheLockMode`] enum docs for more details on when the different
47+
//! modes should be used.
48+
//!
49+
//! ## Locking implementation details
2350
//!
2451
//! This is implemented by two separate lock files, the "download" one and the
2552
//! "mutate" one. The `MutateExclusive` lock acquired both the "mutate" and
@@ -73,6 +100,8 @@ pub enum CacheLockMode {
73100
/// A `DownloadExclusive` lock ensures that only one cargo is doing
74101
/// resolution and downloading new packages.
75102
///
103+
/// You should use this when downloading new packages or doing resolution.
104+
///
76105
/// If another cargo has a `MutateExclusive` lock, then an attempt to get
77106
/// a `DownloadExclusive` lock will block.
78107
///
@@ -81,22 +110,36 @@ pub enum CacheLockMode {
81110
DownloadExclusive,
82111
/// A `Shared` lock allows multiple cargos to read from the source files.
83112
///
113+
/// You should use this when cargo is reading source files from the
114+
/// package cache. This is typically done during the build phase, since
115+
/// cargo only needs to read files during that time. This allows multiple
116+
/// cargo processes to build concurrently without interfering with one
117+
/// another, while guarding against other cargos using `MutateExclusive`.
118+
///
84119
/// If another cargo has a `MutateExclusive` lock, then an attempt to get
85120
/// a `Shared` will block.
86121
///
87-
/// If another cargo has a `DownloadExclusive` lock, then the both can
122+
/// If another cargo has a `DownloadExclusive` lock, then they both can
88123
/// operate concurrently under the assumption that downloading does not
89124
/// modify existing source files.
90125
Shared,
91126
/// A `MutateExclusive` lock ensures no other cargo is reading or writing
92127
/// from the package caches.
93128
///
94-
/// This is used for things like garbage collection to avoid modifying
95-
/// caches while other cargos are running.
129+
/// You should use this when modifying existing files in the package
130+
/// cache. For example, things like garbage collection want to avoid
131+
/// deleting files while other cargos are trying to read (`Shared`) or
132+
/// resolve or download (`DownloadExclusive`).
133+
///
134+
/// If another cargo has a `DownloadExclusive` or `Shared` lock, then this
135+
/// will block until they all release their locks.
96136
MutateExclusive,
97137
}
98138

99139
/// A locker that can be used to acquire locks.
140+
///
141+
/// See the [`crate::util::cache_lock`] module documentation for an overview
142+
/// of how cache locking works.
100143
#[derive(Debug)]
101144
pub struct CacheLocker {
102145
/// The state of the locker.

0 commit comments

Comments
 (0)