# Terms and Definitions

Object

  Interesting kind of part of the system, such as a Core, a Cache, a Memory node, etc. The different types detected by hwloc are detailed in the hwloc_obj_type_t enumeration.

  They are topologically sorted by CPU set into a tree.

CPU set

  The set of logical processors (or processing units) logically included in an object (if it makes sense). They are always expressed using physical logical processor numbers (as announced by the OS). They are just masks, they do not have any relation with an operating system actual binding notion like Linux' cpusets.

Parent object

  The object logically containing the current object, for example because its CPU set includes the CPU set of the current object.

Ancestor object

  The parent object, or its own parent object, and so on.

Children object(s)

  The object (or objects) contained in the current object because their CPU set is included in the CPU set of the current object.

Arity

  The number of children of an object.

Sibling objects

  Objects of the same type which have the same parent.

Sibling rank

  Index to uniquely identify objects of the same type which have the same parent, and is always in the range [0, parent_arity).

Cousin objects

  Objects of the same type as the current object.

Level

  Set of objects of the same type.

OS index

  The index that the operating system (OS) uses to identify the object. This may be completely arbitrary, or it may depend on the BIOS configuration.

Depth

  Nesting level in the object tree, starting from the 0th object.

Logical index

  Index to uniquely identify objects of the same type. It expresses proximity in a generic way. This index is always linear and in the range [0, num_objs_same_type_same_level). Think of it as ``cousin rank.'' The ordering is based on topology first, and then on OS CPU numbers, so it is stable across everything except firmware CPU renumbering.

Logical processor
Processing unit

  The smallest processing element that can be represented by a hwloc object. It may be a single-core processor, a core of a multicore processor, or a single thread in SMT processor.

The following diagram can help to understand the vocabulary of the relationships by showing the example of a machine with two dual core sockets (with no hardware threads); thus, a topology with 4 levels. Each box with rounded corner corresponds to one hwloc_obj_t, containing the values of the different integer fields (depth, logical_index, etc.), and arrows show to which other hwloc_obj_t pointers point to (first_child, parent, etc.)

It should be noted that for PU objects, the logical index -- as computed linearly by hwloc -- is not the same as the OS index.