include/hwloc/diff.h

/*
 * Copyright © 2013-2020 Inria.  All rights reserved.
 * See COPYING in top-level directory.
 */

/** \file
 * \brief Topology differences.
 */

#ifndef HWLOC_DIFF_H
#define HWLOC_DIFF_H

#ifndef HWLOC_H
#error Please include the main hwloc.h instead
#endif


#ifdef __cplusplus
extern "C" {
#elif 0
}
#endif


/** \defgroup hwlocality_diff Topology differences
 *
 * 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.
 *
 * @{
 */


/** \brief Type of one object attribute difference.
 */
typedef enum hwloc_topology_diff_obj_attr_type_e {
  /** \brief 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_SIZE,

  /** \brief 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_NAME,
  /** \brief 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.
   */
  HWLOC_TOPOLOGY_DIFF_OBJ_ATTR_INFO
} hwloc_topology_diff_obj_attr_type_t;

/** \brief One object attribute difference.
 */
union hwloc_topology_diff_obj_attr_u {
  struct hwloc_topology_diff_obj_attr_generic_s {
    /* each part of the union must start with these */
    hwloc_topology_diff_obj_attr_type_t type;
  } generic;

  /** \brief Integer attribute modification with an optional index. */
  struct hwloc_topology_diff_obj_attr_uint64_s {
    /* used for storing integer attributes */
    hwloc_topology_diff_obj_attr_type_t type;
    hwloc_uint64_t index; /* not used for SIZE */
    hwloc_uint64_t oldvalue;
    hwloc_uint64_t newvalue;
  } uint64;

  /** \brief String attribute modification with an optional name */
  struct hwloc_topology_diff_obj_attr_string_s {
    /* used for storing name and info pairs */
    hwloc_topology_diff_obj_attr_type_t type;
    char *name; /* not used for NAME */
    char *oldvalue;
    char *newvalue;
  } string;
};


/** \brief Type of one element of a difference list.
 */
typedef enum hwloc_topology_diff_type_e {
  /** \brief An object attribute was changed.
   * The union is a hwloc_topology_diff_u::hwloc_topology_diff_obj_attr_s.
   */
  HWLOC_TOPOLOGY_DIFF_OBJ_ATTR,

  /** \brief 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.
   */
  HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX
} hwloc_topology_diff_type_t;

/** \brief One element of a difference list between two topologies.
 */
typedef union hwloc_topology_diff_u {
  struct hwloc_topology_diff_generic_s {
    /* each part of the union must start with these */
    hwloc_topology_diff_type_t type;
    union hwloc_topology_diff_u * next; /* pointer to the next element of the list, or NULL */
  } generic;

  /* A difference in an object attribute. */
  struct hwloc_topology_diff_obj_attr_s {
    hwloc_topology_diff_type_t type; /* must be ::HWLOC_TOPOLOGY_DIFF_OBJ_ATTR */
    union hwloc_topology_diff_u * next;
    /* List of attribute differences for a single object */
    int obj_depth;
    unsigned obj_index;
    union hwloc_topology_diff_obj_attr_u diff;
  } obj_attr;

  /* A difference that is too complex. */
  struct hwloc_topology_diff_too_complex_s {
    hwloc_topology_diff_type_t type; /* must be ::HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX */
    union hwloc_topology_diff_u * next;
    /* Where we had to stop computing the diff in the first topology */
    int obj_depth;
    unsigned obj_index;
  } too_complex;
} * hwloc_topology_diff_t;


/** \brief Compute the difference between 2 topologies.
 *
 * The difference is stored as a list of ::hwloc_topology_diff_t entries
 * starting at \p 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.
 *
 * \return 0 if the difference can be represented properly.
 *
 * \return 0 with \p diff pointing to NULL if there is no difference
 * between the topologies.
 *
 * \return 1 if the difference is too complex (see above). Some entries in
 * the list will be of type ::HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX.
 *
 * \return -1 on any other error.
 *
 * \note \p flags is currently not used. It should be 0.
 *
 * \note The output diff has to be freed with hwloc_topology_diff_destroy().
 *
 * \note 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.
 *
 * \note 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).
*/
HWLOC_DECLSPEC int hwloc_topology_diff_build(hwloc_topology_t topology, hwloc_topology_t newtopology, unsigned long flags, hwloc_topology_diff_t *diff);

/** \brief Flags to be given to hwloc_topology_diff_apply().
 */
enum hwloc_topology_diff_apply_flags_e {
  /** \brief Apply topology diff in reverse direction.
   * \hideinitializer
   */
  HWLOC_TOPOLOGY_DIFF_APPLY_REVERSE = (1UL<<0)
};

/** \brief Apply a topology diff to an existing topology.
 *
 * \p 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.
 *
 * \return 0 on success.
 *
 * \return -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.
 */
HWLOC_DECLSPEC int hwloc_topology_diff_apply(hwloc_topology_t topology, hwloc_topology_diff_t diff, unsigned long flags);

/** \brief Destroy a list of topology differences.
 */
HWLOC_DECLSPEC int hwloc_topology_diff_destroy(hwloc_topology_diff_t diff);

/** \brief Load a list of topology differences from a XML file.
 *
 * If not \c NULL, \p 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.
 */
HWLOC_DECLSPEC int hwloc_topology_diff_load_xml(const char *xmlpath, hwloc_topology_diff_t *diff, char **refname);

/** \brief Export a list of topology differences to a XML file.
 *
 * If not \c NULL, \p 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.
 */
HWLOC_DECLSPEC int hwloc_topology_diff_export_xml(hwloc_topology_diff_t diff, const char *refname, const char *xmlpath);

/** \brief Load a list of topology differences from a XML buffer.
 *
 * If not \c NULL, \p 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.
  */
HWLOC_DECLSPEC int hwloc_topology_diff_load_xmlbuffer(const char *xmlbuffer, int buflen, hwloc_topology_diff_t *diff, char **refname);

/** \brief Export a list of topology differences to a XML buffer.
 *
 * If not \c NULL, \p 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().
 */
HWLOC_DECLSPEC int hwloc_topology_diff_export_xmlbuffer(hwloc_topology_diff_t diff, const char *refname, char **xmlbuffer, int *buflen);

/** @} */


#ifdef __cplusplus
} /* extern "C" */
#endif


#endif /* HWLOC_DIFF_H */