Add: New metadata APIs for C

Author: ashvardanian

c/lib.cpp

@@ -143,7 +143,9 @@ size_t fu_count_quality_levels(void) {
     return 1; // TODO: One day I'll get some of those weird CPUs to do this
 }
 
-size_t fu_volume_huge_pages(size_t numa_node_index) {
+size_t fu_volume_any_pages(void) { return fu::get_ram_total_volume(); }
+
+size_t fu_volume_huge_pages_in(size_t numa_node_index) {
 #if FU_ENABLE_NUMA
     size_t total_volume = 0;
     auto const &node = global_numa_topology.node(numa_node_index);
@@ -154,13 +156,13 @@ size_t fu_volume_huge_pages(size_t numa_node_index) {
 #endif
 }
 
-size_t fu_volume_any_pages(size_t numa_node_index) {
+size_t fu_volume_any_pages_in(size_t numa_node_index) {
 #if FU_ENABLE_NUMA
     if (!globals_initialize()) return 0;
     if (numa_node_index >= global_numa_topology.nodes_count()) return 0;
 
     auto const &node = global_numa_topology.node(numa_node_index);
-    return node.total_memory_bytes();
+    return node.memory_size;
 #else
     return fu::get_ram_total_volume();
 #endif
@@ -348,9 +350,8 @@ size_t fu_pool_count_threads_in(fu_pool_t *pool, size_t colocation_index) {
 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);
+    return std::visit([=](auto &variant) { return variant.thread_local_index(global_thread_index, colocation_index); },
+                      opaque->variants);
 }
 
 #pragma endregion - Lifetime

include/fork_union.h

@@ -153,7 +153,6 @@ typedef enum fu_caller_exclusivity_t {
  *  @retval "numa+x86_tpause" for the NUMA-aware pool with `tpause` instruction with "waitpkg" CPU feature.
  *  @retval "numa+arm64_wfet" for the NUMA-aware pool with `wfet` instruction on AArch64.
  *  @retval "numa+risc5_pause" for the NUMA-aware pool with `pause` instruction on RISC-V.
- *  @note This API is @b not synchronized and should be called once during initialization.
  *
  *  The string describes both the memory topology awareness and the CPU-specific optimizations
  *  available for busy-waiting. These capabilities directly affect performance characteristics:
@@ -167,7 +166,6 @@ char const *fu_capabilities_string(void);
  *  @brief Describes the number of logical CPU cores available on the system.
  *  @retval 0 if the thread pool is not supported on the current platform or detection failed.
  *  @retval 1-N where N is the number of logical cores detected by the OS.
- *  @note This API is @b not synchronized and should be called once during initialization.
  *
  *  On x86 systems with hyper-threading enabled, this will be 2x the number of physical cores.
  *  On ARM big.LITTLE architectures, this includes both performance and efficiency cores.
@@ -186,7 +184,6 @@ size_t fu_count_logical_cores(void);
  *  @retval 1 on most desktop, laptop, or IoT platforms with unified memory.
  *  @retval 2-8 on typical dual-socket servers or heterogeneous mobile chips.
  *  @retval 4-32 is a typical range on high-end cloud servers with multiple sockets.
- *  @note This API is @b not synchronized and should be called once during initialization.
  *
  *  A "colocation" represents a group of threads that share the same:
  *  - NUMA memory domain (fast local memory access)
@@ -205,7 +202,6 @@ size_t fu_count_colocations(void);
  *  @retval 1 on systems with uniform memory access (UMA).
  *  @retval 2-8 on typical multi-socket servers.
  *  @retval 8+ on high-end systems with complex topologies.
- *  @note This API is @b not synchronized and should be called once during initialization.
  *
  *  NUMA nodes represent distinct memory domains with different access latencies.
  *  Memory allocated on the local NUMA node is typically 2-3x faster to access
@@ -220,19 +216,36 @@ size_t fu_count_numa_nodes(void);
  *  @retval 0 if QoS detection is not supported.
  *  @retval 1 on systems with homogeneous cores.
  *  @retval 2-3 on systems with heterogeneous cores (e.g., ARM big.LITTLE, Intel P+E cores).
- *  @note This API is @b not synchronized and should be called once during initialization.
  *
  *  Different QoS levels may have vastly different performance characteristics.
  *  Consider creating separate thread pools for different workload types.
  */
 size_t fu_count_quality_levels(void);
 
+/**
+ *  @brief Returns the total volume of any pages (huge or regular) available across all NUMA nodes.
+ *  @retval Number of bytes of memory pages available across all NUMA nodes.
+ */
+size_t fu_volume_any_pages(void);
+
+/**
+ *  @brief Returns the volume of any pages (huge or regular) available on the specified NUMA node.
+ *  @param[in] numa_node_index The index of the NUMA node to query, in [0, numa_nodes_count).
+ *  @retval 0 if the NUMA node index is invalid or if no memory is available.
+ *  @retval Number of bytes of memory pages available on the specified NUMA node.
+ *
+ *  This function queries the operating system for the total amount of memory pages
+ *  (both huge pages and regular pages) available for allocation on the specified NUMA node.
+ *  This is useful for determining how much memory can be allocated for vector storage
+ *  based on a percentage of available memory.
+ */
+size_t fu_volume_any_pages_in(size_t numa_node_index);
+
 /**
  *  @brief Describes the number of different huge page sizes supported.
  *  @param[in] numa_node_index The index of the NUMA node to allocate memory on, in [0, numa_nodes_count).
  *  @retval 0 if huge pages are not supported or not available.
  *  @retval 1-4 on systems with huge page support (typically 2MB, 1GB sizes).
- *  @note This API is @b not synchronized and should be called once during initialization.
  *
  *  Huge pages reduce TLB (Translation Lookaside Buffer) pressure by using larger
  *  page sizes than the standard 4KB. This can significantly improve performance
@@ -244,21 +257,7 @@ size_t fu_count_quality_levels(void);
  *  - 16KB/64KB: Base page sizes on some ARM configurations
  *  @sa `fu_allocate_at_least` for NUMA-aware allocation with huge page support.
  */
-size_t fu_volume_huge_pages(size_t numa_node_index);
-
-/**
- *  @brief Returns the volume of any pages (huge or regular) available on the specified NUMA node.
- *  @param[in] numa_node_index The index of the NUMA node to query, in [0, numa_nodes_count).
- *  @retval 0 if the NUMA node index is invalid or if no memory is available.
- *  @retval Number of bytes of memory pages available on the specified NUMA node.
- *  @note This API is @b not synchronized and should be called once during initialization.
- *
- *  This function queries the operating system for the total amount of memory pages
- *  (both huge pages and regular pages) available for allocation on the specified NUMA node.
- *  This is useful for determining how much memory can be allocated for vector storage
- *  based on a percentage of available memory.
- */
-size_t fu_volume_any_pages(size_t numa_node_index);
+size_t fu_volume_huge_pages_in(size_t numa_node_index);
 
 #pragma endregion - Metadata