Developer Notes

Symbol Conflicts

The hwloc is loaded into the public linker name space to support hwloc plugins. This might have unintended consequences.

Design Decisions

Some design decisions were made in the initial development phase. For instance, whether something should be a Python attribute or a Python method. My choice at the time was simple, if it’s part of a C struct, it’s an attribute, otherwise, it’s a function. If both are possible, like the cpuset and the pci_id, we use property. This way, we can keep it simple and allow future extension for parameters. It’s ok, Python stdlib does not use property very often, let’s move on.

Hwloc has lots of setters and getters, some Python users might frown upon this design pattern, but we decided keep it instead. Most of these setters and getters have parameters. We could have wrapped them into properties like:

topology.membind[proc_id] = Membind(policy, flags)

It might be more ergonomic this way, but also feels like an un-intuitive way to writing code. In addition, the setter and getters don’t have exact match. For instance, setting the DEFAULT policy with the membind setter might get you a FIRST_TOUCH policy in the getter.

For interpolation modules, hwloc supports getting the CPU affinity of GPUs with functions like nvml_get_device_cpuset. We rename the function in the high-level interface as get_affinity to avoid confusion.

GitHub CI

PyHwloc’s GitHub action tests use container images cached in ghcr.io. Please refer to the GitHub document for an in-depth explanation of how it works.

There are two Docker images used in CI:

  1. Test image (ghcr.io/open-mpi/pyhwloc): Built from dev/Dockerfile.cpu, used for running tests and building documentation.

  2. Manylinux image (ghcr.io/open-mpi/pyhwloc-manylinux_2_34): Built from dev/Dockerfile.manylinux_2_34, used for building portable PyPI wheels.

Update hwloc

When bumping hwloc version, one needs to:

  • Update the hwloc_version(_v2) files.

  • Update GHA image tags.

  • Build and push new test images using GHA.

For hwloc V3, this can be automated from GitHub Actions by manually running the Bump hwloc and test images workflow. The workflow runs dev/bump_hwloc.sh and opens a pull request only when dev/hwloc_version changes, then builds the updated test and wheel images, uploads wheel artifacts, and runs the normal CI tests against the bump branch.

Building Images Locally

To build the test image for hwloc V2:

docker build --progress=plain ./dev -f ./dev/Dockerfile.cpu --build-arg HWLOC_MAJOR=2 -t ghcr.io/open-mpi/pyhwloc:v2.13.0

To build the test image for hwloc V3:

docker build --progress=plain ./dev -f ./dev/Dockerfile.cpu --build-arg HWLOC_MAJOR=3 -t ghcr.io/open-mpi/pyhwloc:latest

To build the manylinux image:

docker build --progress=plain ./dev -f ./Dockerfile.manylinux_2_34 -t ghcr.io/open-mpi/pyhwloc-manylinux_2_34:latest