Upgrading to v2.0 API

Here is a list of recommended ways to work-around API changes.

Detecting the hwloc version

To detect whether your building against hwloc 2.0.0 or later:

#if HWLOC_API_VERSION >= 0x20000
...
#endif

HWLOC_OBJ_CACHE replaced

Replaced with HWLOC_OBJ_L1CACHE, ..., HWLOC_OBJ_L5CACHE, HWLOC_OBJ_L1ICACHE, ..., HWLOC_OBJ_L3ICACHE.

hwloc_get_cache_type_depth() is not really needed to disambiguate cache types anymore.

hwloc_obj_type_is_cache(), hwloc_obj_type_is_dcache() and hwloc_obj_type_is_icache() may be used to check whether a given type is a cache, data/unified cache or instruction cache.

I/O and Misc children

I/O children are not in the main object children list anymore. They are in the list starting at obj->io_first_child and whose size if obj->io_arity.

Misc children are not in the main object children list anymore. They are in the list starting at obj->misc_first_child and whose size if obj->misc_arity.

hwloc_topology_insert_misc_object_by_cpuset() and hwloc_topology_insert_misc_object_by_parent() replaced

hwloc_topology_insert_misc_object_by_cpuset() is replaced with hwloc_topology_alloc_group_object() and hwloc_topology_insert_group_object().

hwloc_topology_insert_misc_object_by_parent() is replaced with hwloc_topology_insert_misc_object().

hwloc_topology_set_fsroot() removed

hwloc_topology_set_fsroot() was removed. For remote/offline debugging, the HWLOC_FSROOT environment variable is still supported for the same behavior.

hwloc_obj_type_string() replaced, hwloc_obj_snprintf() removed

hwloc_type_name() replaces it.

hwloc_obj_snprintf() removed because long-deprecated by hwloc_obj_type_snprintf() and hwloc_obj_attr_snprintf().

hwloc_obj_type_sscanf() deprecated, hwloc_obj_type_of_string() removed

hwloc_type_sscanf() extends hwloc_obj_type_sscanf() by passing a union hwloc_obj_attr_u which may receive cache, group, bridge or OS device attributes.

hwloc_type_sscanf_as_depth() is also added to directly return the corresponding level depth within a topology.

hwloc_topology_ignore_type(), hwloc_topology_ignore_type_keep_structure() and hwloc_topology_ignore_all_keep_structure() replaced

Respectively superseded by

hwloc_topology_set_type_filter(topology, type, HWLOC_TYPE_FILTER_KEEP_NONE);
hwloc_topology_set_type_filter(topology, type, HWLOC_TYPE_FILTER_KEEP_STRUCTURE);
hwloc_topology_set_all_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_STRUCTURE);

Also, the meaning of KEEP_STRUCTURE has changed (only entire levels may be ignored, instead of single objects), the old behavior is not available anymore.

HWLOC_TOPOLOGY_FLAG_ICACHES replaced

Superseded by

hwloc_topology_set_icache_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_ALL);

HWLOC_TOPOLOGY_FLAG_WHOLE_IO, HWLOC_TOPOLOGY_FLAG_IO_DEVICES and HWLOC_TOPOLOGY_FLAG_IO_BRIDGES replaced

Respectively by

hwloc_topology_set_icache_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_ALL);
hwloc_topology_set_io_types_filter(topology, HWLOC_TYPE_FILTER_KEEP_IMPORTANT);

hwloc_topology_export_xml() and hwloc_topology_export_xmlbuffer() have a new flags argument

Flags may be used to force a hwloc-1.x-compatible XML export:

#if HWLOC_API_VERSION >= 0x20000
   if (need 1.x compatible XML export)
      hwloc_topology_export_xml(...., HWLOC_TOPOLOGY_EXPORT_XML_FLAG_V1);
   else /* need 2.x compatible XML export */
      hwloc_topology_export_xml(...., 0);
#else
   hwloc_topology_export_xml(....);
#endif

hwloc_topology_diff_load_xml(), hwloc_topology_diff_load_xmlbuffer(), hwloc_topology_diff_export_xml(), hwloc_topology_diff_export_xmlbuffer() and hwloc_topology_diff_destroy() lost the topology argument

The first argument (topology) isn't needed anymore.

Distances API totally rewritten

Now in hwloc/distances.h

hwloc_fill_object_sets() renamed

Renamed into hwloc_obj_add_children_sets().

hwloc_distribute() and hwloc_distributev() removed

Removed, deprecated by hwloc_distrib()

obj->online_cpuset removed

The field has been removed from hwloc_obj_t. Offline are simply listed in the complete_cpuset as previously.

obj->os_level removed

The object field has been removed.

HWLOC_MEMBIND_REPLICATE removed

Not available anymore (no supported operating system supports it).

*_membind_nodeset() memory binding interfaces deprecated

Use the variant without _nodeset suffix and pass the new HWLOC_MEMBIND_BYNODESET flag

hwloc_cpuset_from/to_nodeset_strict() deprecated

Now useless since all topologies are NUMA. Use the variant without the _strict suffix

Custom interface removed

hwloc_topology_set_custom(), hwloc_custom_insert_topology() and hwloc_custom_insert_group_object_by_parent() removed from the API.

The corresponding hwloc-assembler and hwloc-assembler-remote command-line tools also removed.

The custom interface is not available anymore. Topologies always start with object with valid cpusets and nodesets.