NXThreadBind

Binds the calling thread to a specified CPU, which results in hard affinity.

Library:LibC
Classification:NKS
Service:Threads

Syntax

  #include <nks/thread.h> 
   
  int NXThreadBind (
     NXCpuId_t   cpu_id);

Parameters

cpu_id

(IN) Specifies the ID of the CPU to be bound:

Flag

Value

Description

0 to N-1

In NKS, CPUs on a platform are numbered 0 to N-1 for a platform with N CPUs. Specifying one of these values binds the thread to that CPU.

NX_MYCPU

0xFFFFFFFE

Specifies the CPU on which the calling thread is executing.

NX_THR_UNBOUND

0xFFFFFFFF

Removes any existing binding.

Return Values

If successful, returns 0; otherwise, returns a nonzero error code:

Decimal

Hex

Constant

Description

9

0x09

NX_EINVAL

Invalid CPU number specified.

69

0x45

NX_EPERM

The caller does not have appropriate privileges.

Remarks

A bound thread is scheduled only on the CPU to which it is bound. You can use the NXThreadBind function to bind a thread to a CPU, and with a subsequent call using the NX_THR_UNBOUND flag, remove that binding.

The NKS layer surfaces a simple naming scheme for the set of CPUs that are currently online by numbering them 0 through N-1 sequentially (with N being the number of CPUs online).

NXThreadBind is synchronous; on return, the calling thread is executed on the specified CPU.

Some worker thread pools may be set up on a per-processor basis. If the code that is being executed by one of those threads calls NXThreadBind, it defeats the purpose of creating per-processor worker thread pools. The application is responsible for controlling such a confusing situation.

See Also