###############
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:

.. code-block:: python

  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 <https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry>`__ 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:

.. code-block:: sh

    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:

.. code-block:: sh

    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:

.. code-block:: sh

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