Struct AffinityMask 

pub struct AffinityMask { /* private fields */ }

A cross-platform CPU affinity mask representing a set of logical processors.

An AffinityMask specifies which logical processors (CPU threads) a thread is allowed to execute on. This is useful for:

• Restricting latency-sensitive threads to performance cores (P-cores)
• Restricting background threads to efficiency cores (E-cores)
• Allowing thread migration within a subset of cores to reduce scheduling latency

Example

use gdt_cpus::AffinityMask;

// Create a mask for cores 0, 1, and 2
let mask = AffinityMask::from_cores(&[0, 1, 2]);
assert_eq!(mask.count(), 3);
assert!(mask.contains(0));
assert!(mask.contains(1));
assert!(mask.contains(2));
assert!(!mask.contains(3));

Platform Behavior

When used with set_thread_affinity:

• Linux/Windows: The mask is applied directly to constrain thread execution
• macOS: Returns Error::Unsupported; use QoS classes instead

Implementations

impl AffinityMask

pub fn empty() -> Self

Creates an empty affinity mask with no cores set.

Example

use gdt_cpus::AffinityMask;

let mask = AffinityMask::empty();
assert!(mask.is_empty());
assert_eq!(mask.count(), 0);

pub fn single(logical_core_id: usize) -> Self

Creates an affinity mask with a single core set.

Arguments

• logical_core_id - The logical processor ID to include in the mask

Example

use gdt_cpus::AffinityMask;

let mask = AffinityMask::single(5);
assert_eq!(mask.count(), 1);
assert!(mask.contains(5));

pub fn from_cores(core_ids: &[usize]) -> Self

Creates an affinity mask from a slice of core IDs.

Arguments

• core_ids - Slice of logical processor IDs to include

Example

use gdt_cpus::AffinityMask;

let mask = AffinityMask::from_cores(&[0, 2, 4, 6]);
assert_eq!(mask.count(), 4);
assert!(mask.contains(0));
assert!(!mask.contains(1));
assert!(mask.contains(2));

pub fn add(&mut self, logical_core_id: usize)

Adds a logical core to the mask.

If the core is already in the mask, this is a no-op.

Arguments

• logical_core_id - The logical processor ID to add

Example

use gdt_cpus::AffinityMask;

let mut mask = AffinityMask::empty();
mask.add(0);
mask.add(1);
assert_eq!(mask.count(), 2);

pub fn remove(&mut self, logical_core_id: usize)

Removes a logical core from the mask.

If the core is not in the mask, this is a no-op.

Arguments

• logical_core_id - The logical processor ID to remove

Example

use gdt_cpus::AffinityMask;

let mut mask = AffinityMask::from_cores(&[0, 1, 2]);
mask.remove(1);
assert_eq!(mask.count(), 2);
assert!(!mask.contains(1));

pub fn contains(&self, logical_core_id: usize) -> bool

Checks if a logical core is in the mask.

Arguments

• logical_core_id - The logical processor ID to check

Returns

true if the core is in the mask, false otherwise.

Example

use gdt_cpus::AffinityMask;

let mask = AffinityMask::from_cores(&[0, 2, 4]);
assert!(mask.contains(0));
assert!(!mask.contains(1));
assert!(mask.contains(2));

pub fn count(&self) -> usize

Returns the number of cores in the mask.

Example

use gdt_cpus::AffinityMask;

let mask = AffinityMask::from_cores(&[0, 1, 2, 3]);
assert_eq!(mask.count(), 4);

pub fn is_empty(&self) -> bool

Returns true if the mask is empty (no cores set).

Example

use gdt_cpus::AffinityMask;

let empty = AffinityMask::empty();
assert!(empty.is_empty());

let non_empty = AffinityMask::single(0);
assert!(!non_empty.is_empty());

pub fn iter(&self) -> impl Iterator<Item = usize> + '_

Returns an iterator over the core IDs in the mask.

Example

use gdt_cpus::AffinityMask;

let mask = AffinityMask::from_cores(&[1, 3, 5]);
let cores: Vec<usize> = mask.iter().collect();
assert_eq!(cores, vec![1, 3, 5]);

pub fn union(&self, other: &AffinityMask) -> AffinityMask

Returns the union of this mask with another.

The resulting mask contains all cores that are in either mask.

Example

use gdt_cpus::AffinityMask;

let a = AffinityMask::from_cores(&[0, 1]);
let b = AffinityMask::from_cores(&[1, 2]);
let union = a.union(&b);
assert_eq!(union.count(), 3);
assert!(union.contains(0));
assert!(union.contains(1));
assert!(union.contains(2));

pub fn intersection(&self, other: &AffinityMask) -> AffinityMask

Returns the intersection of this mask with another.

The resulting mask contains only cores that are in both masks.

Example

use gdt_cpus::AffinityMask;

let a = AffinityMask::from_cores(&[0, 1, 2]);
let b = AffinityMask::from_cores(&[1, 2, 3]);
let intersection = a.intersection(&b);
assert_eq!(intersection.count(), 2);
assert!(intersection.contains(1));
assert!(intersection.contains(2));

pub fn as_raw_u64(&self) -> u64

Returns the first 64 cores as a raw u64 bitmask.

This is useful for platform APIs that only support 64 cores. Cores beyond index 63 are not included.

Example

use gdt_cpus::AffinityMask;

let mask = AffinityMask::from_cores(&[0, 1, 63]);
let raw = mask.as_raw_u64();
assert_eq!(raw, 0x8000_0000_0000_0003);

pub fn as_raw_bits(&self) -> &[u64]

Returns the raw bits as a slice.

Each element represents 64 cores: bits[0] = cores 0-63, bits[1] = cores 64-127, etc.

Trait Implementations

impl Clone for AffinityMask

fn clone(&self) -> AffinityMask

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AffinityMask

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AffinityMask

fn default() -> AffinityMask

Returns the “default value” for a type.

impl Display for AffinityMask

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromIterator<usize> for AffinityMask

fn from_iter<T: IntoIterator<Item = usize>>(iter: T) -> Self

Creates a value from an iterator.

impl IntoIterator for &AffinityMask

type Item = usize

The type of the elements being iterated over.

type IntoIter = IntoIter<usize>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq for AffinityMask

fn eq(&self, other: &AffinityMask) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for AffinityMask

impl StructuralPartialEq for AffinityMask