1 //! An implementation of the GNU make jobserver.
3 //! This crate is an implementation, in Rust, of the GNU `make` jobserver for
4 //! CLI tools that are interoperating with make or otherwise require some form
5 //! of parallelism limiting across process boundaries. This was originally
6 //! written for usage in Cargo to both (a) work when `cargo` is invoked from
7 //! `make` (using `make`'s jobserver) and (b) work when `cargo` invokes build
8 //! scripts, exporting a jobserver implementation for `make` processes to
11 //! The jobserver implementation can be found in [detail online][docs] but
12 //! basically boils down to a cross-process semaphore. On Unix this is
13 //! implemented with the `pipe` syscall and read/write ends of a pipe and on
14 //! Windows this is implemented literally with IPC semaphores.
16 //! The jobserver protocol in `make` also dictates when tokens are acquired to
17 //! run child work, and clients using this crate should take care to implement
18 //! such details to ensure correct interoperation with `make` itself.
22 //! Connect to a jobserver that was set up by `make` or a different process:
25 //! use jobserver::Client;
27 //! // See API documentation for why this is `unsafe`
28 //! let client = match unsafe { Client::from_env() } {
29 //! Some(client) => client,
30 //! None => panic!("client not configured"),
34 //! Acquire and release token from a jobserver:
37 //! use jobserver::Client;
39 //! let client = unsafe { Client::from_env().unwrap() };
40 //! let token = client.acquire().unwrap(); // blocks until it is available
41 //! drop(token); // releases the token when the work is done
44 //! Create a new jobserver and configure a child process to have access:
47 //! use std::process::Command;
48 //! use jobserver::Client;
50 //! let client = Client::new(4).expect("failed to create jobserver");
51 //! let mut cmd = Command::new("make");
52 //! client.configure(&mut cmd);
57 //! This crate makes no attempt to release tokens back to a jobserver on
58 //! abnormal exit of a process. If a process which acquires a token is killed
59 //! with ctrl-c or some similar signal then tokens will not be released and the
60 //! jobserver may be in a corrupt state.
62 //! Note that this is typically ok as ctrl-c means that an entire build process
63 //! is being torn down, but it's worth being aware of at least!
65 //! ## Windows caveats
67 //! There appear to be two implementations of `make` on Windows. On MSYS2 one
68 //! typically comes as `mingw32-make` and the other as `make` itself. I'm not
69 //! personally too familiar with what's going on here, but for jobserver-related
70 //! information the `mingw32-make` implementation uses Windows semaphores
71 //! whereas the `make` program does not. The `make` program appears to use file
72 //! descriptors and I'm not really sure how it works, so this crate is not
73 //! compatible with `make` on Windows. It is, however, compatible with
76 //! [docs]: http://make.mad-scientist.net/papers/jobserver-implementation/
78 #![deny(missing_docs, missing_debug_implementations)]
79 #![doc(html_root_url = "https://docs.rs/jobserver/0.1")]
83 use std
::process
::Command
;
84 use std
::sync
::{Arc, Condvar, Mutex, MutexGuard}
;
90 #[path = "windows.rs"]
92 #[cfg(not(any(unix, windows)))]
96 /// A client of a jobserver
98 /// This structure is the main type exposed by this library, and is where
99 /// interaction to a jobserver is configured through. Clients are either created
100 /// from scratch in which case the internal semphore is initialied on the spot,
101 /// or a client is created from the environment to connect to a jobserver
104 /// Some usage examples can be found in the crate documentation for using a
107 /// Note that a `Client` implements the `Clone` trait, and all instances of a
108 /// `Client` refer to the same jobserver instance.
109 #[derive(Clone, Debug)]
111 inner
: Arc
<imp
::Client
>,
114 /// An acquired token from a jobserver.
116 /// This token will be released back to the jobserver when it is dropped and
117 /// otherwise represents the ability to spawn off another thread of work.
119 pub struct Acquired
{
120 client
: Arc
<imp
::Client
>,
126 /// This drops the `Acquired` token without releasing the associated token.
128 /// This is not generally useful, but can be helpful if you do not have the
129 /// ability to store an Acquired token but need to not yet release it.
131 /// You'll typically want to follow this up with a call to `release_raw` or
132 /// similar to actually release the token later on.
133 pub fn drop_without_releasing(mut self) {
134 self.disabled
= true;
138 #[derive(Default, Debug)]
140 lock
: Mutex
<HelperInner
>,
144 #[derive(Default, Debug)]
152 /// Creates a new jobserver initialized with the given parallelism limit.
154 /// A client to the jobserver created will be returned. This client will
155 /// allow at most `limit` tokens to be acquired from it in parallel. More
156 /// calls to `acquire` will cause the calling thread to block.
158 /// Note that the created `Client` is not automatically inherited into
159 /// spawned child processes from this program. Manual usage of the
160 /// `configure` function is required for a child process to have access to a
166 /// use jobserver::Client;
168 /// let client = Client::new(4).expect("failed to create jobserver");
173 /// Returns an error if any I/O error happens when attempting to create the
174 /// jobserver client.
175 pub fn new(limit
: usize) -> io
::Result
<Client
> {
177 inner
: Arc
::new(imp
::Client
::new(limit
)?
),
181 /// Attempts to connect to the jobserver specified in this process's
184 /// When the a `make` executable calls a child process it will configure the
185 /// environment of the child to ensure that it has handles to the jobserver
186 /// it's passing down. This function will attempt to look for these details
187 /// and connect to the jobserver.
189 /// Note that the created `Client` is not automatically inherited into
190 /// spawned child processes from this program. Manual usage of the
191 /// `configure` function is required for a child process to have access to a
196 /// If a jobserver was found in the environment and it looks correct then
197 /// `Some` of the connected client will be returned. If no jobserver was
198 /// found then `None` will be returned.
200 /// Note that on Unix the `Client` returned **takes ownership of the file
201 /// descriptors specified in the environment**. Jobservers on Unix are
202 /// implemented with `pipe` file descriptors, and they're inherited from
203 /// parent processes. This `Client` returned takes ownership of the file
204 /// descriptors for this process and will close the file descriptors after
205 /// this value is dropped.
207 /// Additionally on Unix this function will configure the file descriptors
208 /// with `CLOEXEC` so they're not automatically inherited by spawned
213 /// This function is `unsafe` to call on Unix specifically as it
214 /// transitively requires usage of the `from_raw_fd` function, which is
215 /// itself unsafe in some circumstances.
217 /// It's recommended to call this function very early in the lifetime of a
218 /// program before any other file descriptors are opened. That way you can
219 /// make sure to take ownership properly of the file descriptors passed
222 /// It's generally unsafe to call this function twice in a program if the
223 /// previous invocation returned `Some`.
225 /// Note, though, that on Windows it should be safe to call this function
226 /// any number of times.
227 pub unsafe fn from_env() -> Option
<Client
> {
228 let var
= match env
::var("CARGO_MAKEFLAGS")
229 .or(env
::var("MAKEFLAGS"))
230 .or(env
::var("MFLAGS"))
233 Err(_
) => return None
,
235 let mut arg
= "--jobserver-fds=";
236 let pos
= match var
.find(arg
) {
239 arg
= "--jobserver-auth=";
240 match var
.find(arg
) {
247 let s
= var
[pos
+ arg
.len()..].split(' '
).next().unwrap();
248 imp
::Client
::open(s
).map(|c
| Client { inner: Arc::new(c) }
)
251 /// Acquires a token from this jobserver client.
253 /// This function will block the calling thread until a new token can be
254 /// acquired from the jobserver.
258 /// On successful acquisition of a token an instance of `Acquired` is
259 /// returned. This structure, when dropped, will release the token back to
260 /// the jobserver. It's recommended to avoid leaking this value.
264 /// If an I/O error happens while acquiring a token then this function will
265 /// return immediately with the error. If an error is returned then a token
266 /// was not acquired.
267 pub fn acquire(&self) -> io
::Result
<Acquired
> {
268 let data
= self.inner
.acquire()?
;
270 client
: self.inner
.clone(),
276 /// Configures a child process to have access to this client's jobserver as
279 /// This function is required to be called to ensure that a jobserver is
280 /// properly inherited to a child process. If this function is *not* called
281 /// then this `Client` will not be accessible in the child process. In other
282 /// words, if not called, then `Client::from_env` will return `None` in the
283 /// child process (or the equivalent of `Child::from_env` that `make` uses).
285 /// ## Platform-specific behavior
287 /// On Unix and Windows this will clobber the `CARGO_MAKEFLAGS` environment
288 /// variables for the child process, and on Unix this will also allow the
289 /// two file descriptors for this client to be inherited to the child.
291 /// On platforms other than Unix and Windows this panics.
292 pub fn configure(&self, cmd
: &mut Command
) {
293 let arg
= self.inner
.string_arg();
294 // Older implementations of make use `--jobserver-fds` and newer
295 // implementations use `--jobserver-auth`, pass both to try to catch
296 // both implementations.
297 let value
= format
!("--jobserver-fds={0} --jobserver-auth={0}", arg
);
298 cmd
.env("CARGO_MAKEFLAGS", &value
);
299 self.inner
.configure(cmd
);
302 /// Converts this `Client` into a helper thread to deal with a blocking
303 /// `acquire` function a little more easily.
305 /// The fact that the `acquire` function on `Client` blocks isn't always
306 /// the easiest to work with. Typically you're using a jobserver to
307 /// manage running other events in parallel! This means that you need to
308 /// either (a) wait for an existing job to finish or (b) wait for a
309 /// new token to become available.
311 /// Unfortunately the blocking in `acquire` happens at the implementation
312 /// layer of jobservers. On Unix this requires a blocking call to `read`
313 /// and on Windows this requires one of the `WaitFor*` functions. Both
314 /// of these situations aren't the easiest to deal with:
316 /// * On Unix there's basically only one way to wake up a `read` early, and
317 /// that's through a signal. This is what the `make` implementation
318 /// itself uses, relying on `SIGCHLD` to wake up a blocking acquisition
319 /// of a new job token. Unfortunately nonblocking I/O is not an option
320 /// here, so it means that "waiting for one of two events" means that
321 /// the latter event must generate a signal! This is not always the case
322 /// on unix for all jobservers.
324 /// * On Windows you'd have to basically use the `WaitForMultipleObjects`
325 /// which means that you've got to canonicalize all your event sources
326 /// into a `HANDLE` which also isn't the easiest thing to do
329 /// This function essentially attempts to ease these limitations by
330 /// converting this `Client` into a helper thread spawned into this
331 /// process. The application can then request that the helper thread
332 /// acquires tokens and the provided closure will be invoked for each token
335 /// The intention is that this function can be used to translate the event
336 /// of a token acquisition into an arbitrary user-defined event.
340 /// This function will consume the `Client` provided to be transferred to
341 /// the helper thread that is spawned. Additionally a closure `f` is
342 /// provided to be invoked whenever a token is acquired.
344 /// This closure is only invoked after calls to
345 /// `HelperThread::request_token` have been made and a token itself has
346 /// been acquired. If an error happens while acquiring the token then
347 /// an error will be yielded to the closure as well.
351 /// This function will return an instance of the `HelperThread` structure
352 /// which is used to manage the helper thread associated with this client.
353 /// Through the `HelperThread` you'll request that tokens are acquired.
354 /// When acquired, the closure provided here is invoked.
356 /// When the `HelperThread` structure is returned it will be gracefully
357 /// torn down, and the calling thread will be blocked until the thread is
358 /// torn down (which should be prompt).
362 /// This function may fail due to creation of the helper thread or
363 /// auxiliary I/O objects to manage the helper thread. In any of these
364 /// situations the error is propagated upwards.
366 /// # Platform-specific behavior
368 /// On Windows this function behaves pretty normally as expected, but on
369 /// Unix the implementation is... a little heinous. As mentioned above
370 /// we're forced into blocking I/O for token acquisition, namely a blocking
371 /// call to `read`. We must be able to unblock this, however, to tear down
372 /// the helper thread gracefully!
374 /// Essentially what happens is that we'll send a signal to the helper
375 /// thread spawned and rely on `EINTR` being returned to wake up the helper
376 /// thread. This involves installing a global `SIGUSR1` handler that does
377 /// nothing along with sending signals to that thread. This may cause
378 /// odd behavior in some applications, so it's recommended to review and
379 /// test thoroughly before using this.
380 pub fn into_helper_thread
<F
>(self, f
: F
) -> io
::Result
<HelperThread
>
382 F
: FnMut(io
::Result
<Acquired
>) + Send
+ '
static,
384 let state
= Arc
::new(HelperState
::default());
386 inner
: Some(imp
::spawn_helper(self, state
.clone(), Box
::new(f
))?
),
391 /// Blocks the current thread until a token is acquired.
393 /// This is the same as `acquire`, except that it doesn't return an RAII
394 /// helper. If successful the process will need to guarantee that
395 /// `release_raw` is called in the future.
396 pub fn acquire_raw(&self) -> io
::Result
<()> {
397 self.inner
.acquire()?
;
401 /// Releases a jobserver token back to the original jobserver.
403 /// This is intended to be paired with `acquire_raw` if it was called, but
404 /// in some situations it could also be called to relinquish a process's
405 /// implicit token temporarily which is then re-acquired later.
406 pub fn release_raw(&self) -> io
::Result
<()> {
407 self.inner
.release(None
)?
;
412 impl Drop
for Acquired
{
415 drop(self.client
.release(Some(&self.data
)));
420 /// Structure returned from `Client::into_helper_thread` to manage the lifetime
421 /// of the helper thread returned, see those associated docs for more info.
423 pub struct HelperThread
{
424 inner
: Option
<imp
::Helper
>,
425 state
: Arc
<HelperState
>,
429 /// Request that the helper thread acquires a token, eventually calling the
430 /// original closure with a token when it's available.
432 /// For more information, see the docs on that function.
433 pub fn request_token(&self) {
434 // Indicate that there's one more request for a token and then wake up
435 // the helper thread if it's sleeping.
436 self.state
.lock().requests
+= 1;
437 self.state
.cvar
.notify_one();
441 impl Drop
for HelperThread
{
443 // Flag that the producer half is done so the helper thread should exit
444 // quickly if it's waiting. Wake it up if it's actually waiting
445 self.state
.lock().producer_done
= true;
446 self.state
.cvar
.notify_one();
448 // ... and afterwards perform any thread cleanup logic
449 self.inner
.take().unwrap().join();
454 fn lock(&self) -> MutexGuard
<'_
, HelperInner
> {
455 self.lock
.lock().unwrap_or_else(|e
| e
.into_inner())
458 /// Executes `f` for each request for a token, where `f` is expected to
459 /// block and then provide the original closure with a token once it's
462 /// This is an infinite loop until the helper thread is dropped, at which
463 /// point everything should get interrupted.
464 fn for_each_request(&self, mut f
: impl FnMut(&HelperState
)) {
465 let mut lock
= self.lock();
467 // We only execute while we could receive requests, but as soon as
468 // that's `false` we're out of here.
469 while !lock
.producer_done
{
470 // If no one's requested a token then we wait for someone to
472 if lock
.requests
== 0 {
473 lock
= self.cvar
.wait(lock
).unwrap_or_else(|e
| e
.into_inner());
477 // Consume the request for a token, and then actually acquire a
478 // token after unlocking our lock (not that acquisition happens in
479 // `f`). This ensures that we don't actually hold the lock if we
480 // wait for a long time for a token.
486 lock
.consumer_done
= true;
487 self.cvar
.notify_one();
490 fn producer_done(&self) -> bool
{
491 self.lock().producer_done
496 fn no_helper_deadlock() {
497 let x
= crate::Client
::new(32).unwrap();
499 std
::mem
::drop(x
.into_helper_thread(|_
| {}
).unwrap());