Hardware Locality (hwloc): Managing memory attributes

Hardware Locality (hwloc) 2.14.0rc1

Enumerations | Functions
Managing memory attributes

## Enumerations
enum | hwloc_memattr_flag_e { HWLOC_MEMATTR_FLAG_HIGHER_FIRST = (1UL<<0) , HWLOC_MEMATTR_FLAG_LOWER_FIRST = (1UL<<1) , HWLOC_MEMATTR_FLAG_NEED_INITIATOR = (1UL<<2) }

## Functions
int | hwloc_memattr_get_name (hwloc_topology_t topology, hwloc_memattr_id_t attribute, const char **name)
int | hwloc_memattr_get_flags (hwloc_topology_t topology, hwloc_memattr_id_t attribute, unsigned long *flags)
int | hwloc_memattr_register (hwloc_topology_t topology, const char *name, unsigned long flags, hwloc_memattr_id_t *id)
int | hwloc_memattr_set_value (hwloc_topology_t topology, hwloc_memattr_id_t attribute, hwloc_obj_t target_node, struct hwloc_location *initiator, unsigned long flags, hwloc_uint64_t value)

## Detailed Description

Memory attribues are identified by an ID (hwloc_memattr_id_t) and a name. hwloc_memattr_get_name() and hwloc_memattr_get_by_name() convert between them (or return error if the attribute does not exist).

The set of valid hwloc_memattr_id_t is a contigous set starting at `0`. It first contains predefined attributes, as listed in hwloc_memattr_id_e (from `0` to `HWLOC_MEMATTR_ID_MAX-1`). Then custom attributes may be dynamically registered with hwloc_memattr_register(). They will get the following IDs (`HWLOC_MEMATTR_ID_MAX` for the first one, etc.).

To iterate over all valid attributes (either predefined or dynamically registered custom ones), one may iterate over IDs starting from `0` until hwloc_memattr_get_name() or hwloc_memattr_get_flags() returns an error.

The values for an existing attribute or for custom dynamically registered ones may be set or modified with hwloc_memattr_set_value().

## Enumeration Type Documentation

## ◆ hwloc_memattr_flag_e

enum hwloc_memattr_flag_e

Memory attribute flags. Given to hwloc_memattr_register() and returned by hwloc_memattr_get_flags().

Enumerator
HWLOC_MEMATTR_FLAG_HIGHER_FIRST | The best nodes for this memory attribute are those with the higher values. For instance Bandwidth.
HWLOC_MEMATTR_FLAG_LOWER_FIRST | The best nodes for this memory attribute are those with the lower values. For instance Latency.
HWLOC_MEMATTR_FLAG_NEED_INITIATOR | The value returned for this memory attribute depends on the given initiator. For instance Bandwidth and Latency, but not Capacity.

## Function Documentation

## ◆ hwloc_memattr_get_flags()

int hwloc_memattr_get_flags | ( | hwloc_topology_t | topology,
|  | hwloc_memattr_id_t | attribute,
|  | unsigned long * | flags )

Return the flags of the given attribute.

Flags are a OR'ed set of hwloc_memattr_flag_e.

The output pointer `flags` cannot be `NULL`.

Returns
  0 on success.
  -1 with errno set to `EINVAL` if the attribute does not exist.

## ◆ hwloc_memattr_get_name()

int hwloc_memattr_get_name | ( | hwloc_topology_t | topology,
|  | hwloc_memattr_id_t | attribute,
|  | const char ** | name )

Return the name of a memory attribute.

The output pointer `name` cannot be `NULL`.

Returns
  0 on success.
  -1 with errno set to `EINVAL` if the attribute does not exist.

## ◆ hwloc_memattr_register()

int hwloc_memattr_register | ( | hwloc_topology_t | topology,
|  | const char * | name,
|  | unsigned long | flags,
|  | hwloc_memattr_id_t * | id )

Register a new memory attribute.

Add a new custom memory attribute. Flags are a OR'ed set of hwloc_memattr_flag_e. It must contain one of HWLOC_MEMATTR_FLAG_HIGHER_FIRST or HWLOC_MEMATTR_FLAG_LOWER_FIRST but not both.

The new attribute `id` is immediately after the last existing attribute ID (which is either the ID of the last registered attribute if any, or the ID of the last predefined attribute in hwloc_memattr_id_e).

Returns
  0 on success.
  -1 with errno set to `EINVAL` if an invalid set of flags is given.
  -1 with errno set to `EBUSY` if another attribute already uses this name.

## ◆ hwloc_memattr_set_value()

int hwloc_memattr_set_value | ( | hwloc_topology_t | topology,
|  | hwloc_memattr_id_t | attribute,
|  | hwloc_obj_t | target_node,
|  | struct hwloc_location * | initiator,
|  | unsigned long | flags,
|  | hwloc_uint64_t | value )

Set an attribute value for a specific target NUMA node.

If the attribute does not relate to a specific initiator (it does not have the flag HWLOC_MEMATTR_FLAG_NEED_INITIATOR), location `initiator` is ignored and may be `NULL`.

The initiator will be copied into the topology, the caller should free anything allocated to store the initiator, for instance the cpuset.

`target_node` cannot be `NULL`.

`attribute` cannot be HWLOC_MEMATTR_ID_CAPACITY or HWLOC_MEMATTR_ID_LOCALITY.

`flags` must be `0` for now.

Note
  The initiator `initiator` should be of type HWLOC_LOCATION_TYPE_CPUSET when referring to accesses performed by CPU cores. HWLOC_LOCATION_TYPE_OBJECT is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs.

Returns
  0 on success or -1 on error.