Improve: Steer Apple efficiency-core pools via QoS

A colocated_pool spawned on an efficiency domain now asks for
QOS_CLASS_UTILITY - Darwin's only lever that actually places threads on
E-cores. The dense compute_level cannot make that call alone: the bottom
rank is E-cores on an A18 but big cores on an M5 Pro, so the harvest now
keeps each perflevel's absolute class, parsed from hw.perflevelN.name
into the new apple_core_quality field. The whole kit - parser, field,
and consumer - is gated on FU_WITH_PLACE_THREADS_BY_CORE_CLASS, so
turning the capability off erases it together.

The iOS CI job now also links and runs the test suite on a booted
simulator across an sdk x std matrix, instead of stopping at the
device-SDK compile.

.github/workflows/prerelease.yml

@@ -644,26 +644,39 @@ jobs:
       - name: Test Zig (portable)
         run: zig build test -Dportable=true
 
-  # iOS shares Darwin's `pthread_attr_set_qos_class_np` and `hw.perflevel*`, and shares its refusal
-  # to pin. Compiling for the device and for the simulator is enough to keep those paths honest;
-  # running is not, because a simulator binary reads the *host* Mac's topology, not a phone's.
+  # iOS shares Darwin's QoS scheduling and `hw.perflevel*` topology, and shares its refusal to pin.
+  # The device SDK is compile-only - a phone can't run on the CI host - but the simulator binary is
+  # linked and run on a booted simulator. A simulator reads the *host* Mac's topology, so this proves
+  # the Apple path under the iOS ABI, not any particular phone's layout.
   build_ios:
-    name: iOS (Compile Only)
+    name: iOS (${{ matrix.sdk }}, ${{ matrix.std }})
     runs-on: macos-15
     strategy:
       fail-fast: false
       matrix:
         sdk: [iphoneos, iphonesimulator]
+        std: [c++17, c++20]
+        include:
+          - { sdk: iphoneos, triple: arm64-apple-ios17.0 }
+          - { sdk: iphonesimulator, triple: arm64-apple-ios17.0-simulator }
     steps:
       - name: Checkout
         uses: actions/checkout@v5
 
-      - name: Build C++ for ${{ matrix.sdk }}
+      - name: Compile the C++ test and the C shim
         run: |
           SYSROOT=$(xcrun --sdk ${{ matrix.sdk }} --show-sdk-path)
-          if [ "${{ matrix.sdk }}" = "iphoneos" ]; then TARGET=arm64-apple-ios17.0; \
-          else TARGET=arm64-apple-ios17.0-simulator; fi
-          clang++ -std=c++20 -O2 -Wall -Wextra -Werror -target $TARGET -isysroot "$SYSROOT" \
-            -Iinclude -c scripts/test.cpp -o test_ios.o
-          clang++ -std=c++17 -O2 -Wall -Wextra -Werror -target $TARGET -isysroot "$SYSROOT" \
-            -Iinclude -c c/forkunion.cpp -o forkunion_ios.o
+          clang++ -std=${{ matrix.std }} -O2 -Wall -Wextra -Werror -target ${{ matrix.triple }} \
+            -isysroot "$SYSROOT" -Iinclude scripts/test.cpp -o forkunion_test_ios
+          clang++ -std=${{ matrix.std }} -O2 -Wall -Wextra -Werror -target ${{ matrix.triple }} \
+            -isysroot "$SYSROOT" -Iinclude -c c/forkunion.cpp -o forkunion_ios.o
+
+      # GitHub's macOS images pre-create simulators for their Xcode; boot the first iPhone, don't mint one.
+      - name: Run the C++ test on the iOS Simulator
+        if: matrix.sdk == 'iphonesimulator'
+        run: |
+          DEVICE_ID=$(xcrun simctl list devices available iPhone \
+            | grep -oE "[0-9A-F-]{36}" | head -1)
+          test -n "$DEVICE_ID"
+          xcrun simctl boot "$DEVICE_ID"
+          xcrun simctl spawn "$DEVICE_ID" "$PWD/forkunion_test_ios"

include/forkunion/distributed.hpp

@@ -75,8 +75,11 @@ struct alignas(default_alignment_k) pinned_thread_t {
     core_id_t core_id {-1};
     /** @brief Thread name, written by the spawner and applied by the worker to itself. */
     char name[16] {};
-    /** @brief QoS class of this worker's core. @todo Populate from VFS, if available. */
-    core_quality_t core_quality {-1};
+#if FU_WITH_PLACE_THREADS_BY_CORE_CLASS
+    /** @brief Apple's absolute class for this worker's domain, or -1 when unnamed.
+     *  @sa `compute_domain_t::apple_core_quality`, copied here at spawn. */
+    core_quality_t apple_core_quality {-1};
+#endif
     /**
      *  @brief This thread's private cursor for `for_n_dynamic`. @sa `dynamic_claim`.
      *  @note Lives here, rather than in a second array, so the pool allocates once and the cursor
@@ -365,6 +368,9 @@ struct colocated_pool {
             pthreads_[0].handle.store(::pthread_self(), std::memory_order_release);
 #endif
             pthreads_[0].id.store(current_thread_id(), std::memory_order_release);
+#if FU_WITH_PLACE_THREADS_BY_CORE_CLASS
+            pthreads_[0].apple_core_quality = domain.apple_core_quality;
+#endif
         }
 
         // The startup sequence for the POSIX threads differs from the `flat_pool`,
@@ -396,14 +402,17 @@ struct colocated_pool {
             // Apple offers no pinning; a Quality-of-Service class is the whole placement story, and
             // it must be chosen before the thread exists. On a chip with efficiency cores, `UTILITY`
             // is what confines a thread to them; on an all-performance chip the class is inert.
-            ::pthread_attr_set_qos_class_np(&attributes, _qos_for_level(domain.compute_level, compute_levels), 0);
+            ::pthread_attr_set_qos_class_np(&attributes, _qos_for_domain(domain, compute_levels), 0);
 #endif
             created = ::pthread_create(&new_pthread_handle, &attributes, &_posix_worker_loop, this) == 0;
             ::pthread_attr_destroy(&attributes);
             pthreads_[i].handle.store(new_pthread_handle, std::memory_order_relaxed);
             pthreads_[i].id.store(0, std::memory_order_relaxed); // ? 0 means "not published yet"
 #endif
             pthreads_[i].core_id = -1; // ? Not pinned yet
+#if FU_WITH_PLACE_THREADS_BY_CORE_CLASS
+            pthreads_[i].apple_core_quality = domain.apple_core_quality;
+#endif
 
             if (!created) {
                 mood_.store(mood_t::die_k, std::memory_order_release);
@@ -876,24 +885,22 @@ struct colocated_pool {
 
 #if FU_WITH_PLACE_THREADS_BY_CORE_CLASS
     /**
-     *  @brief Maps a compute level onto the only placement control Darwin offers.
-     *  @param[in] level The domain's `compute_level`, where higher is more performant.
+     *  @brief Maps a compute domain onto the only placement control Darwin offers: a QoS class.
      *  @param[in] levels Distinct levels the machine reports; 1 means every core is interchangeable.
      *
-     *  The top tier asks for `USER_INITIATED`, not `USER_INTERACTIVE`: the latter is reserved for work
-     *  a person is waiting on, and a compute pool is not that. Everything below it takes `DEFAULT`.
-     *
-     *  @note It is tempting to give the bottom tier `QOS_CLASS_UTILITY`, which is what confines a
-     *        thread to efficiency cores. That is wrong here. `compute_level` is a dense rank over
-     *        `hw.perflevelN`, and the bottom rank is only an @b efficiency tier on the chips that have
-     *        one. An M5 Pro reports two levels named "Super" and "Performance", both big cores - and
-     *        `UTILITY` would deprioritize two thirds of the machine. Telling the two cases apart needs
-     *        `hw.perflevelN.name`, which the harvest does not yet keep.
+     *  The fastest tier present runs the hot path at `USER_INITIATED` - not `USER_INTERACTIVE`, which
+     *  is reserved for work a person is waiting on. Below it, only a tier the OS names "Efficiency"
+     *  takes `UTILITY`, the class that confines threads to E-cores. The rank alone cannot decide that:
+     *  the bottom rank is E-cores on an A18 but big cores on an M5 Pro, where `UTILITY` would banish
+     *  two thirds of the machine. Checking rank first keeps an all-efficiency chip honest - its E-cores
+     *  are the fastest thing present. A hidden or unknown name parses to `apple_performance_k`, so the
+     *  fallback is rank-only and `UTILITY` is never guessed.
      */
-    static qos_class_t _qos_for_level(std::size_t const level, std::size_t const levels) noexcept {
-        if (levels <= 1) return QOS_CLASS_USER_INITIATED;
-        if (level + 1 == levels) return QOS_CLASS_USER_INITIATED; // ? The fastest tier this chip has
-        return QOS_CLASS_DEFAULT;
+    static qos_class_t _qos_for_domain(compute_domain_t const &domain, std::size_t const levels) noexcept {
+        if (domain.compute_level + 1 >= levels) return QOS_CLASS_USER_INITIATED; // ? The fastest tier present
+        if (domain.apple_core_quality == apple_efficiency_k)
+            return QOS_CLASS_UTILITY; // ? Genuine E-cores - confine here
+        return QOS_CLASS_DEFAULT;     // ? A slower big tier stays big
     }
 #endif
 

include/forkunion/topology.hpp

@@ -736,6 +736,16 @@ struct compute_domain_t {
     memory_domain_index_t memory_domain_index {};
     /** @brief QoS ordinal, sorted least-to-most performant. */
     std::size_t compute_level {0};
+#if FU_WITH_PLACE_THREADS_BY_CORE_CLASS
+    /**
+     *  @brief Apple's absolute class for these cores, from `hw.perflevelN.name`; -1 when unnamed.
+     *  @sa `colocated_pool`'s `_qos_for_domain`, for why the relative rank above cannot replace it.
+     *
+     *  Spawn-path plumbing, not a second caller-facing rank: like `first_core_id`, it is the raw
+     *  material the platform's placement call consumes - an affinity mask there, a QoS class here.
+     */
+    core_quality_t apple_core_quality {-1};
+#endif
     /**
      *  @brief Relative throughput of @b one core here; 0 when the platform exposes no rating.
      *  @sa `compute_level` is a dense ordinal for grouping - never divide by it.
@@ -1038,7 +1048,61 @@ FU_MAYBE_UNUSED_ static inline std::size_t apple_sysctl_uint(char const *name) n
     if (::sysctlbyname(name, &value, &length, nullptr, 0) != 0) return 0;
     return static_cast<std::size_t>(value);
 }
-#endif
+#endif // FU_ON_APPLE
+
+/*  The core-quality kit exists for one consumer - the QoS class a `colocated_pool` assigns at spawn -
+ *  so it is gated on that capability: turning it off erases producer, field, and consumer together. */
+#if FU_WITH_PLACE_THREADS_BY_CORE_CLASS
+/** @brief Reads a string `sysctl` by name into @p out (always NUL-terminated), returning success. */
+FU_MAYBE_UNUSED_ static inline bool apple_sysctl_string(char const *name, char *out, std::size_t cap) noexcept {
+    if (cap == 0) return false;
+    std::size_t length = cap;
+    if (::sysctlbyname(name, out, &length, nullptr, 0) != 0) {
+        out[0] = '\0';
+        return false;
+    }
+    // ? A value that exactly filled the buffer arrives unterminated
+    out[cap - 1] = '\0';
+    return true;
+}
+
+/**
+ *  @brief Apple's `hw.perflevelN.name` vocabulary as an @b absolute ladder; higher is more performant.
+ *  @note Absolute, unlike `compute_level`: "Performance" is the same class on an M1 (its top tier)
+ *        and an M5 Pro (its bottom). Apple has shipped exactly these three names.
+ */
+enum apple_core_quality_t : core_quality_t {
+    apple_efficiency_k = 0,  // "Efficiency" - the only tier that is physically E-cores
+    apple_performance_k = 1, // "Performance"
+    apple_super_k = 2,       // "Super" - the M5-era top tier, still a big core
+};
+
+/**
+ *  @brief The name Apple gives an absolute core class, or `nullptr` for an unknown one.
+ *  @note The one source of truth for the names; `apple_core_quality_from_name` inverts it.
+ */
+FU_MAYBE_UNUSED_ static inline char const *apple_core_quality_name(core_quality_t const quality) noexcept {
+    switch (quality) {
+    case apple_efficiency_k: return "Efficiency";
+    case apple_performance_k: return "Performance";
+    case apple_super_k: return "Super";
+    default: return nullptr;
+    }
+}
+
+/**
+ *  @brief Maps a `hw.perflevelN.name` to its absolute class; inverts `apple_core_quality_name`.
+ *  @retval apple_performance_k for a null or unrecognised name, so `UTILITY` is never guessed.
+ */
+FU_MAYBE_UNUSED_ static inline core_quality_t apple_core_quality_from_name(char const *name) noexcept {
+    if (name == nullptr) return apple_performance_k;
+    for (core_quality_t quality = apple_efficiency_k; quality <= apple_super_k; ++quality) {
+        char const *const candidate = apple_core_quality_name(quality);
+        if (candidate != nullptr && std::strcmp(candidate, name) == 0) return quality;
+    }
+    return apple_performance_k;
+}
+#endif // FU_WITH_PLACE_THREADS_BY_CORE_CLASS
 
 /**
  *  @brief NUMA topology descriptor: describing memory pools and core counts next to them.
@@ -1548,6 +1612,15 @@ struct machine_topology {
             // ? A level with no `cpusperl2` is one undivided cluster, not zero-sized ones.
             if (cores_per_cluster == 0 || cores_per_cluster > level_cores) cores_per_cluster = level_cores;
 
+#if FU_WITH_PLACE_THREADS_BY_CORE_CLASS
+            // The absolute class the QoS choice keys on; a hidden name (a locked-down sandbox)
+            // parses to a big tier, never to efficiency cores.
+            std::snprintf(name, sizeof(name), "hw.perflevel%zu.name", level);
+            char level_name[32];
+            apple_sysctl_string(name, level_name, sizeof(level_name));
+            core_quality_t const level_quality = apple_core_quality_from_name(level_name);
+#endif
+
             std::size_t const level_rank = nonempty_levels - 1 - levels_written;
             for (std::size_t cut = 0; cut < level_cores; cut += cores_per_cluster) {
                 std::size_t const cluster_cores = (level_cores - cut) < cores_per_cluster //
@@ -1557,6 +1630,9 @@ struct machine_topology {
                 domain.memory_domain_id = 0;
                 domain.memory_domain_index = static_cast<memory_domain_index_t>(0);
                 domain.compute_level = level_rank; // ? Sibling clusters share their level's rank
+#if FU_WITH_PLACE_THREADS_BY_CORE_CLASS
+                domain.apple_core_quality = level_quality;
+#endif
                 domain.capacity = 0;
                 domain.cache_bytes = level_cache_bytes; // ? L2 is private to the cluster, shared within it
                 domain.first_core_id = core_ids_ptr + core_offset + cut;