Struct cpu_affinity::LogicalCores

source ·

pub struct LogicalCores(_);

Expand description

Logical cores to use for process and thread affinity, abstracting away platform, library and Operating System differences.

Provides the following definitions:-

Constant LogicalCores::IsSettingProcessAffinitySupported: Boolean that is true if the current platform contains a way to attempt to set process affinity.
Constant LogicalCores::IsSettingThreadAffinitySupported: Boolean that is true if the current platform contains a way to attempt to set thread affinity. Note that this is true for Fuschia and Empscripten, but that setting thread affinity always fails as unsupported as of 3rd December 2018.
Method set_current_process_affinity(&self) -> io::Result<()>: Tries to set the current process’ affinity; may fail (eg may not be supported in particular revisions of an OS, particularly so on Fuschia and Emscripten).
Method set_process_affinity(&self, process_identifier) -> io::Result<()>: As above, but for a particular process. Usually fails with permission denied if not root.
Method set_current_thread_affinity(&self) -> io::Result<()>: Tries to set the thread process’ affinity; may fail (eg may not be supported in particular revisions of an OS, particularly so on Fuschia and Emscripten).
Method set_thread_affinity(&self, thread_identifier) -> io::Result<()>: As above, but for a thread process. Usually fails with permission denied if not root.

If support for a platform has not been explicitly added to this library then it will not fail on that platform but it will not change any process or thread affinities, either.

At this time, there is no support for Solaris. If you’re interested in adding support, see https://stackoverflow.com/questions/14085515/obtain-lwp-id-from-a-pthread-t-on-solaris-to-use-with-processor-bind.

DragonFlyBSD and FreeBSD currently (as of 3rd December 2018) support 256 cores.

Windows is a bit squiffy with more than 64 cores.

Implementations

source

impl LogicalCores

source

pub const IsSettingProcessAffinitySupported: bool = true

Is setting process affinity is supported?

Note that on emscripten and fuschia an error (ENOSYS) by the platform will always be returned as of the 3rd December 2018.

The following do not support setting process affinity:-

iOS
Mac OS
OpenBSD
BitRig

source

pub const IsSettingThreadAffinitySupported: bool = true

Is setting thread affinity is supported?

Note that on emscripten and fuschia an error (ENOSYS) by the platform will always be returned as of the 3rd December 2018.

The following do not support setting thread affinity:-

Android
iOS
Mac OS
OpenBSD
BitRig

source

pub fn set_current_process_affinity(&self) -> Result<()>

Sets the current process’ logical core affinity.

This is not efficiently implemented (it uses a loop).

Failure occurs if a CPU in the set does not exist, is offline or in some other way is unavailable to the process_identifier (EINVAL).

source

pub fn set_process_affinity(
&self,
process_identifier: ProcessIdentifier
) -> Result<()>

Sets the process’ logical core affinity.

This is not efficiently implemented (it uses a loop).

Failure occurs if:-

Permission is denied to change the process affinity for process_identifier (EPERM) (for example, the process isn’t a child of this process);
A CPU in the set does not exist, is offline or in some other way is unavailable to the process_identifier (EINVAL);
process_identifier does not exist (ESRCH)
Operating system is not yet implemented (ENOSYS) - typical of Emscripten and Fuschia.

source

pub fn set_current_thread_affinity(&self) -> Result<()>

Sets the thread’s logical core affinity.

Threads are never resident on just on core, and hence a lot of thread local opimizations (eg with clever non-blocking alogorithms) are useless.

source

pub fn set_thread_affinity(
&self,
thread_identifier: ThreadIdentifier
) -> Result<()>

Sets the thread’s logical core affinity.

This is only used as a hint on iOS and MacOS; it is near useless.

Threads are never resident on just on core, and hence a lot of thread local opimizations (eg with clever non-blocking alogorithms) are useless.

Permission is denied to change the process affinity for process_identifier (EPERM) (for example, the process isn’t a child of this process);
A CPU in the set does not exist, is offline or in some other way is unavailable to the process_identifier (EINVAL);
process_identifier does not exist (ESRCH)
Operating system is not yet implemented (ENOSYS) - typical of Emscripten and Fuschia.
ERANGE - on FreeBSD, the cpu set was far too large.
EDEADLK - on FreeBSD, the cpu set could not be honoured.