hwloc_obj Struct Reference

#include <hwloc.h>

Data Fields
hwloc_obj_type_t	type
unsigned	os_index
char *	name
struct hwloc_obj_memory_s	memory
union hwloc_obj_attr_u *	attr
unsigned	depth
unsigned	logical_index
signed	os_level
struct hwloc_obj *	next_cousin
struct hwloc_obj *	prev_cousin
struct hwloc_obj *	parent
unsigned	sibling_rank
struct hwloc_obj *	next_sibling
struct hwloc_obj *	prev_sibling
unsigned	arity
struct hwloc_obj **	children
struct hwloc_obj *	first_child
struct hwloc_obj *	last_child
void *	userdata
hwloc_cpuset_t	cpuset
hwloc_cpuset_t	complete_cpuset
hwloc_cpuset_t	online_cpuset
hwloc_cpuset_t	allowed_cpuset
hwloc_nodeset_t	nodeset
hwloc_nodeset_t	complete_nodeset
hwloc_nodeset_t	allowed_nodeset
struct hwloc_distances_s **	distances
unsigned	distances_count
struct hwloc_obj_info_s *	infos
unsigned	infos_count
int	symmetric_subtree

Detailed Description

Structure of a topology object.

Applications must not modify any field except hwloc_obj.userdata.

Field Documentation

allowed_cpuset

hwloc_cpuset_t hwloc_obj::allowed_cpuset

The CPU set of allowed logical processors.

This includes the CPUs contained in this object which are allowed for binding, i.e. passing them to the hwloc binding functions should not return permission errors. This is usually restricted by administration rules. Some of them may however be offline so binding to them may still not be possible, see online_cpuset.

Note

Its value must not be changed, hwloc_bitmap_dup() must be used instead.

allowed_nodeset

hwloc_nodeset_t hwloc_obj::allowed_nodeset

The set of allowed NUMA memory nodes.

This includes the NUMA memory nodes contained in this object which are allowed for memory allocation, i.e. passing them to NUMA node-directed memory allocation should not return permission errors. This is usually restricted by administration rules.

If there are no NUMA nodes in the machine, all the memory is close to this object, so allowed_nodeset is full.

Note

Its value must not be changed, hwloc_bitmap_dup() must be used instead.

arity

unsigned hwloc_obj::arity

Number of children.

attr

union hwloc_obj_attr_u* hwloc_obj::attr

Object type-specific Attributes, may be NULL if no attribute value was found.

children

struct hwloc_obj** hwloc_obj::children

Children, children[0 .. arity -1].

complete_cpuset

hwloc_cpuset_t hwloc_obj::complete_cpuset

The complete CPU set of logical processors of this object,.

This includes not only the same as the cpuset field, but also some CPUs for which topology information is unknown or incomplete, and the CPUs that are ignored when the HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM flag is not set. Thus no corresponding PU object may be found in the topology, because the precise position is undefined. It is however known that it would be somewhere under this object.

Note

Its value must not be changed, hwloc_bitmap_dup() must be used instead.

complete_nodeset

hwloc_nodeset_t hwloc_obj::complete_nodeset

The complete NUMA node set of this object,.

This includes not only the same as the nodeset field, but also some NUMA nodes for which topology information is unknown or incomplete, and the nodes that are ignored when the HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM flag is not set. Thus no corresponding NUMA node object may be found in the topology, because the precise position is undefined. It is however known that it would be somewhere under this object.

If there are no NUMA nodes in the machine, all the memory is close to this object, so complete_nodeset is full.

Note

Its value must not be changed, hwloc_bitmap_dup() must be used instead.

cpuset

hwloc_cpuset_t hwloc_obj::cpuset

CPUs covered by this object.

This is the set of CPUs for which there are PU objects in the topology under this object, i.e. which are known to be physically contained in this object and known how (the children path between this object and the PU objects).

If the HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM configuration flag is set, some of these CPUs may be offline, or not allowed for binding, see online_cpuset and allowed_cpuset.

Note

Its value must not be changed, hwloc_bitmap_dup() must be used instead.

depth

unsigned hwloc_obj::depth

Vertical index in the hierarchy.

For normal objects, this is the depth of the horizontal level that contains this object and its cousins of the same type. If the topology is symmetric, this is equal to the parent depth plus one, and also equal to the number of parent/child links from the root object to here.

For special objects (I/O and Misc) that are not in the main tree, this is a special negative value that corresponds to their dedicated level, see hwloc_get_type_depth() and hwloc_get_type_depth_e. Those special values can be passed to hwloc functions such hwloc_get_nbobjs_by_depth() as usual.

distances

struct hwloc_distances_s** hwloc_obj::distances

Distances between all objects at same depth below this object.

distances_count

unsigned hwloc_obj::distances_count

first_child

struct hwloc_obj* hwloc_obj::first_child

First child.

infos

struct hwloc_obj_info_s* hwloc_obj::infos

Array of stringified info type=name.

infos_count

unsigned hwloc_obj::infos_count

Size of infos array.

last_child

struct hwloc_obj* hwloc_obj::last_child

Last child.

logical_index

unsigned hwloc_obj::logical_index

Horizontal index in the whole list of similar objects, hence guaranteed unique across the entire machine. Could be a "cousin_rank" since it's the rank within the "cousin" list below.

memory

struct hwloc_obj_memory_s hwloc_obj::memory

Memory attributes.

name

char* hwloc_obj::name

Object-specific name if any. Mostly used for identifying OS devices and Misc objects where a name string is more useful than numerical indexes.

next_cousin

struct hwloc_obj* hwloc_obj::next_cousin

Next object of same type and depth.

next_sibling

struct hwloc_obj* hwloc_obj::next_sibling

Next object below the same parent.

nodeset

hwloc_nodeset_t hwloc_obj::nodeset

NUMA nodes covered by this object or containing this object.

This is the set of NUMA nodes for which there are NUMA node objects in the topology under or above this object, i.e. which are known to be physically contained in this object or containing it and known how (the children path between this object and the NUMA node objects).

In the end, these nodes are those that are close to the current object.

If the HWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM configuration flag is set, some of these nodes may not be allowed for allocation, see allowed_nodeset.

If there are no NUMA nodes in the machine, all the memory is close to this object, so nodeset is full.

Note

Its value must not be changed, hwloc_bitmap_dup() must be used instead.

online_cpuset

hwloc_cpuset_t hwloc_obj::online_cpuset

The CPU set of online logical processors.

This includes the CPUs contained in this object that are online, i.e. draw power and can execute threads. It may however not be allowed to bind to them due to administration rules, see allowed_cpuset.

Note

Its value must not be changed, hwloc_bitmap_dup() must be used instead.

os_index

unsigned hwloc_obj::os_index

OS-provided physical index number. It is not guaranteed unique across the entire machine, except for PUs and NUMA nodes.

os_level

signed hwloc_obj::os_level

OS-provided physical level, -1 if unknown or meaningless.

parent

struct hwloc_obj* hwloc_obj::parent

Parent, NULL if root (system object)

prev_cousin

struct hwloc_obj* hwloc_obj::prev_cousin

Previous object of same type and depth.

prev_sibling

struct hwloc_obj* hwloc_obj::prev_sibling

Previous object below the same parent.

sibling_rank

unsigned hwloc_obj::sibling_rank

Index in parent's children[] array.

symmetric_subtree

int hwloc_obj::symmetric_subtree

Set if the subtree of objects below this object is symmetric, which means all children and their children have identical subtrees. If set in the topology root object, lstopo may export the topology as a synthetic string.

type

hwloc_obj_type_t hwloc_obj::type

Type of object.

userdata

void* hwloc_obj::userdata

Application-given private data pointer, initialized to NULL, use it as you wish. See hwloc_topology_set_userdata_export_callback() if you wish to export this field to XML.

---

The documentation for this struct was generated from the following file:

• hwloc.h