NAME

       Topology differences -

   Data Structures
       union hwloc_topology_diff_obj_attr_u
       union hwloc_topology_diff_u

   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.

Typedef Documentation

   typedef enum hwloc_topology_diff_obj_attr_type_e  hwloc_topology_diff_obj_attr_type_t
       Type of one object attribute difference.

   typedef union hwloc_topology_diff_u *  hwloc_topology_diff_t
       One element of a difference list between two topologies.

   typedef enum hwloc_topology_diff_type_e  hwloc_topology_diff_type_t
       Type of one element of a difference list.

Enumeration Type Documentation

   enum hwloc_topology_diff_apply_flags_e
       Flags to be given to hwloc_topology_diff_apply().

       Enumerator

       HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE
              Apply topology diff in reverse direction.

   enum hwloc_topology_diff_obj_attr_type_e
       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.

   enum hwloc_topology_diff_type_e
       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_ttopology, hwloc_topology_diff_tdiff, unsigned longflags)
       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 before patching.

       If the difference cannot be applied entirely, all previous applied portions 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 portion could not be applied.

    int hwloc_topology_diff_build (hwloc_topology_ttopology, hwloc_topology_tnewtopology, unsigned longflags,
       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 are
       added or removed), a special diff entry of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX is queued. The
       computation of the diff does not continue under 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 NULL if there is no difference between the topologies.

           1 if the difference is too complex (for instance if some objects are added or removed), some entries
           in the list will be of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX and 1 is returned.

           -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 as a list to hwloc_topology_diff_destroy().

    int hwloc_topology_diff_destroy (hwloc_topology_ttopology, hwloc_topology_diff_tdiff)
       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_ttopology, hwloc_topology_diff_tdiff, 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_ttopology, hwloc_topology_diff_tdiff, 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_ttopology, 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_ttopology, const char *xmlbuffer, intbuflen,
       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.

Author

       Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code.