.TH "hwloc_obj" 3 "Thu Dec 13 2018" "Version 1.11.12" "Hardware Locality (hwloc)" \" -*- nroff -*-
.ad l
.nh
.SH NAME
hwloc_obj
.SH SYNOPSIS
.br
.PP
.PP
\fC#include <hwloc\&.h>\fP
.SS "Data Fields"

.in +1c
.ti -1c
.RI "\fBhwloc_obj_type_t\fP \fBtype\fP"
.br
.ti -1c
.RI "unsigned \fBos_index\fP"
.br
.ti -1c
.RI "char * \fBname\fP"
.br
.ti -1c
.RI "struct \fBhwloc_obj_memory_s\fP \fBmemory\fP"
.br
.ti -1c
.RI "union \fBhwloc_obj_attr_u\fP * \fBattr\fP"
.br
.ti -1c
.RI "unsigned \fBdepth\fP"
.br
.ti -1c
.RI "unsigned \fBlogical_index\fP"
.br
.ti -1c
.RI "signed \fBos_level\fP"
.br
.ti -1c
.RI "struct \fBhwloc_obj\fP * \fBnext_cousin\fP"
.br
.ti -1c
.RI "struct \fBhwloc_obj\fP * \fBprev_cousin\fP"
.br
.ti -1c
.RI "struct \fBhwloc_obj\fP * \fBparent\fP"
.br
.ti -1c
.RI "unsigned \fBsibling_rank\fP"
.br
.ti -1c
.RI "struct \fBhwloc_obj\fP * \fBnext_sibling\fP"
.br
.ti -1c
.RI "struct \fBhwloc_obj\fP * \fBprev_sibling\fP"
.br
.ti -1c
.RI "unsigned \fBarity\fP"
.br
.ti -1c
.RI "struct \fBhwloc_obj\fP ** \fBchildren\fP"
.br
.ti -1c
.RI "struct \fBhwloc_obj\fP * \fBfirst_child\fP"
.br
.ti -1c
.RI "struct \fBhwloc_obj\fP * \fBlast_child\fP"
.br
.ti -1c
.RI "void * \fBuserdata\fP"
.br
.ti -1c
.RI "\fBhwloc_cpuset_t\fP \fBcpuset\fP"
.br
.ti -1c
.RI "\fBhwloc_cpuset_t\fP \fBcomplete_cpuset\fP"
.br
.ti -1c
.RI "\fBhwloc_cpuset_t\fP \fBonline_cpuset\fP"
.br
.ti -1c
.RI "\fBhwloc_cpuset_t\fP \fBallowed_cpuset\fP"
.br
.ti -1c
.RI "\fBhwloc_nodeset_t\fP \fBnodeset\fP"
.br
.ti -1c
.RI "\fBhwloc_nodeset_t\fP \fBcomplete_nodeset\fP"
.br
.ti -1c
.RI "\fBhwloc_nodeset_t\fP \fBallowed_nodeset\fP"
.br
.ti -1c
.RI "struct \fBhwloc_distances_s\fP ** \fBdistances\fP"
.br
.ti -1c
.RI "unsigned \fBdistances_count\fP"
.br
.ti -1c
.RI "struct \fBhwloc_obj_info_s\fP * \fBinfos\fP"
.br
.ti -1c
.RI "unsigned \fBinfos_count\fP"
.br
.ti -1c
.RI "int \fBsymmetric_subtree\fP"
.br
.in -1c
.SH "Detailed Description"
.PP 
Structure of a topology object\&. 

Applications must not modify any field except \fBhwloc_obj\&.userdata\fP\&. 
.SH "Field Documentation"
.PP 
.SS "\fBhwloc_cpuset_t\fP hwloc_obj::allowed_cpuset"

.PP
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\&.
.PP
\fBNote:\fP
.RS 4
Its value must not be changed, \fBhwloc_bitmap_dup()\fP must be used instead\&. 
.RE
.PP

.SS "\fBhwloc_nodeset_t\fP hwloc_obj::allowed_nodeset"

.PP
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\&.
.PP
If there are no NUMA nodes in the machine, all the memory is close to this object, so \fCallowed_nodeset\fP is full\&.
.PP
\fBNote:\fP
.RS 4
Its value must not be changed, \fBhwloc_bitmap_dup()\fP must be used instead\&. 
.RE
.PP

.SS "unsigned hwloc_obj::arity"

.PP
Number of children\&. 
.SS "union \fBhwloc_obj_attr_u\fP* hwloc_obj::attr"

.PP
Object type-specific Attributes, may be \fCNULL\fP if no attribute value was found\&. 
.SS "struct \fBhwloc_obj\fP** hwloc_obj::children"

.PP
Children, \fCchildren\fP[0 \&.\&. arity -1]\&. 
.SS "\fBhwloc_cpuset_t\fP hwloc_obj::complete_cpuset"

.PP
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 \fBHWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM\fP 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\&.
.PP
\fBNote:\fP
.RS 4
Its value must not be changed, \fBhwloc_bitmap_dup()\fP must be used instead\&. 
.RE
.PP

.SS "\fBhwloc_nodeset_t\fP hwloc_obj::complete_nodeset"

.PP
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 \fBHWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM\fP 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\&.
.PP
If there are no NUMA nodes in the machine, all the memory is close to this object, so \fCcomplete_nodeset\fP is full\&.
.PP
\fBNote:\fP
.RS 4
Its value must not be changed, \fBhwloc_bitmap_dup()\fP must be used instead\&. 
.RE
.PP

.SS "\fBhwloc_cpuset_t\fP hwloc_obj::cpuset"

.PP
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)\&.
.PP
If the \fBHWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM\fP configuration flag is set, some of these CPUs may be offline, or not allowed for binding, see online_cpuset and allowed_cpuset\&.
.PP
\fBNote:\fP
.RS 4
Its value must not be changed, \fBhwloc_bitmap_dup()\fP must be used instead\&. 
.RE
.PP

.SS "unsigned hwloc_obj::depth"

.PP
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\&.
.PP
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 \fBhwloc_get_type_depth()\fP and \fBhwloc_get_type_depth_e\fP\&. Those special values can be passed to hwloc functions such \fBhwloc_get_nbobjs_by_depth()\fP as usual\&. 
.SS "struct \fBhwloc_distances_s\fP** hwloc_obj::distances"

.PP
Distances between all objects at same depth below this object\&. 
.SS "unsigned hwloc_obj::distances_count"

.SS "struct \fBhwloc_obj\fP* hwloc_obj::first_child"

.PP
First child\&. 
.SS "struct \fBhwloc_obj_info_s\fP* hwloc_obj::infos"

.PP
Array of stringified info type=name\&. 
.SS "unsigned hwloc_obj::infos_count"

.PP
Size of infos array\&. 
.SS "struct \fBhwloc_obj\fP* hwloc_obj::last_child"

.PP
Last child\&. 
.SS "unsigned hwloc_obj::logical_index"

.PP
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\&. 
.SS "struct \fBhwloc_obj_memory_s\fP hwloc_obj::memory"

.PP
Memory attributes\&. 
.SS "char* hwloc_obj::name"

.PP
Object-specific name if any\&. Mostly used for identifying OS devices and Misc objects where a name string is more useful than numerical indexes\&. 
.SS "struct \fBhwloc_obj\fP* hwloc_obj::next_cousin"

.PP
Next object of same type and depth\&. 
.SS "struct \fBhwloc_obj\fP* hwloc_obj::next_sibling"

.PP
Next object below the same parent\&. 
.SS "\fBhwloc_nodeset_t\fP hwloc_obj::nodeset"

.PP
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)\&.
.PP
In the end, these nodes are those that are close to the current object\&.
.PP
If the \fBHWLOC_TOPOLOGY_FLAG_WHOLE_SYSTEM\fP configuration flag is set, some of these nodes may not be allowed for allocation, see allowed_nodeset\&.
.PP
If there are no NUMA nodes in the machine, all the memory is close to this object, so \fCnodeset\fP is full\&.
.PP
\fBNote:\fP
.RS 4
Its value must not be changed, \fBhwloc_bitmap_dup()\fP must be used instead\&. 
.RE
.PP

.SS "\fBhwloc_cpuset_t\fP hwloc_obj::online_cpuset"

.PP
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\&.
.PP
\fBNote:\fP
.RS 4
Its value must not be changed, \fBhwloc_bitmap_dup()\fP must be used instead\&. 
.RE
.PP

.SS "unsigned hwloc_obj::os_index"

.PP
OS-provided physical index number\&. It is not guaranteed unique across the entire machine, except for PUs and NUMA nodes\&. 
.SS "signed hwloc_obj::os_level"

.PP
OS-provided physical level, -1 if unknown or meaningless\&. 
.SS "struct \fBhwloc_obj\fP* hwloc_obj::parent"

.PP
Parent, \fCNULL\fP if root (system object) 
.SS "struct \fBhwloc_obj\fP* hwloc_obj::prev_cousin"

.PP
Previous object of same type and depth\&. 
.SS "struct \fBhwloc_obj\fP* hwloc_obj::prev_sibling"

.PP
Previous object below the same parent\&. 
.SS "unsigned hwloc_obj::sibling_rank"

.PP
Index in parent's \fCchildren\fP[] array\&. 
.SS "int hwloc_obj::symmetric_subtree"

.PP
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\&. 
.SS "\fBhwloc_obj_type_t\fP hwloc_obj::type"

.PP
Type of object\&. 
.SS "void* hwloc_obj::userdata"

.PP
Application-given private data pointer, initialized to \fCNULL\fP, use it as you wish\&. See \fBhwloc_topology_set_userdata_export_callback()\fP if you wish to export this field to XML\&. 

.SH "Author"
.PP 
Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.