2
2
//!
3
3
//! This implements locking on the package and index caches (source files,
4
4
//! `.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:
6
28
//!
7
29
//! * [`CacheLockMode::DownloadExclusive`] -- This is an exclusive lock
8
30
//! acquired while downloading packages and doing resolution.
17
39
//! cargo is reading from the cache.
18
40
//!
19
41
//! 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
23
50
//!
24
51
//! This is implemented by two separate lock files, the "download" one and the
25
52
//! "mutate" one. The `MutateExclusive` lock acquired both the "mutate" and
@@ -73,6 +100,8 @@ pub enum CacheLockMode {
73
100
/// A `DownloadExclusive` lock ensures that only one cargo is doing
74
101
/// resolution and downloading new packages.
75
102
///
103
+ /// You should use this when downloading new packages or doing resolution.
104
+ ///
76
105
/// If another cargo has a `MutateExclusive` lock, then an attempt to get
77
106
/// a `DownloadExclusive` lock will block.
78
107
///
@@ -81,22 +110,36 @@ pub enum CacheLockMode {
81
110
DownloadExclusive ,
82
111
/// A `Shared` lock allows multiple cargos to read from the source files.
83
112
///
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
+ ///
84
119
/// If another cargo has a `MutateExclusive` lock, then an attempt to get
85
120
/// a `Shared` will block.
86
121
///
87
- /// If another cargo has a `DownloadExclusive` lock, then the both can
122
+ /// If another cargo has a `DownloadExclusive` lock, then they both can
88
123
/// operate concurrently under the assumption that downloading does not
89
124
/// modify existing source files.
90
125
Shared ,
91
126
/// A `MutateExclusive` lock ensures no other cargo is reading or writing
92
127
/// from the package caches.
93
128
///
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.
96
136
MutateExclusive ,
97
137
}
98
138
99
139
/// 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.
100
143
#[ derive( Debug ) ]
101
144
pub struct CacheLocker {
102
145
/// The state of the locker.
0 commit comments