hwlocality...trs_manage(3)

💖 NAME 💖

hwlocality_memattrs_manage — Managing memory attributes. That's the whole vibe: we're managing memory attributes today, bestie. This is the hwlocality...trs_manage(3) page from the Library Functions Manual for Hardware Locality (hwloc) 🫶.

✨ 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)

Four functions, all returning int status codes. They're the main characters of this page, no cap.

🌸 Detailed Description 🌸

Memory attributes 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 an error if the attribute does not exist. Simple, iconic, done.

The set of valid hwloc_memattr_id_t is a contiguous 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. That's your stopping condition, bestie 🦋.

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. Higher = better, periodt.
• HWLOC_MEMATTR_FLAG_LOWER_FIRST — the best nodes for this memory attribute are those with the lower values. For instance Latency. Lower = better, no cap.
• 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 an 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 an 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.

🫶 Author 🫶

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

---

That's the whole page, bestie 💖 — brought to you by Hardware Locality (hwloc), version 2.15.0, on the hwlocality...trs_manage(3) page. The footer has no date line, so no invented date, periodt 🙈✨. Stay slay, and may all your attributes stay valid 🦋💜.