manpagez: man pages & more
man hwloc_topology_diff_obj_attr_u(3)
Home | html | info | man
hwlocality_diff(3)         Hardware Locality (hwloc)        hwlocality_diff(3)




NAME

       hwlocality_diff - Topology differences


SYNOPSIS

   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_diff_t diff)
       int hwloc_topology_diff_load_xml (const char *xmlpath,
           hwloc_topology_diff_t *diff, char **refname)
       int hwloc_topology_diff_export_xml (hwloc_topology_diff_t diff, const
           char *refname, const char *xmlpath)
       int hwloc_topology_diff_load_xmlbuffer (const char *xmlbuffer, int
           buflen, hwloc_topology_diff_t *diff, char **refname)
       int hwloc_topology_diff_export_xmlbuffer (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.
       Differences between object sets or topology-wide allowed sets, cannot
       be represented either.

       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

   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_u::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_u::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_u::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
              An object attribute was changed. The union is a
              hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s.

       HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX
              The difference is too complex, it cannot be represented. The
              difference below this object has not been checked.
              hwloc_topology_diff_build() will return 1. The union is a
              hwloc_topology_diff_u::hwloc_topology_diff_too_complex_s.


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_diff_t diff)
       Destroy a list of topology differences.

   int hwloc_topology_diff_export_xml (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.

   int hwloc_topology_diff_export_xmlbuffer (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.

       The returned buffer ends with a \0 that is included in the returned
       length.

       Note
           The XML buffer should later be freed with hwloc_free_xmlbuffer().



   int hwloc_topology_diff_load_xml (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 pointer returned in refname should later be freed by the
           caller.



   int hwloc_topology_diff_load_xmlbuffer (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 pointer returned in refname should later be freed by the
           caller.




Author

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



Version 2.4.0                   Thu Nov 26 2020             hwlocality_diff(3)

hwloc 2.4.0 - Generated Sat Feb 6 14:38:57 CST 2021
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.