refactor(linter): always explicitly initialize Rayon thread pool (#13122)

Previously we only explicitly initialized the global Rayon thread pool if `--threads` option is specified.

Instead, do it unconditionally, and always specify thread count. The purpose is to obtain a guarantee that `rayon::current_num_threads()` will always return the same number during the rest of the linter's work.

This invariant is not relied upon currently, but will become critical for soundness once we run JS plugins on multiple threads.

Also, if `std::thread::available_parallelism()` is not able to obtain CPU core count, log a warning that the linter will run single-threaded. Previously Rayon would use only a single thread, but would make that decision silently. I'm not sure in what circumstances `available_parallelism()` can return `Err`, but if it does, the user will probably want to know about it.

Author: overlookmotel

apps/oxlint/src/command/lint.rs

@@ -60,13 +60,45 @@ pub struct LintCommand {
 
 impl LintCommand {
     pub fn handle_threads(&self) {
-        Self::set_rayon_threads(self.misc_options.threads);
+        Self::init_rayon_thread_pool(self.misc_options.threads);
     }
 
-    fn set_rayon_threads(threads: Option<usize>) {
-        if let Some(threads) = threads {
-            rayon::ThreadPoolBuilder::new().num_threads(threads).build_global().unwrap();
-        }
+    /// Initialize Rayon global thread pool with specified number of threads.
+    ///
+    /// If `--threads` option is not used, or `--threads 0` is given,
+    /// default to the number of available CPU cores.
+    #[expect(clippy::print_stderr)]
+    fn init_rayon_thread_pool(threads: Option<usize>) {
+        // Always initialize thread pool, even if using default thread count,
+        // to ensure thread pool's thread count is locked after this point.
+        // `rayon::current_num_threads()` will always return the same number after this point.
+        //
+        // If you don't initialize the global thread pool explicitly, or don't specify `num_threads`,
+        // Rayon will initialize the thread pool when it's first used, with a thread count of
+        // `std::thread::available_parallelism()`, and that thread count won't change thereafter.
+        // So we don't *need* to initialize the thread pool here if we just want the default thread count.
+        //
+        // However, Rayon's docs state that:
+        // > In the future, the default behavior may change to dynamically add or remove threads as needed.
+        // https://docs.rs/rayon/1.11.0/rayon/struct.ThreadPoolBuilder.html#method.num_threads
+        //
+        // To ensure we continue to have a "locked" thread count, even after future Rayon upgrades,
+        // we always initialize the thread pool and explicitly specify thread count here.
+
+        let thread_count = if let Some(thread_count) = threads
+            && thread_count > 0
+        {
+            thread_count
+        } else if let Ok(thread_count) = std::thread::available_parallelism() {
+            thread_count.get()
+        } else {
+            eprintln!(
+                "Unable to determine available thread count. Defaulting to 1.\nConsider specifying the number of threads explicitly with `--threads` option."
+            );
+            1
+        };
+
+        rayon::ThreadPoolBuilder::new().num_threads(thread_count).build_global().unwrap();
     }
 }
 

crates/oxc_linter/src/service/runtime.rs

@@ -241,6 +241,26 @@ use message_cloner::MessageCloner;
 
 impl Runtime {
     pub(super) fn new(linter: Linter, options: LintServiceOptions) -> Self {
+        // If global thread pool wasn't already initialized, do it now.
+        // This "locks" config for the thread pool, which ensures `rayon::current_num_threads()`
+        // cannot change from now on.
+        //
+        // Initializing the thread pool without specifying `num_threads` produces a threadpool size
+        // based on `std::thread::available_parallelism`. However, Rayon's docs state that:
+        // > In the future, the default behavior may change to dynamically add or remove threads as needed.
+        // https://docs.rs/rayon/1.11.0/rayon/struct.ThreadPoolBuilder.html#method.num_threads
+        //
+        // However, I (@overlookmotel) assume that would be considered a breaking change,
+        // so we don't have to worry about it until Rayon v2.
+        // When Rayon v2 is released and we upgrade to it, we'll need to revisit this and make sure
+        // we still guarantee that thread count is locked.
+        //
+        // If thread pool was already initialized, this won't do anything.
+        // `build_global` will return `Err` in that case, but we can ignore it.
+        // That just means the config (and so number of threads) is already locked.
+        // https://docs.rs/rayon/1.11.0/rayon/struct.ThreadPoolBuilder.html#method.build_global
+        let _ = rayon::ThreadPoolBuilder::new().build_global();
+
         let thread_count = rayon::current_num_threads();
         let allocator_pool = AllocatorPool::new(thread_count);