hwlocality_memattrs_manage(3) Library Functions Manual
NAME
hwlocality_memattrs_manage - Managing memory attributes
SYNOPSIS
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
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
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.
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.
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.
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_FLAG_ID_CAPACITY or
::HWLOC_MEMATTR_FLAG_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.
Author
Generated automatically by Doxygen for Hardware Locality (hwloc) from
the source code.
Hardware Locality (hwloc) Version 2.12.0 hwlocality_memattrs_manage(3)
hwloc 2.12.0 - Generated Fri May 9 07:18:16 CDT 2025