Skip to content

Add generalized CPU topology and affinity capabilities - #214

Open
Br3ach wants to merge 4 commits into
CauldronDevelopmentLLC:masterfrom
Br3ach:cpu-topology-affinity
Open

Br3ach wants to merge 4 commits into
CauldronDevelopmentLLC:masterfrom
Br3ach:cpu-topology-affinity

Conversation

@Br3ach

@Br3ach Br3ach commented Sep 29, 2026 •

Copy link
Copy Markdown

Builds on ac74f1d ("Better performance CPU detection. CPU affinity for subprocesses")

Extending that support into the more general CPU topology interface needed for the affinity/resource-group work I plan to add to the FAH client.

  • Adds ordered CPU performance classes instead of exposing only a single performance-CPU set.
  • Adds physical-core / SMT sibling topology (future use).
  • Adds getAvailableCPUs() to report the logical CPUs the current execution context can use.
  • Adds getCPUAffinityCapability() to distinguish hard affinity support from unsupported or future hint-only platforms.
  • Keeps the existing getPerformanceCPUs() / getPerformanceCPUCount() behavior for compatibility.
  • Keeps Windows limited to a single representable processor group, with guards for WOW64 / 32-bit affinity-mask folding.
  • Exposes Linux hybrid performance classes and SMT sibling relationships where the kernel provides the required topology data.
  • Leaves scheduling and allocation policy to the FAH client - cbang only reports topology and affinity capability.

@Br3ach
Br3ach force-pushed the cpu-topology-affinity branch 3 times, most recently from 31c40c9 to a94543e Compare October 3, 2026 18:14
@jcoffland
jcoffland force-pushed the cpu-topology-affinity branch from d15321f to 8acdbdf Compare October 5, 2026 12:44
@jcoffland

Copy link
Copy Markdown
Member

Thanks for this. I've made some changes on top of your branch. Now there's only one API and no duplicated detection code:

  • One performance API. getCPUPerformanceLevels() is now the only per-platform virtual for this. getPerformanceCPUs() is non-virtual: it returns the first level when there's more than one level. The Linux and Windows getPerformanceCPUs() overrides are gone.
  • One clustering rule. selectFastestCPUs() is replaced by clusterCPUs(), which starts a new level at every gap of more than 15%. Linux uses it for both cpu_capacity and cpuinfo_max_freq. Results are the same as before, except on CPUs with three or more tiers that are each more than 15% apart, where getPerformanceCPUs() now returns only the top tier.
  • Affinity. I removed getCPUAffinityCapability() and its enum. An empty result from getAvailableCPUs() now means affinity isn't supported, and the base class default is {}.
  • Windows. One validated GetLogicalProcessorInformationEx walk, using your bounds checks, feeds both the performance levels and the core threads. A maskToCPUs() helper replaces the copied bit loops.
  • Linux. The detection logic now exists only in getCPUPerformanceLevels(), with helpers for reading the online CPUs and each core's sibling threads.
  • I also removed the comment about vtable ordering. cbang is a static library, so binary compatibility isn't a concern.

I tested on Linux but couldn't compile the Windows changes. Needs build and test on Windows, ideally on a hybrid Intel machine.

@Br3ach

Br3ach commented Oct 5, 2026

Copy link
Copy Markdown
Author

Thanks!

(1) Confirmed that the Windows MSVC x64 build succeeds. Simulated topology tests and native detection on my homogeneous CPU also passed. I haven’t tested on a real Intel hybrid machine.

(2) The purpose of getCPUAffinityCapability() was to distinguish enforceable CPU restrictions from advisory placement hints, such as macOS affinity tags, and unsupported affinity. It was separate from getAvailableCPUs() because knowing which CPUs are available does not itself establish whether placement can be enforced.

My work on the FAH client currently uses it as a gate for managed allocation:

bool newHard =
sys.getCPUAffinityCapability() == SystemInfo::CPU_AFFINITY_HARD;

if (newAvailable.empty()) newHard = false;

Actual affinity enforcement happens separately in the client’s process launcher. Removing the capability API is fine. I can determine support in the client using a Windows/Linux platform check and a nonempty available-CPU set, while retaining exact-mask verification at launch.

@Br3ach

Br3ach commented Oct 7, 2026

Copy link
Copy Markdown
Author

Apple Clang reported an ambiguous conversion in String(cores.size()); I added an explicit uint64_t cast. With this fix, cbang and FAHClient built successfully on native macOS ARM64 (build).

@jcoffland

Copy link
Copy Markdown
Member

Thanks for testing the Windows build.

You don't need a platform check in the client. !getAvailableCPUs().empty() is the whole gate. cbang returns an empty set on any platform where it can't set affinity, using the same checks the capability function used: sched_getaffinity() on Linux and the single-processor-group mask check on Windows. macOS and FreeBSD now get the base default, {}. If cbang ever supports macOS affinity tags, we can add an API for advisory placement then.

Testing on a real hybrid Intel machine, on Linux or Windows, is still open if anyone has one.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants