Modifying a loaded Topology

## Enumerations

enum | hwloc_restrict_flags_e { HWLOC_RESTRICT_FLAG_REMOVE_CPULESS, HWLOC_RESTRICT_FLAG_ADAPT_MISC, HWLOC_RESTRICT_FLAG_ADAPT_IO }

## Functions

int | hwloc_topology_restrict (hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, unsigned long flags)
hwloc_obj_t | hwloc_topology_insert_misc_object (hwloc_topology_t topology, hwloc_obj_t parent, const char *name)
hwloc_obj_t | hwloc_topology_alloc_group_object (hwloc_topology_t topology)
hwloc_obj_t | hwloc_topology_insert_group_object (hwloc_topology_t topology, hwloc_obj_t group)
int | hwloc_obj_add_other_obj_sets (hwloc_obj_t dst, hwloc_obj_t src)

## Detailed Description

## Enumeration Type Documentation

## hwloc_restrict_flags_e

enum hwloc_restrict_flags_e

Flags to be given to hwloc_topology_restrict().

Enumerator
HWLOC_RESTRICT_FLAG_REMOVE_CPULESS | Remove all objects that became CPU-less. By default, only objects that contain no PU and no memory are removed.
HWLOC_RESTRICT_FLAG_ADAPT_MISC | Move Misc objects to ancestors if their parents are removed during restriction. If this flag is not set, Misc objects are removed when their parents are removed.
HWLOC_RESTRICT_FLAG_ADAPT_IO | Move I/O objects to ancestors if their parents are removed during restriction. If this flag is not set, I/O devices and bridges are removed when their parents are removed.

## Function Documentation

## hwloc_obj_add_other_obj_sets()

int hwloc_obj_add_other_obj_sets | ( | hwloc_obj_t | dst,
|  | hwloc_obj_t | src
| ) |  |

Setup object cpusets/nodesets by OR'ing another object's sets.

For each defined cpuset or nodeset in `src`, allocate the corresponding set in `dst` and add `src` to it by OR'ing sets.

This function is convenient between hwloc_topology_alloc_group_object() and hwloc_topology_insert_group_object(). It builds the sets of the new Group that will be inserted as a new intermediate parent of several objects.

## hwloc_topology_alloc_group_object()

hwloc_obj_t hwloc_topology_alloc_group_object | ( | hwloc_topology_t | topology | ) |

Allocate a Group object to insert later with hwloc_topology_insert_group_object().

This function returns a new Group object. The caller should (at least) initialize its sets before inserting the object. See hwloc_topology_insert_group_object().

The `subtype` object attribute may be set to display something else than "Group" as the type name for this object in lstopo. Custom name/value info pairs may be added with hwloc_obj_add_info() after insertion.

The `kind` group attribute should be 0. The `subkind` group attribute may be set to identify multiple Groups of the same level.

It is recommended not to set any other object attribute before insertion, since the Group may get discarded during insertion.

The object will be destroyed if passed to hwloc_topology_insert_group_object() without any set defined.

## hwloc_topology_insert_group_object()

hwloc_obj_t hwloc_topology_insert_group_object | ( | hwloc_topology_t | topology,
|  | hwloc_obj_t | group
| ) |  |

Add more structure to the topology by adding an intermediate Group.

The caller should first allocate a new Group object with hwloc_topology_alloc_group_object(). Then it must setup at least one of its CPU or node sets to specify the final location of the Group in the topology. Then the object can be passed to this function for actual insertion in the topology.

Either the cpuset or nodeset field (or both, if compatible) must be set to a non-empty bitmap. The complete_cpuset or complete_nodeset may be set instead if inserting with respect to the complete topology (including disallowed, offline or unknown objects).

It grouping several objects, hwloc_obj_add_other_obj_sets() is an easy way to build the Group sets iteratively.

These sets cannot be larger than the current topology, or they would get restricted silently.

The core will setup the other sets after actual insertion.

Returns
  The inserted object if it was properly inserted.
  An existing object if the Group was discarded because the topology already contained an object at the same location (the Group did not add any locality information). Any name/info key pair set before inserting is appended to the existing object.
  `NULL` if the insertion failed because of conflicting sets in topology tree.
  `NULL` if Group objects are filtered-out of the topology (HWLOC_TYPE_FILTER_KEEP_NONE).
  `NULL` if the object was discarded because no set was initialized in the Group before insert, or all of them were empty.

## hwloc_topology_insert_misc_object()

hwloc_obj_t hwloc_topology_insert_misc_object | ( | hwloc_topology_t | topology,
|  | hwloc_obj_t | parent,
|  | const char * | name
| ) |  |

Add a MISC object as a leaf of the topology.

A new MISC object will be created and inserted into the topology at the position given by parent. It is appended to the list of existing Misc children, without ever adding any intermediate hierarchy level. This is useful for annotating the topology without actually changing the hierarchy.

`name` is supposed to be unique across all Misc objects in the topology. It will be duplicated to setup the new object attributes.

The new leaf object will not have any `cpuset`.

Returns
  the newly-created object
  `NULL` on error.
  `NULL` if Misc objects are filtered-out of the topology (HWLOC_TYPE_FILTER_KEEP_NONE).

Note
  If `name` contains some non-printable characters, they will be dropped when exporting to XML, see hwloc_topology_export_xml() in hwloc/export.h.

## hwloc_topology_restrict()

int hwloc_topology_restrict | ( | hwloc_topology_t restrict | topology,
|  | hwloc_const_cpuset_t | cpuset,
|  | unsigned long | flags
| ) |  |

Restrict the topology to the given CPU set.

Topology `topology` is modified so as to remove all objects that are not included (or partially included) in the CPU set `cpuset`. All objects CPU and node sets are restricted accordingly.

`flags` is a OR'ed set of hwloc_restrict_flags_e.

Note
  This call may not be reverted by restricting back to a larger cpuset. Once dropped during restriction, objects may not be brought back, except by loading another topology with hwloc_topology_load().

Returns
  0 on success.
  -1 with errno set to EINVAL if the input cpuset is invalid. The topology is not modified in this case.
  -1 with errno set to ENOMEM on failure to allocate internal data. The topology is reinitialized in this case. It should be either destroyed with hwloc_topology_destroy() or configured and loaded again.