cpu_execution_policy.h

Requested and resolved CPU execution policy for a runtime session.

This is the first step (Pool PR01) of the :ref:l-next-steps-session-execution-pools roadmap. It defines the typed policy a session requests and the immutable resolution derived from it. The executor and compatible-pool registry are delivered by Pool PR02. Session wiring is delivered by a later step; this header owns the policy vocabulary and its deterministic validation.

namespace onnx_light

Alias that makes onnx-light headers compatible with code that references ONNX_LIGHT_NAMESPACE (the macro used in the standard onnx package).

Set to ONNX_LIGHT_NAMESPACE so both names resolve to the same namespace.

Symbol-visibility attribute for the public onnx-light C++ API.

Maps the upstream compatibility macro to onnx-light’s explicit proto ABI annotation. This keeps declarations from vendored ONNX headers visible when lib_onnx_proto uses hidden visibility by default.

Namespace alias so that ONNX C++ code (and consumers such as onnxruntime) that refers to the literal onnx namespace — rather than the ONNX_NAMESPACE macro — resolves to the onnx-light namespace. The standard onnx package lives in namespace onnx; onnx-light uses onnx_light (via ONNX_LIGHT_NAMESPACE), so this alias keeps onnx-light a true drop-in. It is only introduced when the onnx-light namespace differs from onnx.

namespace core

namespace runtime

Enums

enum class CpuSpinPolicy

Controls how a waiting worker or caller spins before parking.

Spinning applies both to workers waiting for a new generation and to the caller waiting for worker completion. The default bounds the spin and eventually parks.

Values:

enumerator kAdaptive

Bounded, topology-derived spin that eventually parks.

enumerator kFixedIterations

Spin for an explicit number of iterations before parking.

enumerator kFixedDuration

Spin for an explicit duration in nanoseconds before parking.

enumerator kParkImmediately

Park immediately without spinning.

enum class CpuAffinityPolicy

Controls how workers are placed on the process-visible logical processors.

Values:

enumerator kNone

Do not pin workers; a successful no-affinity policy.

enumerator kPhysicalCores

One logical processor per physical core.

enumerator kPerformanceCores

Prefer performance cores when the topology can identify them.

enumerator kPhysicalThenSmt

One logical processor per physical core, then SMT siblings.

enumerator kExplicit

Pin workers to an explicit CPU set.

Functions

std::vector<CpuLogicalProcessor> ProcessVisibleLogicalProcessors()

Returns stable identifiers for the logical processors currently available to this process.

The returned set reflects process affinity restrictions such as Linux cpusets. It is empty when the operating system cannot expose stable logical processor identifiers.

Returns: The process-visible logical processors in increasing identifier order.

ResolvedCpuExecutionPolicy ResolveCpuExecutionPolicy(const CpuExecutionPolicy &request)

Resolves a requested CPU execution policy into an immutable resolution.

Resolution validates the request deterministically and derives the effective participant count and worker placement from the process-visible topology. Fallbacks taken when a requested topology feature is unavailable are recorded in :cpp:var:ResolvedCpuExecutionPolicy::diagnostics rather than failing.

The following requests fail with :cpp:class:std::invalid_argument:

• a negative :cpp:var:CpuExecutionPolicy::num_threads;

• a spin budget that is zero for a fixed policy or non-zero for the adaptive or park-immediately policy;

• a :cpp:enumerator:CpuAffinityPolicy::kExplicit policy with an empty CPU set, duplicate identifiers, or an identifier outside the process-visible set;

• a non-explicit affinity policy that supplies a CPU set;

• an explicit CPU set whose size conflicts with a positive requested thread count.

Returns: The immutable resolution derived from the request.

Parameters:

request – The requested policy.

Variables

constexpr uint64_t kDefaultAdaptiveSpinIterations = 10000

Default number of adaptive spin iterations recorded before parking.

struct CpuExecutionPolicy

#include <cpu_execution_policy.h>

Requested per-session CPU execution policy.

Names are illustrative and may change during API review. The policy is resolved into an immutable :cpp:class:ResolvedCpuExecutionPolicy by :cpp:func:ResolveCpuExecutionPolicy.

Public Functions

bool operator==(const CpuExecutionPolicy&) const = default

Public Members

int32_t num_threads = 0

Requested number of participants, including the calling thread.

• 0 (default): use a topology-derived default.

• 1: serial, no worker threads.

• > 1: request exactly this many participants.

• < 0: rejected.

CpuSpinPolicy spin_policy = CpuSpinPolicy::kAdaptive

Requested spin-before-park policy.

uint64_t spin_budget = 0

Iterations for :cpp:enumerator:CpuSpinPolicy::kFixedIterations or nanoseconds for :cpp:enumerator:CpuSpinPolicy::kFixedDuration. Must be 0 for the adaptive and park-immediately policies.

CpuAffinityPolicy affinity_policy = CpuAffinityPolicy::kPhysicalCores

Requested affinity policy.

std::vector<CpuLogicalProcessor> cpu_set

Explicit participant CPU set, required and only allowed for :cpp:enumerator:CpuAffinityPolicy::kExplicit. The first processor is assigned to the calling participant; the remaining processors are assigned to workers.

bool allow_nested_parallelism = false

Whether nested parallel regions may create additional participants.

struct CpuLogicalProcessor

#include <cpu_execution_policy.h>

Identifies a logical processor by a stable operating-system identifier.

Identifiers must come from the process-visible CPU set and are never inferred from adjacency. The wrapper keeps the vocabulary extensible without changing every call site.

Public Functions

bool operator==(const CpuLogicalProcessor&) const = default

Public Members

uint32_t id = 0

Stable operating-system logical processor identifier.

uint16_t group = 0

Windows processor group. It is 0 on platforms without processor groups.

struct ResolvedCpuExecutionPolicy

#include <cpu_execution_policy.h>

Immutable resolution of a :cpp:class:CpuExecutionPolicy.

The resolution describes the workers that actually execute the graph. It is derived deterministically from the request and the process-visible topology.

Public Functions

bool operator==(const ResolvedCpuExecutionPolicy&) const = default

Public Members

CpuExecutionPolicy request

The request this resolution was derived from.

uint32_t effective_threads = 1

Effective number of participants, including the calling thread. Always >= 1.

std::optional<CpuLogicalProcessor> caller_processor

Explicit calling-participant assignment, absent when the caller is not pinned by this policy.

std::vector<CpuLogicalProcessor> worker_processors

Explicit worker processor assignment, empty when no pinning is applied. Its size is at most effective_threads - 1.

bool uses_smt = false

Whether the resolution relies on SMT siblings.

bool uses_efficiency_cores = false

Whether the resolution relies on efficiency cores.

ResolvedSpinPolicy spin

Resolved spin and park policy.

bool allow_nested_parallelism = false

Whether nested parallel regions may create additional participants.

std::vector<std::string> diagnostics

Human-readable notes about fallbacks taken during resolution.

struct ResolvedSpinPolicy

#include <cpu_execution_policy.h>

Immutable resolution of a spin policy.

Exactly one of :cpp:var:iterations and :cpp:var:duration_ns is non-zero for the fixed policies; both are 0 for the park-immediately policy.

Public Functions

bool operator==(const ResolvedSpinPolicy&) const = default

Public Members

CpuSpinPolicy policy = CpuSpinPolicy::kAdaptive

Resolved spin policy class.

uint64_t iterations = 0

Resolved spin iterations before parking, or 0 when not iteration-based.

uint64_t duration_ns = 0

Resolved spin duration in nanoseconds before parking, or 0 when not duration-based.