Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
hwlocality_diff(3)	   Library Functions Manual	    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.

       Returns
	   0.

   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.

       Returns
	   0 on	success, -1 on error.

   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.

       Returns
	   0 on	success, -1 on error.

       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.

       Returns
	   0 on	success, -1 on error.

       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. Build a list of
       differences from	the XML	memory buffer given at xmlbuffer and of	length
       buflen (including an ending \0).	 This  buffer  may  have  been	filled
       earlier with hwloc_topology_diff_export_xmlbuffer().

       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.

       Returns
	   0 on	success, -1 on error.

       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.

Hardware Locality (hwloc)	Version	2.11.2		    hwlocality_diff(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=hwloc_topology_diff_destroy&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help