#core_affinity

justjavac/core_affinity provides a minimal native API for reading and setting the CPU affinity of the current thread.

#Install

moon add justjavac/core_affinity

#API

@core_affinity.get_core_ids(): returns the zero-based core ids currently available to the calling thread.
@core_affinity.set_for_current(ids): applies a new affinity mask for the calling thread and returns whether it succeeded.

#Example

///|
test "read current affinity" {
  let ids = @core_affinity.get_core_ids()
  assert_true(ids.length() > 0)
  assert_true(ids.length() <= 64)
}

///|
test "pin to the first available core and restore" {
  let original_ids = @core_affinity.get_core_ids()
  assert_true(original_ids.length() > 0)

  let first_id = original_ids[0]
  assert_true(@core_affinity.set_for_current([first_id]))
  assert_true(@core_affinity.get_core_ids().contains(first_id))

  ignore(@core_affinity.set_for_current(original_ids))
}

#Notes

Core ids are zero-based.
Only ids in 0..63 are accepted by this package.
The affinity change only affects the calling thread.

get_core_ids

source

fn get_core_ids() -> Array[Int]

Returns the zero-based CPU core ids that the current thread may run on.

The function reads the platform affinity mask and expands every set bit into a core id. The returned array is ordered from low core id to high core id.

Returns

An Array[Int] containing all enabled core ids for the calling thread.

Example

test "inspect current affinity" {
  let ids = get_core_ids()
  assert_true(ids.length() > 0)
  assert_true(ids.length() <= 64)
}

Notes

Core ids are zero-based.
The package currently models up to 64 cores because it uses a UInt64 mask internally.
The result reflects the calling thread, not the whole process.

set_for_current

source

fn set_for_current(ids : Array[Int]) -> Bool

Restricts the current thread to the given CPU core ids.

The input array is converted into a native affinity mask and then passed to the platform-specific implementation. Duplicate core ids are harmless.

Parameters

ids: Zero-based core ids to enable for the current thread.

Returns

Returns true when the affinity change succeeds. Returns false when:

ids is empty;
any core id is outside 0..63;
or the operating system rejects the new affinity mask.

Example

test "pin thread to one available core" {
  let original_ids = get_core_ids()
  assert_true(original_ids.length() > 0)

  let first_id = original_ids[0]
  assert_true(set_for_current([first_id]))

  let current_ids = get_core_ids()
  assert_true(current_ids.contains(first_id))

  ignore(set_for_current(original_ids))
}

Notes

The change applies only to the calling thread.
Passing a single-element array pins the current thread to one core.
Some platforms may still reject a syntactically valid mask due to system policy, missing permissions, or unsupported affinity APIs.