From 50c0221ca38cd8469d8875a68482e93bb5753e51 Mon Sep 17 00:00:00 2001 From: bjorn3 Date: Tue, 10 Nov 2020 10:31:39 +0100 Subject: [PATCH] Add some comments --- src/cargo/core/compiler/job_queue.rs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/cargo/core/compiler/job_queue.rs b/src/cargo/core/compiler/job_queue.rs index af68722bb50..e883ad3e601 100644 --- a/src/cargo/core/compiler/job_queue.rs +++ b/src/cargo/core/compiler/job_queue.rs @@ -162,14 +162,28 @@ impl std::fmt::Display for JobId { } } +/// A `JobState` is constructed by `JobQueue::run` and passed to `Job::run`. It includes everything +/// necessary to communicate between the main thread and the execution of the job. +/// +/// The job may execute on either a dedicated thread or the main thread. If the job executes on the +/// main thread, the `output` field must be set to prevent a deadlock. pub struct JobState<'a> { /// Channel back to the main thread to coordinate messages and such. + /// + /// When the `output` field is `Some`, care must be taken to avoid calling `push_bounded` on + /// the message queue to prevent a deadlock. messages: Arc>, /// Normally output is sent to the job queue with backpressure. When the job is fresh /// however we need to immediately display the output to prevent a deadlock as the /// output messages are processed on the same thread as they are sent from. `output` /// defines where to output in this case. + /// + /// Currently the `Shell` inside `Config` is wrapped in a `RefCell` and thus can't be passed + /// between threads. This means that it isn't possible for multiple output messages to be + /// interleaved. In the future, it may be wrapped in a `Mutex` instead. In this case + /// interleaving is still prevented as the lock would be held for the whole printing of an + /// output message. output: Option<&'a Config>, /// The job id that this state is associated with, used when sending