I do not want hwloc to rediscover my enormous machine topology every time I rerun a process
Although the topology discovery is not expensive on common machines, its overhead may become significant when multiple processes repeat the discovery on large machines (for instance when starting one process per core in a parallel application). The machine topology usually does not vary much, except if some cores are stopped/restarted or if the administrator restrictions are modified. Thus rediscovering the whole topology again and again may look useless.
For this purpose, hwloc offers XML import/export features. It lets you save the discovered topology to a file (for instance with the lstopo program) and reload it later by setting the HWLOC_XMLFILE environment variable. Loading a XML topology is usually much faster than querying multiple files or calling multiple functions of the operating system. It is also possible to manipulate such XML files with the C programming interface, and the import/export may also be directed to memory buffer (that may for instance be transmitted between applications through a socket).
How do I handle API upgrades?
The hwloc interface is extended with every new major release. Any application using the hwloc API should be prepared to check at compile-time whether some features are available in the currently installed hwloc distribution.
To check whether hwloc is at least 1.1, you should use:
#include <hwloc.h>
#if HWLOC_API_VERSION >= 0x00010100
...
#endif
One of the major changes in hwloc 1.1 is the addition of the bitmap API. It supersedes the now deprecated cpuset API which will be removed in a future hwloc release. It is strongly recommended to switch existing codes to the bitmap API. Keeping support for older hwloc versions is easy. For instance, if your code uses hwloc_cpuset_alloc, you should use hwloc_bitmap_alloc instead and add the following code to one of your common headers:
#include <hwloc.h>
#if HWLOC_API_VERSION < 0x00010100
#define hwloc_bitmap_alloc hwloc_cpuset_alloc
#endif
Similarly, the hwloc 1.0 interface may be detected by comparing HWLOC_API_VERSION with 0x00010000.
hwloc 0.9 did not define any HWLOC_API_VERSION but this very old release probably does not deserve support from your application anymore.
