Add SCX scheduling option for freebyrd T1 decode (Phase 3)

When GRK_USE_SCX_SCHEDULING=ON, freebyrd uses sicorax's Rust-based
scx_parallel_for for T1 block decoding instead of TaskFlow. The SCX
path produces bit-identical output to the TaskFlow path.

CMake integration finds the pre-built libscx_scheduling.a static lib
and links it with pthread/dl on Linux.

Author: Grok Compression

CMakeLists.txt

@@ -211,6 +211,30 @@ option(GRK_BUILD_CODEC "Build the CODEC executables" ON)
 option(GRK_BUILD_PLUGIN_LOADER "Enable loading of T1 plugin" OFF)
 mark_as_advanced(GRK_BUILD_PLUGIN_LOADER)
 
+# Sicorax Rust scheduling library (used by freebyrd scheduler)
+option(GRK_USE_SCX_SCHEDULING "Link sicorax Rust scheduling library for freebyrd scheduler" OFF)
+if(GRK_USE_SCX_SCHEDULING)
+  set(SCX_SCHEDULING_DIR "${CMAKE_SOURCE_DIR}/../sicorax" CACHE PATH "Path to sicorax source tree")
+  set(SCX_SCHEDULING_LIB "${SCX_SCHEDULING_DIR}/crates/scx-scheduling/target/release/libscx_scheduling.a")
+  if(NOT EXISTS "${SCX_SCHEDULING_LIB}")
+    message(STATUS "Building sicorax scx-scheduling Rust crate...")
+    execute_process(
+      COMMAND cargo build --release
+      WORKING_DIRECTORY "${SCX_SCHEDULING_DIR}/crates/scx-scheduling"
+      RESULT_VARIABLE SCX_BUILD_RESULT
+    )
+    if(NOT SCX_BUILD_RESULT EQUAL 0)
+      message(FATAL_ERROR "Failed to build scx-scheduling Rust crate")
+    endif()
+  endif()
+  add_library(scx_scheduling STATIC IMPORTED)
+  set_target_properties(scx_scheduling PROPERTIES IMPORTED_LOCATION "${SCX_SCHEDULING_LIB}")
+  # Rust static libs on Linux need pthread and dl
+  if(UNIX AND NOT APPLE)
+    set_target_properties(scx_scheduling PROPERTIES INTERFACE_LINK_LIBRARIES "pthread;dl")
+  endif()
+endif()
+
 set(SPDLOG_INSTALL OFF CACHE BOOL "" FORCE)
 set(SPDLOG_BUILD_EXAMPLE OFF CACHE BOOL "" FORCE)
 set(SPDLOG_BUILD_TESTS OFF CACHE BOOL "" FORCE)

src/lib/core/CMakeLists.txt

@@ -276,6 +276,11 @@ if(UNIX)
   target_link_libraries(${GROK_CORE_NAME} PUBLIC ${CMAKE_THREAD_LIBS_INIT})
 endif(UNIX)
 target_link_libraries(${GROK_CORE_NAME} PRIVATE hwy ${LCMS_LIBNAME})
+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)
+endif()
 if(GRK_ENABLE_LIBCURL AND GRK_HAVE_LIBCURL)
   target_link_libraries(${GROK_CORE_NAME} PRIVATE ${GRK_CURL_TARGET})
   target_include_directories(${GROK_CORE_NAME} PRIVATE

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

@@ -63,6 +63,10 @@ struct ITileProcessor;
 #include "TileBlocks.h"
 #include "SchedulerStandard.h"
 #include "ImageComponentFlow.h"
+#ifdef GRK_USE_SCX_SCHEDULING
+#include "scx_scheduling_ffi.h"
+#include <unordered_map>
+#endif
 #include "SchedulerFreebyrd.h"
 
 namespace grk
@@ -234,6 +238,65 @@ bool SchedulerFreebyrd::decodeBlocks(ITileProcessor* tileProcessor)
   if(allBlocks.empty())
     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.
+  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)
+    {
+      return ((uint32_t)cblkwExpn << 16) | (uint32_t)cblkhExpn;
+    }
+
+    static void decode(size_t i, size_t thread_id, void* ud)
+    {
+      auto* c = static_cast<ParallelDecodeCtx*>(ud);
+      if(!c->self->success_)
+        return;
+      try
+      {
+        auto& block = (*c->blocks)[i];
+        auto& bctx = (*c->contexts)[i];
+        t1::ICoder* coder = nullptr;
+        if(block->needsCachedCoder())
+        {
+          coder = t1::CoderFactory::makeCoder(bctx.isHT, false, bctx.cbw, bctx.cbh,
+                                              bctx.tileCacheStrategy);
+        }
+        else if(!bctx.cacheAll)
+        {
+          auto key = coderKey(bctx.cblkwExpn, bctx.cblkhExpn);
+          auto& coderMap = c->threadCoders[thread_id];
+          auto it = coderMap.find(key);
+          if(it == coderMap.end())
+          {
+            auto newCoder = std::shared_ptr<t1::ICoder>(t1::CoderFactory::makeCoder(
+                bctx.isHT, false, bctx.cbw, bctx.cbh, bctx.tileCacheStrategy));
+            it = coderMap.emplace(key, std::move(newCoder)).first;
+          }
+          coder = it->second.get();
+        }
+        if(!block->open(coder))
+          c->self->success_ = false;
+      }
+      catch(...)
+      {
+        c->self->success_ = false;
+      }
+    }
+  };
+  ParallelDecodeCtx ctx{this, &allBlocks, &blockContexts, {}};
+  ctx.threadCoders.resize(num_threads);
+  scx_parallel_for(allBlocks.size(), num_threads, ParallelDecodeCtx::decode, &ctx);
+#else
   // Decode all blocks in parallel using TaskFlow
   tf::Taskflow taskflow;
   for(size_t i = 0; i < allBlocks.size(); ++i)
@@ -267,6 +330,7 @@ bool SchedulerFreebyrd::decodeBlocks(ITileProcessor* tileProcessor)
     });
   }
   TFSingleton::get().run(taskflow).wait();
+#endif
 
   return success_;
 }