Add: locate_thread_in for C and Rust

It helps determine the local thread rank in a larger distributed system

Author: ashvardanian

c/lib.cpp

@@ -345,6 +345,14 @@ size_t fu_pool_count_threads_in(fu_pool_t *pool, size_t colocation_index) {
     return std::visit([=](auto &variant) { return variant.threads_count(colocation_index); }, opaque->variants);
 }
 
+size_t fu_pool_locate_thread_in(fu_pool_t *pool, size_t global_thread_index, size_t colocation_index) {
+    assert(pool != nullptr);
+    opaque_pool_t *opaque = reinterpret_cast<opaque_pool_t *>(pool);
+    return std::visit([=](auto &variant) { 
+        return variant.thread_local_index(global_thread_index, colocation_index);
+    }, opaque->variants);
+}
+
 #pragma endregion - Lifetime
 
 #pragma region - Primary API

include/fork_union.h

@@ -481,6 +481,15 @@ size_t fu_pool_count_threads(fu_pool_t *pool);
  */
 size_t fu_pool_count_threads_in(fu_pool_t *pool, size_t colocation_index);
 
+/**
+ *  @brief Converts a global thread index to a local thread index within a colocation.
+ *  @param[in] pool Thread pool handle, must not be NULL.
+ *  @param[in] global_thread_index The global thread index to convert.
+ *  @param[in] colocation_index Index of the colocation, must be < `fu_pool_count_colocations(pool)`.
+ *  @retval Local thread index within the specified colocation.
+ */
+size_t fu_pool_locate_thread_in(fu_pool_t *pool, size_t global_thread_index, size_t colocation_index);
+
 #pragma endregion - Lifetime
 
 #pragma region - Primary API

rust/lib.rs

@@ -353,6 +353,7 @@ extern "C" {
     fn fu_pool_count_threads(pool: *mut c_void) -> usize;
     fn fu_pool_count_colocations(pool: *mut c_void) -> usize;
     fn fu_pool_count_threads_in(pool: *mut c_void, colocation_index: usize) -> usize;
+    fn fu_pool_locate_thread_in(pool: *mut c_void, global_thread_index: usize, colocation_index: usize) -> usize;
 
     #[allow(dead_code)]
     fn fu_pool_for_threads(
@@ -683,6 +684,24 @@ impl ThreadPool {
         unsafe { fu_pool_count_threads_in(self.inner, colocation_index) }
     }
 
+    /// Converts a global thread index to a local thread index within a colocation.
+    ///
+    /// This is useful for distributed thread pools where threads are grouped into
+    /// colocations (NUMA nodes or QoS levels). The local index can be used for
+    /// per-colocation data structures or algorithms.
+    ///
+    /// # Arguments
+    ///
+    /// * `global_thread_index` - The global thread index to convert
+    /// * `colocation_index` - The colocation to get the local index for
+    ///
+    /// # Returns
+    ///
+    /// The local thread index within the specified colocation.
+    pub fn locate_thread_in(&self, global_thread_index: usize, colocation_index: usize) -> usize {
+        unsafe { fu_pool_locate_thread_in(self.inner, global_thread_index, colocation_index) }
+    }
+
     /// Transitions worker threads to a power-saving sleep state.
     ///
     /// This function places worker threads into a low-power sleep state when no work