feat(freebyrd): use ScxEngine persistent thread pool for T1 decode

Replace scx_parallel_for (which spawns/joins threads per tile) with
ScxEngineSingleton — a persistent worker pool that stays alive for the
lifetime of the process. This eliminates thread spawn/join overhead
when decoding multiple tiles.

Changes:
- Add ScxEngineSingleton: global wrapper around Rust ScxEngine
- decodeBlocks() now submits T1 jobs via scx_engine_submit_batch()
  and runs them with scx_engine_run()
- CMake: conditionally compile ScxEngineSingleton.cpp when
  GRK_USE_SCX_SCHEDULING is ON

The engine creates domains (currently 'T1') with sequence-based
ordering, laying the groundwork for Phase 2 where DWT will also be
submitted to the engine for natural T1/DWT interleaving.

Author: Grok Compression

src/lib/core/CMakeLists.txt

@@ -280,6 +280,8 @@ if(GRK_USE_SCX_SCHEDULING)
   target_link_libraries(${GROK_CORE_NAME} PRIVATE scx_scheduling)
   target_include_directories(${GROK_CORE_NAME} PRIVATE "${SCX_SCHEDULING_DIR}/src/scheduling")
   target_compile_definitions(${GROK_CORE_NAME} PRIVATE GRK_USE_SCX_SCHEDULING)
+  target_sources(${GROK_CORE_NAME} PRIVATE
+    ${CMAKE_CURRENT_SOURCE_DIR}/scheduling/freebyrd/ScxEngineSingleton.cpp)
 endif()
 if(GRK_ENABLE_LIBCURL AND GRK_HAVE_LIBCURL)
   target_link_libraries(${GROK_CORE_NAME} PRIVATE ${GRK_CURL_TARGET})

src/lib/core/scheduling/freebyrd/SchedulerFreebyrd.cpp

@@ -65,6 +65,7 @@ struct ITileProcessor;
 #include "ImageComponentFlow.h"
 #ifdef GRK_USE_SCX_SCHEDULING
 #include "scx_scheduling_ffi.h"
+#include "ScxEngineSingleton.h"
 #include <unordered_map>
 #endif
 #include "SchedulerFreebyrd.h"
@@ -244,16 +245,13 @@ bool SchedulerFreebyrd::decodeBlocks(ITileProcessor* tileProcessor)
     return true;
 
 #ifdef GRK_USE_SCX_SCHEDULING
-  // Decode all blocks in parallel using sicorax Rust scheduler.
-  // We create local coders per-thread to avoid races with the shared CoderPool,
-  // since multiple tiles may call runDecompressT1() concurrently from different
-  // TF workers, and scx_parallel_for spawns its own threads.
+  // Decode all blocks in parallel using ScxEngine persistent thread pool.
+  // Per-thread coder maps avoid races with the shared CoderPool.
   struct ParallelDecodeCtx
   {
     SchedulerFreebyrd* self;
     std::vector<std::shared_ptr<t1::DecompressBlockExec>>* blocks;
     std::vector<BlockDecodeContext>* contexts;
-    // One coder per thread, keyed by {cblkwExpn, cblkhExpn}
     std::vector<std::unordered_map<uint32_t, std::shared_ptr<t1::ICoder>>> threadCoders;
 
     static uint32_t coderKey(uint8_t cblkwExpn, uint8_t cblkhExpn)
@@ -298,9 +296,18 @@ bool SchedulerFreebyrd::decodeBlocks(ITileProcessor* tileProcessor)
       }
     }
   };
+
+  auto* engine = ScxEngineSingleton::get();
+  // Use a thread-local domain ID — create once, reuse across tiles
+  static uint32_t t1DomainId = scx_engine_create_domain(engine, "T1");
+
   ParallelDecodeCtx ctx{this, &allBlocks, &blockContexts, {}};
   ctx.threadCoders.resize(num_threads);
-  scx_parallel_for(allBlocks.size(), num_threads, ParallelDecodeCtx::decode, &ctx);
+
+  scx_engine_reset_domain(engine, t1DomainId);
+  scx_engine_submit_batch(engine, t1DomainId, 0, allBlocks.size(),
+                          ParallelDecodeCtx::decode, &ctx);
+  scx_engine_run(engine);
 #else
   // Decode all blocks in parallel using TaskFlow
   tf::Taskflow taskflow;

src/lib/core/scheduling/freebyrd/ScxEngineSingleton.cpp

@@ -0,0 +1,21 @@
+/*
+ *    Copyright (C) 2016-2026 Grok Image Compression Inc.
+ *
+ *    This source code is free software: you can redistribute it and/or  modify
+ *    it under the terms of the GNU Affero General Public License, version 3,
+ *    as published by the Free Software Foundation.
+ *
+ *    This source code is distributed in the hope that it will be useful,
+ *    but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *    GNU Affero General Public License for more details.
+ *
+ *    You should have received a copy of the GNU Affero General Public License
+ *    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+#include "ScxEngineSingleton.h"
+
+ScxEngine* ScxEngineSingleton::instance_ = nullptr;
+std::mutex ScxEngineSingleton::mutex_;

src/lib/core/scheduling/freebyrd/ScxEngineSingleton.h

@@ -0,0 +1,78 @@
+/*
+ *    Copyright (C) 2016-2026 Grok Image Compression Inc.
+ *
+ *    This source code is free software: you can redistribute it and/or  modify
+ *    it under the terms of the GNU Affero General Public License, version 3,
+ *    as published by the Free Software Foundation.
+ *
+ *    This source code is distributed in the hope that it will be useful,
+ *    but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *    GNU Affero General Public License for more details.
+ *
+ *    You should have received a copy of the GNU Affero General Public License
+ *    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+#pragma once
+
+#include "scx_scheduling_ffi.h"
+#include <mutex>
+#include <cstdint>
+
+/**
+ * @class ScxEngineSingleton
+ * @brief Manages a global ScxEngine instance (persistent thread pool).
+ *
+ * Like TFSingleton, but wraps the Rust ScxEngine for domain-based scheduling.
+ * The engine is created once and reused across tiles to avoid thread spawn overhead.
+ */
+class ScxEngineSingleton
+{
+public:
+  /**
+   * @brief Creates singleton instance with specified thread count.
+   * @param numThreads Number of worker threads (0 = use all cores)
+   */
+  static void create(int32_t numThreads = 0)
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if(instance_)
+      return;
+    instance_ = scx_engine_create(numThreads);
+  }
+
+  /**
+   * @brief Gets the engine instance (creates with default thread count if null).
+   * @return Raw pointer to ScxEngine
+   */
+  static ScxEngine* get()
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if(!instance_)
+      instance_ = scx_engine_create(0);
+    return instance_;
+  }
+
+  /**
+   * @brief Destroys the engine singleton.
+   */
+  static void destroy()
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if(instance_)
+    {
+      scx_engine_destroy(instance_);
+      instance_ = nullptr;
+    }
+  }
+
+private:
+  ScxEngineSingleton() = default;
+  ScxEngineSingleton(const ScxEngineSingleton&) = delete;
+  ScxEngineSingleton& operator=(const ScxEngineSingleton&) = delete;
+
+  static ScxEngine* instance_;
+  static std::mutex mutex_;
+};