CPUSet for Python 3

1.0.2 · active · verified Thu Apr 16

cpuset-py3 is a Python 3 compatible fork of the original cpuset library, providing functionalities to query and manipulate CPU sets (processor affinity) on Linux systems. It allows creating, modifying, and applying CPU sets to processes and threads, facilitating fine-grained control over CPU core usage. The current version is 1.0.2, and it's maintained on an as-needed basis rather than a strict release cadence.

Common errors

```
ModuleNotFoundError: No module named 'cpuset'
```
cause The `cpuset-py3` package has not been installed, or the Python interpreter is not in an environment where it's installed.

fix Install the library using `pip install cpuset-py3`.
```
PermissionError: [Errno 1] Operation not permitted: 'cpuset'
```
cause Attempting to change process or thread CPU affinity without sufficient operating system permissions.

fix Run the Python script with root privileges (e.g., `sudo python your_script.py`) or ensure the executing user/process has the `CAP_SYS_NICE` capability.
```
AttributeError: module 'cpuset' has no attribute 'CPUSet'
```
cause You likely installed the old `cpuset` (Python 2) package instead of `cpuset-py3`, which has a different internal structure or is incompatible with Python 3.

fix Uninstall the incorrect package (`pip uninstall cpuset`) and then install the correct one (`pip install cpuset-py3`).

Warnings

gotcha This library is designed specifically for Linux systems. Functions for querying and setting CPU affinity (`get_cpuset_for_current_process`, `set_cpuset_for_current_process`, etc.) will not function correctly or might raise errors on other operating systems like macOS or Windows.
Fix: Ensure your application runs on a Linux environment when utilizing system affinity features.
gotcha Setting CPU affinity for processes or threads often requires elevated privileges (e.g., root access or specific Linux capabilities like CAP_SYS_NICE). Operations like `set_cpuset_for_current_process` might fail with `PermissionError` if not run with sufficient permissions.
Fix: Run your script with `sudo` (e.g., `sudo python your_script.py`) or configure the executing user/process with the necessary Linux capabilities.
gotcha Be careful to install `cpuset-py3` for Python 3 compatibility. There is an older, incompatible package named `cpuset` on PyPI which is intended for Python 2 and will cause `AttributeError` or unexpected behavior in Python 3 environments.
Fix: Always use `pip install cpuset-py3`. If you accidentally installed `cpuset`, uninstall it first with `pip uninstall cpuset`.
gotcha The `as_bitmask()` method returns an integer bitmask where each bit corresponds to a CPU ID. For larger or sparsely populated CPU sets, interpreting this raw bitmask can be complex or unintuitive compared to list or string representations.
Fix: For human-readable output, prefer `as_list()` or `as_canonical_str()`. Only use `as_bitmask()` when direct bitwise operations or kernel-level interfaces require it.

Install

pip install cpuset-py3 Install stable version

Imports

CPUSet
wrong:
```
from cpuset import CPUSet
```
correct:
```
import cpuset; s = cpuset.CPUSet()
```
While `from cpuset import CPUSet` works for the class, many other core functions like `set_cpuset_for_current_process` are directly under the `cpuset` module, making `import cpuset` the more holistic and common usage pattern.

set_cpuset_for_current_process

import cpuset; cpuset.set_cpuset_for_current_process(...)

Quickstart

This quickstart demonstrates how to create and manipulate `CPUSet` objects. It also shows how to query the current process's affinity on Linux, with a note about the permissions often required for setting affinity.

import cpuset
import platform

print(f"Running on OS: {platform.system()}\n")

# Create a new empty cpuset
s = cpuset.CPUSet()
s.add_cpu(0)
s.add_cpu(1)
s.add_cpu(2)
print(f"Created CPUSet (0,1,2): {s.as_list()}")
print(f"As string: {s.as_str()}")
print(f"As canonical string: {s.as_canonical_str()}") # will be "0-2"
print(f"As bitmask: {hex(s.as_bitmask())}") # 0x7

# Create from a string representation
s_from_str = cpuset.CPUSet("0-3,5")
print(f"\nCPUSet from string '0-3,5': {s_from_str.as_list()}")

if platform.system() == "Linux":
    print("\nAttempting to query current process affinity (Linux-only):")
    try:
        current_affinity = cpuset.get_cpuset_for_current_process()
        print(f"  Current process affinity: {current_affinity.as_list()}")

        # Uncomment to attempt setting affinity (requires appropriate permissions):
        # print(f"  Attempting to set process affinity to {s.as_list()}...")
        # cpuset.set_cpuset_for_current_process(s)
        # updated_affinity = cpuset.get_cpuset_for_current_process()
        # print(f"  Updated process affinity: {updated_affinity.as_list()}")

    except PermissionError:
        print("  Permission denied to get/set process affinity. Try running with sudo or check capabilities.")
    except Exception as e:
        print(f"  An error occurred during system affinity call: {e}")
else:
    print("\nSystem affinity functions (get/set) are only available on Linux.")

print("\nOperations on CPUSet objects are generally platform-independent:")
s_union = s | cpuset.CPUSet("3-4")
print(f"Union (0-2 | 3-4): {s_union.as_list()}") # [0,1,2,3,4]

s_intersect = s & cpuset.CPUSet("1-3")
print(f"Intersection (0-2 & 1-3): {s_intersect.as_list()}") # [1,2]

view raw JSON →