Like most libraries that mainly fill data structures, hwloc is not thread safe but rather reentrant: all state is held in a hwloc_topology_t instance without mutex protection. That means, for example, that two threads can safely operate on and modify two different hwloc_topology_t instances, but they should not simultaneously invoke functions that modify the same instance. Similarly, one thread should not modify a hwloc_topology_t instance while another thread is reading or traversing it. However, two threads can safely read or traverse the same hwloc_topology_t instance concurrently.
When running in multiprocessor environments, be aware that proper thread synchronization and/or memory coherency protection is needed to pass hwloc data (such as hwloc_topology_t pointers) from one processor to another (e.g., a mutex, semaphore, or a memory barrier). Note that this is not a hwloc-specific requirement, but it is worth mentioning.
For reference, hwloc_topology_t modification operations include (but may not be limited to):
- Creation and destruction
hwloc_topology_init(), hwloc_topology_load(), hwloc_topology_destroy() (see Create and Destroy Topologies) imply major modifications of the structure, including freeing some objects. No other thread cannot access the topology or any of its objects at the same time.
Also references to objects inside the topology are not valid anymore after these functions return.
- Runtime topology modifications
hwloc_topology_insert_misc_object_by_* (see Tinker With Topologies.) may modify the topology significantly by adding objects inside the tree, changing the topology depth, etc. hwloc_topology_restrict modifies the topology even more dramatically by removing some objects.
Although references to former objects may still be valid after insertion or restriction, it is strongly advised to not rely on any such guarantee and always re-consult the topology to reacquire new instances of objects.
- Locating topologies
hwloc_topology_ignore*, hwloc_topology_set* (see Configure Topology Detection) do not modify the topology directly, but they do modify internal structures describing the behavior of the next invocation of hwloc_topology_load(). Hence, all of these functions should not be used concurrently.
Note that these functions do not modify the current topology until it is actually reloaded; it is possible to use them while other threads are only read the current topology.
