.TH "hwlocality_memattrs_manage" 3 "Version 2.10.0rc2" "Hardware Locality (hwloc)" \" -*- nroff -*- .ad l .nh .SH NAME hwlocality_memattrs_manage \- Managing memory attributes .SH SYNOPSIS .br .PP .SS "Enumerations" .in +1c .ti -1c .RI "enum \fBhwloc_memattr_flag_e\fP { \fBHWLOC_MEMATTR_FLAG_HIGHER_FIRST\fP = (1UL<<0), \fBHWLOC_MEMATTR_FLAG_LOWER_FIRST\fP = (1UL<<1), \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP = (1UL<<2) }" .br .in -1c .SS "Functions" .in +1c .ti -1c .RI "int \fBhwloc_memattr_get_name\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, const char **name)" .br .ti -1c .RI "int \fBhwloc_memattr_get_flags\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, unsigned long *flags)" .br .ti -1c .RI "int \fBhwloc_memattr_register\fP (\fBhwloc_topology_t\fP topology, const char *name, unsigned long flags, \fBhwloc_memattr_id_t\fP *id)" .br .ti -1c .RI "int \fBhwloc_memattr_set_value\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, \fBhwloc_obj_t\fP target_node, struct \fBhwloc_location\fP *initiator, unsigned long flags, hwloc_uint64_t value)" .br .ti -1c .RI "int \fBhwloc_memattr_get_targets\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, struct \fBhwloc_location\fP *initiator, unsigned long flags, unsigned *nr, \fBhwloc_obj_t\fP *targets, hwloc_uint64_t *values)" .br .ti -1c .RI "int \fBhwloc_memattr_get_initiators\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, \fBhwloc_obj_t\fP target_node, unsigned long flags, unsigned *nr, struct \fBhwloc_location\fP *initiators, hwloc_uint64_t *values)" .br .in -1c .SH "Detailed Description" .PP .SH "Enumeration Type Documentation" .PP .SS "enum \fBhwloc_memattr_flag_e\fP" .PP Memory attribute flags\&. Given to \fBhwloc_memattr_register()\fP and returned by \fBhwloc_memattr_get_flags()\fP\&. .PP \fBEnumerator\fP .in +1c .TP \fB\fIHWLOC_MEMATTR_FLAG_HIGHER_FIRST \fP\fP The best nodes for this memory attribute are those with the higher values\&. For instance Bandwidth\&. .TP \fB\fIHWLOC_MEMATTR_FLAG_LOWER_FIRST \fP\fP The best nodes for this memory attribute are those with the lower values\&. For instance Latency\&. .TP \fB\fIHWLOC_MEMATTR_FLAG_NEED_INITIATOR \fP\fP The value returned for this memory attribute depends on the given initiator\&. For instance Bandwidth and Latency, but not Capacity\&. .SH "Function Documentation" .PP .SS "int hwloc_memattr_get_flags (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, unsigned long * flags)" .PP Return the flags of the given attribute\&. Flags are a OR'ed set of \fBhwloc_memattr_flag_e\fP\&. .PP \fBReturns\fP .RS 4 0 on success\&. .PP -1 with errno set to \fCEINVAL\fP if the attribute does not exist\&. .RE .PP .SS "int hwloc_memattr_get_initiators (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, \fBhwloc_obj_t\fP target_node, unsigned long flags, unsigned * nr, struct \fBhwloc_location\fP * initiators, hwloc_uint64_t * values)" .PP Return the initiators that have values for a given attribute for a specific target NUMA node\&. Return initiators for the given attribute and target node in the \fCinitiators\fP array\&. If \fCvalues\fP is not \fCNULL\fP, the corresponding attribute values are stored in the array it points to\&. .PP On input, \fCnr\fP points to the number of initiators that may be stored in the array \fCinitiators\fP (and \fCvalues\fP)\&. On output, \fCnr\fP points to the number of initiators (and values) that were actually found, even if some of them couldn't be stored in the array\&. Initiators that couldn't be stored are ignored, but the function still returns success (\fC0\fP)\&. The caller may find out by comparing the value pointed by \fCnr\fP before and after the function call\&. .PP The returned initiators should not be modified or freed, they belong to the topology\&. .PP \fCflags\fP must be \fC0\fP for now\&. .PP If the attribute does not relate to a specific initiator (it does not have the flag \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP), no initiator is returned\&. .PP \fBReturns\fP .RS 4 0 on success or -1 on error\&. .RE .PP \fBNote\fP .RS 4 This function is meant for tools and debugging (listing internal information) rather than for application queries\&. Applications should rather select useful NUMA nodes with \fBhwloc_get_local_numanode_objs()\fP and then look at their attribute values for some relevant initiators\&. .RE .PP .SS "int hwloc_memattr_get_name (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, const char ** name)" .PP Return the name of a memory attribute\&. .PP \fBReturns\fP .RS 4 0 on success\&. .PP -1 with errno set to \fCEINVAL\fP if the attribute does not exist\&. .RE .PP .SS "int hwloc_memattr_get_targets (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, struct \fBhwloc_location\fP * initiator, unsigned long flags, unsigned * nr, \fBhwloc_obj_t\fP * targets, hwloc_uint64_t * values)" .PP Return the target NUMA nodes that have some values for a given attribute\&. Return targets for the given attribute in the \fCtargets\fP array (for the given initiator if any)\&. If \fCvalues\fP is not \fCNULL\fP, the corresponding attribute values are stored in the array it points to\&. .PP On input, \fCnr\fP points to the number of targets that may be stored in the array \fCtargets\fP (and \fCvalues\fP)\&. On output, \fCnr\fP points to the number of targets (and values) that were actually found, even if some of them couldn't be stored in the array\&. Targets that couldn't be stored are ignored, but the function still returns success (\fC0\fP)\&. The caller may find out by comparing the value pointed by \fCnr\fP before and after the function call\&. .PP The returned targets should not be modified or freed, they belong to the topology\&. .PP Argument \fCinitiator\fP is ignored if the attribute does not relate to a specific initiator (it does not have the flag \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP)\&. Otherwise \fCinitiator\fP may be non \fCNULL\fP to report only targets that have a value for that initiator\&. .PP \fCflags\fP must be \fC0\fP for now\&. .PP \fBNote\fP .RS 4 This function is meant for tools and debugging (listing internal information) rather than for application queries\&. Applications should rather select useful NUMA nodes with \fBhwloc_get_local_numanode_objs()\fP and then look at their attribute values\&. .RE .PP \fBReturns\fP .RS 4 0 on success or -1 on error\&. .RE .PP \fBNote\fP .RS 4 The initiator \fCinitiator\fP should be of type \fBHWLOC_LOCATION_TYPE_CPUSET\fP when referring to accesses performed by CPU cores\&. \fBHWLOC_LOCATION_TYPE_OBJECT\fP is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs\&. .RE .PP .SS "int hwloc_memattr_register (\fBhwloc_topology_t\fP topology, const char * name, unsigned long flags, \fBhwloc_memattr_id_t\fP * id)" .PP Register a new memory attribute\&. Add a specific memory attribute that is not defined in \fBhwloc_memattr_id_e\fP\&. Flags are a OR'ed set of \fBhwloc_memattr_flag_e\fP\&. It must contain at least one of \fBHWLOC_MEMATTR_FLAG_HIGHER_FIRST\fP or \fBHWLOC_MEMATTR_FLAG_LOWER_FIRST\fP\&. .PP \fBReturns\fP .RS 4 0 on success\&. .PP -1 with errno set to \fCEBUSY\fP if another attribute already uses this name\&. .RE .PP .SS "int hwloc_memattr_set_value (\fBhwloc_topology_t\fP topology, \fBhwloc_memattr_id_t\fP attribute, \fBhwloc_obj_t\fP target_node, struct \fBhwloc_location\fP * initiator, unsigned long flags, hwloc_uint64_t value)" .PP 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 \fBHWLOC_MEMATTR_FLAG_NEED_INITIATOR\fP), location \fCinitiator\fP is ignored and may be \fCNULL\fP\&. .PP The initiator will be copied into the topology, the caller should free anything allocated to store the initiator, for instance the cpuset\&. .PP \fCflags\fP must be \fC0\fP for now\&. .PP \fBNote\fP .RS 4 The initiator \fCinitiator\fP should be of type \fBHWLOC_LOCATION_TYPE_CPUSET\fP when referring to accesses performed by CPU cores\&. \fBHWLOC_LOCATION_TYPE_OBJECT\fP is currently unused internally by hwloc, but users may for instance use it to provide custom information about host memory accesses performed by GPUs\&. .RE .PP \fBReturns\fP .RS 4 0 on success or -1 on error\&. .RE .PP .SH "Author" .PP Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.