Open MPI logo

Portable Hardware Locality (hwloc) Documentation: v1.9.1

  |   Home   |   Support   |   FAQ   |  
Topology differences

Data Structures

union  hwloc_topology_diff_obj_attr_u
 
struct  hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s
 
struct  hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s
 
struct  hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s
 
union  hwloc_topology_diff_u
 
struct  hwloc_topology_diff_u::hwloc_topology_diff_generic_s
 
struct  hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s
 
struct  hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s
 

Typedefs

typedef enum
hwloc_topology_diff_obj_attr_type_e 
hwloc_topology_diff_obj_attr_type_t
 
typedef enum
hwloc_topology_diff_type_e 
hwloc_topology_diff_type_t
 
typedef union
hwloc_topology_diff_u
hwloc_topology_diff_t
 

Enumerations

enum  hwloc_topology_diff_obj_attr_type_e { HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE, HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME, HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO }
 
enum  hwloc_topology_diff_type_e { HWLOC_TOPOLOGY_DIFF_OBJ_ATTR, HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX }
 
enum  hwloc_topology_diff_apply_flags_e { HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE }
 

Functions

int hwloc_topology_diff_build (hwloc_topology_t topology, hwloc_topology_t newtopology, unsigned long flags, hwloc_topology_diff_t *diff)
 
int hwloc_topology_diff_apply (hwloc_topology_t topology, hwloc_topology_diff_t diff, unsigned long flags)
 
int hwloc_topology_diff_destroy (hwloc_topology_t topology, hwloc_topology_diff_t diff)
 
int hwloc_topology_diff_load_xml (hwloc_topology_t topology, const char *xmlpath, hwloc_topology_diff_t *diff, char **refname)
 
int hwloc_topology_diff_export_xml (hwloc_topology_t topology, hwloc_topology_diff_t diff, const char *refname, const char *xmlpath)
 
int hwloc_topology_diff_load_xmlbuffer (hwloc_topology_t topology, const char *xmlbuffer, int buflen, hwloc_topology_diff_t *diff, char **refname)
 
int hwloc_topology_diff_export_xmlbuffer (hwloc_topology_t topology, hwloc_topology_diff_t diff, const char *refname, char **xmlbuffer, int *buflen)
 

Detailed Description

Applications that manipulate many similar topologies, for instance one for each node of a homogeneous cluster, may want to compress topologies to reduce the memory footprint.

This file offers a way to manipulate the difference between topologies and export/import it to/from XML. Compression may therefore be achieved by storing one topology entirely while the others are only described by their differences with the former. The actual topology can be reconstructed when actually needed by applying the precomputed difference to the reference topology.

This interface targets very similar nodes. Only very simple differences between topologies are actually supported, for instance a change in the memory size, the name of the object, or some info attribute. More complex differences such as adding or removing objects cannot be represented in the difference structures and therefore return errors.

It means that there is no need to apply the difference when looking at the tree organization (how many levels, how many objects per level, what kind of objects, CPU and node sets, etc) and when binding to objects. However the difference must be applied when looking at object attributes such as the name, the memory size or info attributes.

Typedef Documentation

Type of one object attribute difference.

One element of a difference list between two topologies.

Type of one element of a difference list.

Enumeration Type Documentation

Flags to be given to hwloc_topology_diff_apply().

Enumerator
HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE 

Apply topology diff in reverse direction.

Type of one object attribute difference.

Enumerator
HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_SIZE 

The object local memory is modified. The union is a hwloc_topology_diff_obj_attr_uint64_s (and the index field is ignored).

HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_NAME 

The object name is modified. The union is a hwloc_topology_diff_obj_attr_string_s (and the name field is ignored).

HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO 

the value of an info attribute is modified. The union is a hwloc_topology_diff_obj_attr_string_s.

Type of one element of a difference list.

Enumerator
HWLOC_TOPOLOGY_DIFF_OBJ_ATTR 
HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX 

Function Documentation

int hwloc_topology_diff_apply ( hwloc_topology_t  topology,
hwloc_topology_diff_t  diff,
unsigned long  flags 
)

Apply a topology diff to an existing topology.

flags is an OR'ed set of hwloc_topology_diff_apply_flags_e.

The new topology is modified in place. hwloc_topology_dup() may be used to duplicate it before patching.

If the difference cannot be applied entirely, all previous applied elements are unapplied before returning.

Returns
0 on success.
-N if applying the difference failed while trying to apply the N-th part of the difference. For instance -1 is returned if the very first difference element could not be applied.
int hwloc_topology_diff_build ( hwloc_topology_t  topology,
hwloc_topology_t  newtopology,
unsigned long  flags,
hwloc_topology_diff_t diff 
)

Compute the difference between 2 topologies.

The difference is stored as a list of hwloc_topology_diff_t entries starting at diff. It is computed by doing a depth-first traversal of both topology trees simultaneously.

If the difference between 2 objects is too complex to be represented (for instance if some objects have different types, or different numbers of children), a special diff entry of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX is queued. The computation of the diff does not continue below these objects. So each such diff entry means that the difference between two subtrees could not be computed.

Returns
0 if the difference can be represented properly.
0 with diff pointing to NULL if there is no difference between the topologies.
1 if the difference is too complex (see above). Some entries in the list will be of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX.
-1 on any other error.
Note
flags is currently not used. It should be 0.
The output diff has to be freed with hwloc_topology_diff_destroy().
The output diff can only be exported to XML or passed to hwloc_topology_diff_apply() if 0 was returned, i.e. if no entry of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX is listed.
The output diff may be modified by removing some entries from the list. The removed entries should be freed by passing them to to hwloc_topology_diff_destroy() (possible as another list).
int hwloc_topology_diff_destroy ( hwloc_topology_t  topology,
hwloc_topology_diff_t  diff 
)

Destroy a list of topology differences.

Note
The topology parameter must be a valid topology but it is not required that it is related to diff.
int hwloc_topology_diff_export_xml ( hwloc_topology_t  topology,
hwloc_topology_diff_t  diff,
const char *  refname,
const char *  xmlpath 
)

Export a list of topology differences to a XML file.

If not NULL, refname defines an identifier string for the reference topology which was used as a base when computing this difference. This identifier is usually the name of the other XML file that contains the reference topology. This attribute is given back when reading the diff from XML.

Note
The topology parameter must be a valid topology but it is not required that it is related to diff.
int hwloc_topology_diff_export_xmlbuffer ( hwloc_topology_t  topology,
hwloc_topology_diff_t  diff,
const char *  refname,
char **  xmlbuffer,
int *  buflen 
)

Export a list of topology differences to a XML buffer.

If not NULL, refname defines an identifier string for the reference topology which was used as a base when computing this difference. This identifier is usually the name of the other XML file that contains the reference topology. This attribute is given back when reading the diff from XML.

Note
The XML buffer should later be freed with hwloc_free_xmlbuffer().
The topology parameter must be a valid topology but it is not required that it is related to diff.
int hwloc_topology_diff_load_xml ( hwloc_topology_t  topology,
const char *  xmlpath,
hwloc_topology_diff_t diff,
char **  refname 
)

Load a list of topology differences from a XML file.

If not NULL, refname will be filled with the identifier string of the reference topology for the difference file, if any was specified in the XML file. This identifier is usually the name of the other XML file that contains the reference topology.

Note
The topology parameter must be a valid topology but it is not required that it is related to diff.
the pointer returned in refname should later be freed by the caller.
int hwloc_topology_diff_load_xmlbuffer ( hwloc_topology_t  topology,
const char *  xmlbuffer,
int  buflen,
hwloc_topology_diff_t diff,
char **  refname 
)

Load a list of topology differences from a XML buffer.

If not NULL, refname will be filled with the identifier string of the reference topology for the difference file, if any was specified in the XML file. This identifier is usually the name of the other XML file that contains the reference topology.

Note
The topology parameter must be a valid topology but it is not required that it is related to diff.
the pointer returned in refname should later be freed by the caller.