# memberdef

refid: a5209e6508c110dcd4c3c296466f07cb3
name: is_custom
definition: int hwloc_backend::is_custom
type: int
scope: hwloc_backend
briefdescription:
Backend-specific 'is_custom' property.
Shortcut on !strcmp(..->component->name, "custom").
Only the custom component should touch this.


refid: ab8806f6db077f1bb2e9d63ec99223f7a
name: is_thissystem
definition: int hwloc_backend::is_thissystem
type: int
scope: hwloc_backend
briefdescription:
Backend-specific 'is_thissystem' property.
Set to 0 or 1 if the backend should enforce the thissystem flag when it gets enabled.
Set to -1 if the backend doesn't care (default).


refid: a1adfa49eb1eb832b56d097df8d37a660
name: discover
definition: int(* hwloc_backend::discover)(struct hwloc_backend *backend)
type: int(*
argsstring: )(struct hwloc_backend *backend)
scope: hwloc_backend
briefdescription:
Main discovery callback.
returns > 0 if it modified the topology tree, -1 on error, 0 otherwise.
May be NULL if type is HWLOC_DISC_COMPONENT_TYPE_MISC.


refid: a5715ebb86f3290a1d8c86fbec8a7dae7
name: get_obj_cpuset
type: int(*
scope: hwloc_backend
definition:
int(* hwloc_backend::get_obj_cpuset)(struct hwloc_backend *backend, struct hwloc_backend *caller, struct hwloc_obj *obj, hwloc_bitmap_t cpuset)

argsstring:
)(struct hwloc_backend *backend, struct hwloc_backend *caller, struct hwloc_obj *obj, hwloc_bitmap_t cpuset)

briefdescription:
Callback used by the PCI backend to retrieve the locality of a PCI object from the OS/cpu backend.
May be NULL.


refid: afade8464c2b52d0cc63a705f556e81ed
name: notify_new_object
type: int(*
argsstring: )(struct hwloc_backend *backend, struct hwloc_backend *caller, struct hwloc_obj *obj)
scope: hwloc_backend
definition:
int(* hwloc_backend::notify_new_object)(struct hwloc_backend *backend, struct hwloc_backend *caller, struct hwloc_obj *obj)

briefdescription:
Callback called by backends to notify this backend that a new object was added.
returns > 0 if it modified the topology tree, 0 otherwise.
May be NULL.


refid: a610b612f198afa7324c3e720149e416b
name: init
definition: int(* hwloc_component::init)(unsigned long flags)
type: int(*
argsstring: )(unsigned long flags)
scope: hwloc_component
briefdescription: Process-wide component initialization callback.
detaileddescription:
This optional callback is called when the component is registered
to the hwloc core (after loading the plugin).

When the component is built as a plugin, this callback
should call hwloc_check_plugin_namespace()
and return an negative error code on error.

\p flags is always 0 for now.

\return 0 on success, or a negative code on error.

\node If the component uses ltdl for loading its own plugins,
it should load/unload them only in init() and finalize(),
to avoid race conditions with hwloc's use of ltdl.


refid: a8e6a3fbd401292460d8142210c7e5d32
name: finalize
definition: void(* hwloc_component::finalize)(unsigned long flags)
type: void(*
argsstring: )(unsigned long flags)
scope: hwloc_component
briefdescription: Process-wide component termination callback.
detaileddescription:
This optional callback is called after unregistering the component
from the hwloc core (before unloading the plugin).

\p flags is always 0 for now.

\note If the component uses ltdl for loading its own plugins,
it should load/unload them only in init() and finalize(),
to avoid race conditions with hwloc's use of ltdl.


refid: a34144f4d59bf46524e4875194652412b
name: excludes
definition: unsigned hwloc_disc_component::excludes
type: unsigned
scope: hwloc_disc_component
briefdescription: Component types to exclude, as an OR'ed set of HWLOC_DISC_COMPONENT_TYPE_*.
detaileddescription:
For a GLOBAL component, this usually includes all other types (~0).

Other components only exclude types that may bring conflicting
topology information. MISC components should likely not be excluded
since they usually bring non-primary additional information.


refid: ad724ca2e525851042a70cab48481d048
name: instantiate
type: struct hwloc_backend *(*
argsstring: )(struct hwloc_disc_component *component, const void *data1, const void *data2, const void *data3)
scope: hwloc_disc_component
definition:
struct hwloc_backend*(* hwloc_disc_component::instantiate)(struct hwloc_disc_component *component, const void *data1, const void *data2, const void *data3)

briefdescription:
Instantiate callback to create a backend from the component.
Parameters data1, data2, data3 are NULL except for components
that have special enabling routines such as hwloc_topology_set_xml().


refid: ae86d283c272c5ae24073a235efbf6b59
name: priority
definition: unsigned hwloc_disc_component::priority
type: unsigned
scope: hwloc_disc_component
detaileddescription:
Usual values are
50 for native OS (or platform) components,
45 for x86,
40 for no-OS fallback,
30 for global components (xml/synthetic/custom),
20 for pci,
10 for other misc components (opencl etc.).

briefdescription:
Component priority.
Used to sort topology->components, higher priority first.
Also used to decide between two components with the same name.


refid: a27a6b7eab8afec33712da20d5d1fc949
name: next
definition: struct hwloc_disc_component* hwloc_disc_component::next
type: struct hwloc_disc_component *
scope: hwloc_disc_component
detaileddescription:
Used internally to list components by priority on topology->components
(the component structure is usually read-only,
 the core copies it before using this field for queueing)


refid: a4ca2af858cebbce7324ec49903d09474
name: nbobjs
definition: unsigned hwloc_distances_s::nbobjs
type: unsigned
scope: hwloc_distances_s
briefdescription:
Number of objects considered in the matrix.
It is the number of descendant objects at \p relative_depth
below the containing object.
It corresponds to the result of hwloc_get_nbobjs_inside_cpuset_by_depth.


refid: a0f70f48d1bfb18e5e2008825da2967c9
name: latency
definition: float* hwloc_distances_s::latency
type: float *
scope: hwloc_distances_s
briefdescription:
Matrix of latencies between objects, stored as a one-dimension array.
May be \c NULL if the distances considered here are not latencies.
Values are normalized to get 1.0 as the minimal value in the matrix.
Latency from i-th to j-th object is stored in slot i*nbobjs+j.


refid: a204416418049a272bfb51602fc676342
name: latency_base
definition: float hwloc_distances_s::latency_base
type: float
scope: hwloc_distances_s
briefdescription:
The multiplier that should be applied to latency matrix
to retrieve the original OS-provided latencies.
Usually 10 on Linux since ACPI SLIT uses 10 for local latency.


refid: a9d82690370275d42d652eccdea5d3ee5
name: depth
definition: unsigned hwloc_obj::depth
type: unsigned
scope: hwloc_obj
briefdescription:
Vertical index in the hierarchy.
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.


refid: a0d07fb7b8935e137c94d75a3eb492ae9
name: logical_index
definition: unsigned hwloc_obj::logical_index
type: unsigned
scope: hwloc_obj
briefdescription:
Horizontal index in the whole list of similar objects,
could be a "cousin_rank" since it's the rank within the "cousin" list below.


refid: a76fd3ac94401cf32dfccc3a3a8de68a5
name: userdata
definition: void* hwloc_obj::userdata
type: void *
scope: hwloc_obj
briefdescription:
Application-given private data pointer,
initialized to \c NULL, use it as you wish.
See hwloc_topology_set_userdata_export_callback()
if you wish to export this field to XML.


refid: a67925e0f2c47f50408fbdb9bddd0790f
name: cpuset
definition: hwloc_cpuset_t hwloc_obj::cpuset
type: hwloc_cpuset_t
scope: hwloc_obj
briefdescription: CPUs covered by this object.
detaileddescription:
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.


refid: a91788a9da687beb7224cc1fd7b75208c
name: complete_cpuset
definition: hwloc_cpuset_t hwloc_obj::complete_cpuset
type: hwloc_cpuset_t
scope: hwloc_obj
briefdescription: The complete CPU set of logical processors of this object,.
detaileddescription:
This includes not only the same as the cpuset field, but also the 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.


refid: a8842d56c2975380f327ea401c5f53564
name: online_cpuset
definition: hwloc_cpuset_t hwloc_obj::online_cpuset
type: hwloc_cpuset_t
scope: hwloc_obj
briefdescription: The CPU set of online logical processors.
detaileddescription:
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.


refid: afa3c59a6dd3da8ffa48710780a1bfb34
name: allowed_cpuset
definition: hwloc_cpuset_t hwloc_obj::allowed_cpuset
type: hwloc_cpuset_t
scope: hwloc_obj
briefdescription: The CPU set of allowed logical processors.
detaileddescription:
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.


refid: a08f0d0e16c619a6e653526cbee4ffea3
name: nodeset
definition: hwloc_nodeset_t hwloc_obj::nodeset
type: hwloc_nodeset_t
scope: hwloc_obj
briefdescription: NUMA nodes covered by this object or containing this object.
detaileddescription:
This is the set of NUMA nodes for which there are 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 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 \p nodeset is full.

\note Its value must not be changed, hwloc_bitmap_dup must be used instead.


refid: ac38c4012127525ef74c5615c526f4c2e
name: complete_nodeset
definition: hwloc_nodeset_t hwloc_obj::complete_nodeset
type: hwloc_nodeset_t
scope: hwloc_obj
briefdescription: The complete NUMA node set of this object,.
detaileddescription:
This includes not only the same as the nodeset field, but also the 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 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 \p complete_nodeset is full.

\note Its value must not be changed, hwloc_bitmap_dup must be used instead.


refid: a19e3d0a5951a7510fc4fc4722a9bf531
name: allowed_nodeset
definition: hwloc_nodeset_t hwloc_obj::allowed_nodeset
type: hwloc_nodeset_t
scope: hwloc_obj
briefdescription: The set of allowed NUMA memory nodes.
detaileddescription:
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 \p allowed_nodeset is full.

\note Its value must not be changed, hwloc_bitmap_dup must be used instead.


refid: a0f41a1d67dc6b661906f2217563637f3
name: symmetric_subtree
definition: int hwloc_obj::symmetric_subtree
type: int
scope: hwloc_obj
briefdescription:
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.


refid: a43f8133b7c30129b002c2d295e6580fc
name: type
type: hwloc_topology_diff_obj_attr_type_t
scope: hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s
definition:
hwloc_topology_diff_obj_attr_type_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s::type


refid: a784ab5827c1bf531b86d1f02f199d04d
name: type
type: hwloc_topology_diff_obj_attr_type_t
scope: hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s
definition:
hwloc_topology_diff_obj_attr_type_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s::type


refid: a68039c178e9961023345e0728382773b
name: generic
type: struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s
scope: hwloc_topology_diff_obj_attr_u
definition:
struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_generic_s  hwloc_topology_diff_obj_attr_u::generic


refid: abb15bfa7039ca8c97cd7ddfbdf779efa
name: uint64
type: struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s
scope: hwloc_topology_diff_obj_attr_u
definition:
struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s  hwloc_topology_diff_obj_attr_u::uint64


refid: a518a48e13168c31957589ce78820163e
name: string
type: struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s
scope: hwloc_topology_diff_obj_attr_u
definition:
struct hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_string_s  hwloc_topology_diff_obj_attr_u::string


refid: afe262b9aa558fe7bfecbd37a7a129197
name: type
type: hwloc_topology_diff_obj_attr_type_t
scope: hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s
definition:
hwloc_topology_diff_obj_attr_type_t hwloc_topology_diff_obj_attr_u::hwloc_topology_diff_obj_attr_uint64_s::type


refid: ga3f6861045a8029ade373510ffa727d2a
name: hwloc_bitmap_foreach_begin
briefdescription: Loop macro iterating on bitmap \p bitmap.
detaileddescription:
\p index is the loop variable; it should be an unsigned int.  The
first iteration will set \p index to the lowest index in the bitmap.
Successive iterations will iterate through, in order, all remaining
indexes that in the bitmap.  To be specific: each iteration will return a
value for \p index such that hwloc_bitmap_isset(bitmap, index) is true.

The assert prevents the loop from being infinite if the bitmap is infinite.


refid: gadece3d1eb5199fc2fb99bc7dcf1ccc05
name: hwloc_bitmap_alloc
definition: hwloc_bitmap_t hwloc_bitmap_alloc
type: hwloc_bitmap_t
argsstring: (void)
briefdescription: Allocate a new empty bitmap.
detaileddescription:
\returns A valid bitmap or \c NULL.

The bitmap should be freed by a corresponding call to
hwloc_bitmap_free().


refid: ga9511644657030a021dce9941e3cda583
name: hwloc_bitmap_snprintf
definition: int hwloc_bitmap_snprintf
type: int
argsstring: (char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
briefdescription: Stringify a bitmap.
detaileddescription:
Up to \p buflen characters may be written in buffer \p buf.

If \p buflen is 0, \p buf may safely be \c NULL.

\return the number of character that were actually written if not truncating,
or that would have been written (not including the ending \\0).


refid: ga3d06e6447edeb61e56a9ad83f31f0a37
name: hwloc_bitmap_list_snprintf
definition: int hwloc_bitmap_list_snprintf
type: int
argsstring: (char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
briefdescription: Stringify a bitmap in the list format.
detaileddescription:
Lists are comma-separated indexes or ranges.
Ranges are dash separated indexes.
The last range may not have a ending indexes if the bitmap is infinite.

Up to \p buflen characters may be written in buffer \p buf.

If \p buflen is 0, \p buf may safely be \c NULL.

\return the number of character that were actually written if not truncating,
or that would have been written (not including the ending \\0).


refid: ga5beb68a987fe48e5c5edef06ab260e14
name: hwloc_bitmap_taskset_snprintf
definition: int hwloc_bitmap_taskset_snprintf
type: int
argsstring: (char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
briefdescription: Stringify a bitmap in the taskset-specific format.
detaileddescription:
The taskset command manipulates bitmap strings that contain a single
(possible very long) hexadecimal number starting with 0x.

Up to \p buflen characters may be written in buffer \p buf.

If \p buflen is 0, \p buf may safely be \c NULL.

\return the number of character that were actually written if not truncating,
or that would have been written (not including the ending \\0).


refid: ga07b2de8786b3cdb22f21d9dd42588275
name: hwloc_bitmap_fill
definition: void hwloc_bitmap_fill
type: void
argsstring: (hwloc_bitmap_t bitmap)
briefdescription:
Fill bitmap \p bitmap with all possible indexes (even if those objects don't exist or are otherwise unavailable)


refid: ga36d802130aa5d96bc1b5a90d2f0f3765
name: hwloc_bitmap_singlify
definition: void hwloc_bitmap_singlify
type: void
argsstring: (hwloc_bitmap_t bitmap)
briefdescription: Keep a single index among those set in bitmap \p bitmap.
detaileddescription:
May be useful before binding so that the process does not
have a chance of migrating between multiple logical CPUs
in the original mask.


refid: gaec41c6b4dc3361156beb7dea2a74f5a3
name: hwloc_cuda_get_device_cpuset
definition: static int hwloc_cuda_get_device_cpuset
type: int
argsstring: (hwloc_topology_t topology, CUdevice cudevice, hwloc_cpuset_t set)
briefdescription: Get the CPU set of logical processors that are physically close to device \p cudevice.
detaileddescription:
Return the CPU set describing the locality of the CUDA device \p cudevice.

Topology \p topology and device \p cudevice must match the local machine.
I/O devices detection and the CUDA component are not needed in the topology.

The function only returns the locality of the device.
If more information about the device is needed, OS objects should
be used instead, see hwloc_cuda_get_device_osdev()
and hwloc_cuda_get_device_osdev_by_index().

This function is currently only implemented in a meaningful way for
Linux; other systems will simply get a full cpuset.


refid: ga11fed607fa404e29e8da010f3ec128e4
name: hwloc_cuda_get_device_pcidev
definition: static hwloc_obj_t hwloc_cuda_get_device_pcidev
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, CUdevice cudevice)
briefdescription: Get the hwloc PCI device object corresponding to the CUDA device \p cudevice.
detaileddescription:
Return the PCI device object describing the CUDA device \p cudevice.
Return NULL if there is none.

Topology \p topology and device \p cudevice must match the local machine.
I/O devices detection must be enabled in topology \p topology.
The CUDA component is not needed in the topology.


refid: ga252cb72175f1a2d682f883a0add80a66
name: hwloc_cuda_get_device_osdev
definition: static hwloc_obj_t hwloc_cuda_get_device_osdev
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, CUdevice cudevice)
briefdescription: Get the hwloc OS device object corresponding to CUDA device \p cudevice.
detaileddescription:
Return the hwloc OS device object that describes the given
CUDA device \p cudevice. Return NULL if there is none.

Topology \p topology and device \p cudevice must match the local machine.
I/O devices detection and the NVML component must be enabled in the topology.
If not, the locality of the object may still be found using
hwloc_cuda_get_device_cpuset().

\note The corresponding hwloc PCI device may be found by looking
at the result parent pointer.


refid: ga12ee892994ed037e8f64bbffda02cf2e
name: hwloc_cuda_get_device_osdev_by_index
definition: static hwloc_obj_t hwloc_cuda_get_device_osdev_by_index
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, unsigned idx)
briefdescription: Get the hwloc OS device object corresponding to the CUDA device whose index is \p idx.
detaileddescription:
Return the OS device object describing the CUDA device whose
index is \p idx. Return NULL if there is none.

The topology \p topology does not necessarily have to match the current
machine. For instance the topology may be an XML import of a remote host.
I/O devices detection and the CUDA component must be enabled in the topology.

\note The corresponding PCI device object can be obtained by looking
at the OS device parent object.

\note This function is identical to hwloc_cudart_get_device_osdev_by_index().


refid: ga187ca00c6e12800a25151ce331620980
name: hwloc_cudart_get_device_cpuset
definition: static int hwloc_cudart_get_device_cpuset
type: int
argsstring: (hwloc_topology_t topology, int idx, hwloc_cpuset_t set)
briefdescription: Get the CPU set of logical processors that are physically close to device \p idx.
detaileddescription:
Return the CPU set describing the locality of the CUDA device
whose index is \p idx.

Topology \p topology and device \p idx must match the local machine.
I/O devices detection and the CUDA component are not needed in the topology.

The function only returns the locality of the device.
If more information about the device is needed, OS objects should
be used instead, see hwloc_cudart_get_device_osdev_by_index().

This function is currently only implemented in a meaningful way for
Linux; other systems will simply get a full cpuset.


refid: gaeda4e6efbb36b518b2c286434ad23bb2
name: hwloc_cudart_get_device_pcidev
definition: static hwloc_obj_t hwloc_cudart_get_device_pcidev
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, int idx)
briefdescription: Get the hwloc PCI device object corresponding to the CUDA device whose index is \p idx.
detaileddescription:
Return the PCI device object describing the CUDA device whose
index is \p idx. Return NULL if there is none.

Topology \p topology and device \p idx must match the local machine.
I/O devices detection must be enabled in topology \p topology.
The CUDA component is not needed in the topology.


refid: gac0f3eeaf7712919f298097b1a21307b0
name: hwloc_cudart_get_device_osdev_by_index
definition: static hwloc_obj_t hwloc_cudart_get_device_osdev_by_index
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, unsigned idx)
briefdescription: Get the hwloc OS device object corresponding to the CUDA device whose index is \p idx.
detaileddescription:
Return the OS device object describing the CUDA device whose
index is \p idx. Return NULL if there is none.

The topology \p topology does not necessarily have to match the current
machine. For instance the topology may be an XML import of a remote host.
I/O devices detection and the CUDA component must be enabled in the topology.
If not, the locality of the object may still be found using
hwloc_cudart_get_device_cpuset().

\note The corresponding PCI device object can be obtained by looking
at the OS device parent object.

\note This function is identical to hwloc_cuda_get_device_osdev_by_index().


refid: ga8a1754f69fbb31364ea3ea2c39827c9f
name: hwloc_topology_diff_build
definition: int hwloc_topology_diff_build
type: int
briefdescription: Compute the difference between 2 topologies.
argsstring:
(hwloc_topology_t topology, hwloc_topology_t newtopology, unsigned long flags, hwloc_topology_diff_t *diff)

detaileddescription:
The difference is stored as a list of hwloc_topology_diff_t entries
starting at \p diff.
It is computed by doing a depth-first traversal of both topology trees
simultaneously.

If the difference between 2 objects is too complex to be represented
(for instance if some objects have different types, or different numbers
of children), a special diff entry of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX
is queued.
The computation of the diff does not continue below these objects.
So each such diff entry means that the difference between two subtrees
could not be computed.

\return 0 if the difference can be represented properly.

\return 0 with \p diff pointing to NULL if there is no difference
between the topologies.

\return 1 if the difference is too complex (see above). Some entries in
the list will be of type HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX.

\return -1 on any other error.

\note \p flags is currently not used. It should be 0.

\note The output diff has to be freed with hwloc_topology_diff_destroy().

\note The output diff can only be exported to XML or passed to
hwloc_topology_diff_apply() if 0 was returned, i.e. if no entry of type
HWLOC_TOPOLOGY_DIFF_TOO_COMPLEX is listed.

\note The output diff may be modified by removing some entries from
the list. The removed entries should be freed by passing them to
to hwloc_topology_diff_destroy() (possible as another list).


refid: gae7b350d7e7478a4c6047b08aa6544f40
name: hwloc_topology_diff_apply
definition: int hwloc_topology_diff_apply
type: int
argsstring: (hwloc_topology_t topology, hwloc_topology_diff_t diff, unsigned long flags)
briefdescription: Apply a topology diff to an existing topology.
detaileddescription:
\p flags is an OR'ed set of hwloc_topology_diff_apply_flags_e.

The new topology is modified in place. hwloc_topology_dup()
may be used to duplicate it before patching.

If the difference cannot be applied entirely, all previous applied
elements are unapplied before returning.

\return 0 on success.

\return -N if applying the difference failed while trying
to apply the N-th part of the difference. For instance -1
is returned if the very first difference element could not
be applied.


refid: gab531db0e4ca3e590d48358c90f59c197
name: hwloc_topology_diff_destroy
definition: int hwloc_topology_diff_destroy
type: int
argsstring: (hwloc_topology_t topology, hwloc_topology_diff_t diff)
briefdescription: Destroy a list of topology differences.
detaileddescription:
\note The \p topology parameter must be a valid topology
but it is not required that it is related to \p diff.


refid: gae82a885a377aff78936c5f175b5980f8
name: hwloc_topology_diff_load_xml
definition: int hwloc_topology_diff_load_xml
type: int
argsstring: (hwloc_topology_t topology, const char *xmlpath, hwloc_topology_diff_t *diff, char **refname)
briefdescription: Load a list of topology differences from a XML file.
detaileddescription:
If not \c NULL, \p refname will be filled with the identifier
string of the reference topology for the difference file,
if any was specified in the XML file.
This identifier is usually the name of the other XML file
that contains the reference topology.

\note The \p topology parameter must be a valid topology
but it is not required that it is related to \p diff.

\note the pointer returned in refname should later be freed
by the caller.


refid: gacceb7e97b5689d0405db618bb5541012
name: hwloc_topology_diff_export_xml
definition: int hwloc_topology_diff_export_xml
type: int
argsstring: (hwloc_topology_t topology, hwloc_topology_diff_t diff, const char *refname, const char *xmlpath)
briefdescription: Export a list of topology differences to a XML file.
detaileddescription:
If not \c NULL, \p refname defines an identifier string
for the reference topology which was used as a base when
computing this difference.
This identifier is usually the name of the other XML file
that contains the reference topology.
This attribute is given back when reading the diff from XML.

\note The \p topology parameter must be a valid topology
but it is not required that it is related to \p diff.


refid: ga09afc24f1c9860465ec352c4ac518dd4
name: hwloc_topology_diff_load_xmlbuffer
definition: int hwloc_topology_diff_load_xmlbuffer
type: int
briefdescription: Load a list of topology differences from a XML buffer.
argsstring:
(hwloc_topology_t topology, const char *xmlbuffer, int buflen, hwloc_topology_diff_t *diff, char **refname)

detaileddescription:
If not \c NULL, \p refname will be filled with the identifier
string of the reference topology for the difference file,
if any was specified in the XML file.
This identifier is usually the name of the other XML file
that contains the reference topology.

\note The \p topology parameter must be a valid topology
but it is not required that it is related to \p diff.

\note the pointer returned in refname should later be freed
by the caller.


refid: ga88e72855746c81e2341580fa8d619a51
name: hwloc_topology_diff_export_xmlbuffer
definition: int hwloc_topology_diff_export_xmlbuffer
type: int
briefdescription: Export a list of topology differences to a XML buffer.
argsstring:
(hwloc_topology_t topology, hwloc_topology_diff_t diff, const char *refname, char **xmlbuffer, int *buflen)

detaileddescription:
If not \c NULL, \p refname defines an identifier string
for the reference topology which was used as a base when
computing this difference.
This identifier is usually the name of the other XML file
that contains the reference topology.
This attribute is given back when reading the diff from XML.

\note The XML buffer should later be freed with hwloc_free_xmlbuffer().

\note The \p topology parameter must be a valid topology
but it is not required that it is related to \p diff.


refid: ga4d66a77e4fe4051d6e5b772c1b8fcec5
name: hwloc_gl_get_display_osdev_by_port_device
definition: static hwloc_obj_t hwloc_gl_get_display_osdev_by_port_device
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, unsigned port, unsigned device)
briefdescription: Get the hwloc OS device object corresponding to the OpenGL display given by port and device index.
detaileddescription:
Return the OS device object describing the OpenGL display
whose port (server) is \p port and device (screen) is \p device.
Return NULL if there is none.

The topology \p topology does not necessarily have to match the current
machine. For instance the topology may be an XML import of a remote host.
I/O devices detection and the GL component must be enabled in the topology.

\note The corresponding PCI device object can be obtained by looking
at the OS device parent object.


refid: ga2d36ef441d1dfddf49cfb5c01bd58d8e
name: hwloc_gl_get_display_osdev_by_name
definition: static hwloc_obj_t hwloc_gl_get_display_osdev_by_name
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, const char *name)
briefdescription: Get the hwloc OS device object corresponding to the OpenGL display given by name.
detaileddescription:
Return the OS device object describing the OpenGL display
whose name is \p name, built as ":port.device" such as ":0.0" .
Return NULL if there is none.

The topology \p topology does not necessarily have to match the current
machine. For instance the topology may be an XML import of a remote host.
I/O devices detection and the GL component must be enabled in the topology.

\note The corresponding PCI device object can be obtained by looking
at the OS device parent object.


refid: ga936665ab5f0d29a081c4b78d11f4ad07
name: hwloc_gl_get_display_by_osdev
definition: static int hwloc_gl_get_display_by_osdev
type: int
argsstring: (hwloc_topology_t topology, hwloc_obj_t osdev, unsigned *port, unsigned *device)
briefdescription: Get the OpenGL display port and device corresponding to the given hwloc OS object.
detaileddescription:
Return the OpenGL display port (server) in \p port and device (screen)
in \p screen that correspond to the given hwloc OS device object.
Return \c -1 if there is none.

The topology \p topology does not necessarily have to match the current
machine. For instance the topology may be an XML import of a remote host.
I/O devices detection and the GL component must be enabled in the topology.


refid: ga88699a0c86c66a9b7baa3468cd9d24c3
name: hwloc_cpuset_to_glibc_sched_affinity
definition: static int hwloc_cpuset_to_glibc_sched_affinity
type: int
briefdescription: Convert hwloc CPU set \p toposet into glibc sched affinity CPU set \p schedset.
argsstring:
(hwloc_topology_t topology, hwloc_const_cpuset_t hwlocset, cpu_set_t *schedset, size_t schedsetsize)

detaileddescription:
This function may be used before calling sched_setaffinity or any other function
that takes a cpu_set_t as input parameter.

\p schedsetsize should be sizeof(cpu_set_t) unless \p schedset was dynamically allocated with CPU_ALLOC


refid: ga8ec807ec17de57fa77aa5cfd6c8e4bfb
name: hwloc_cpuset_from_glibc_sched_affinity
definition: static int hwloc_cpuset_from_glibc_sched_affinity
type: int
briefdescription: Convert glibc sched affinity CPU set \p schedset into hwloc CPU set.
argsstring:
(hwloc_topology_t topology, hwloc_cpuset_t hwlocset, const cpu_set_t *schedset, size_t schedsetsize)

detaileddescription:
This function may be used before calling sched_setaffinity  or any other function
that takes a cpu_set_t  as input parameter.

\p schedsetsize should be sizeof(cpu_set_t) unless \p schedset was dynamically allocated with CPU_ALLOC


refid: ga547325a4193dbc215d07c23097519d79
name: hwloc_get_first_largest_obj_inside_cpuset
definition: static hwloc_obj_t hwloc_get_first_largest_obj_inside_cpuset
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, hwloc_const_cpuset_t set)
briefdescription: Get the first largest object included in the given cpuset \p set.
detaileddescription:
\return the first object that is included in \p set and whose parent is not.

This is convenient for iterating over all largest objects within a CPU set
by doing a loop getting the first largest object and clearing its CPU set
from the remaining CPU set.

\note This function cannot work if the root object does not have a CPU set,
e.g. if the topology is made of different machines.


refid: ga34ca563fa3a6a4e05268f36a87668511
name: hwloc_get_largest_objs_inside_cpuset
definition: int hwloc_get_largest_objs_inside_cpuset
type: int
argsstring: (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t *restrict objs, int max)
briefdescription: Get the set of largest objects covering exactly a given cpuset \p set.
detaileddescription:
\return the number of objects returned in \p objs.

\note This function cannot work if the root object does not have a CPU set,
e.g. if the topology is made of different machines.


refid: ga468b8bef96f9677d6fe04a0d81044c85
name: hwloc_get_next_obj_inside_cpuset_by_depth
definition: static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_depth
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, hwloc_const_cpuset_t set, unsigned depth, hwloc_obj_t prev)
briefdescription: Return the next object at depth \p depth included in CPU set \p set.
detaileddescription:
If \p prev is \c NULL, return the first object at depth \p depth
included in \p set.  The next invokation should pass the previous
return value in \p prev so as to obtain the next object in \p set.

\note This function cannot work if objects at the given depth do
not have CPU sets or if the topology is made of different machines.


refid: gafe859176cf9233f215fea0e87cef47e7
name: hwloc_get_next_obj_inside_cpuset_by_type
definition: static hwloc_obj_t hwloc_get_next_obj_inside_cpuset_by_type
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, hwloc_obj_t prev)
briefdescription: Return the next object of type \p type included in CPU set \p set.
detaileddescription:
If there are multiple or no depth for given type, return \c NULL
and let the caller fallback to
hwloc_get_next_obj_inside_cpuset_by_depth().

\note This function cannot work if objects of the given type do
not have CPU sets or if the topology is made of different machines.


refid: ga9442c310da87de6d09d3a4b8399ec14f
name: hwloc_get_obj_inside_cpuset_by_depth
definition: static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_depth
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, hwloc_const_cpuset_t set, unsigned depth, unsigned idx)
briefdescription: Return the (logically) \p idx -th object at depth \p depth included in CPU set \p set.
detaileddescription:
\note This function cannot work if objects at the given depth do
not have CPU sets or if the topology is made of different machines.


refid: ga2edf924e5a0cca9cb22f65cc77c6ddb5
name: hwloc_get_obj_inside_cpuset_by_type
definition: static hwloc_obj_t hwloc_get_obj_inside_cpuset_by_type
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, unsigned idx)
briefdescription: Return the \p idx -th object of type \p type included in CPU set \p set.
detaileddescription:
If there are multiple or no depth for given type, return \c NULL
and let the caller fallback to
hwloc_get_obj_inside_cpuset_by_depth().

\note This function cannot work if objects of the given type do
not have CPU sets or if the topology is made of different machines.


refid: ga133c40415de008518608f8bff52a5ab9
name: hwloc_get_nbobjs_inside_cpuset_by_type
definition: static int hwloc_get_nbobjs_inside_cpuset_by_type
type: int
argsstring: (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type)
briefdescription: Return the number of objects of type \p type included in CPU set \p set.
detaileddescription:
If no object for that type exists inside CPU set \p set, 0 is
returned.  If there are several levels with objects of that type
inside CPU set \p set, -1 is returned.

\note This function cannot work if objects of the given type do
not have CPU sets or if the topology is made of different machines.


refid: ga4c3a20d61e9beb06c667b21688c772c5
name: hwloc_get_obj_index_inside_cpuset
definition: static int hwloc_get_obj_index_inside_cpuset
type: int
argsstring: (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t obj)
briefdescription: Return the logical index among the objects included in CPU set \p set.
detaileddescription:
Consult all objects in the same level as \p obj and inside CPU set \p set
in the logical order, and return the index of \p obj within them.
If \p set covers the entire topology, this is the logical index of \p obj.
Otherwise, this is similar to a logical index within the part of the topology
defined by CPU set \p set.


refid: ga0e66aa2dc6b2527cfd10723af646c9d7
name: hwloc_get_child_covering_cpuset
definition: static hwloc_obj_t hwloc_get_child_covering_cpuset
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_t parent)
briefdescription: Get the child covering at least CPU set \p set.
detaileddescription:
\return \c NULL if no child matches or if \p set is empty.

\note This function cannot work if parent does not have a CPU set.


refid: ga41acdcdbb8b95d70ecf6c572a3f67dca
name: hwloc_get_obj_covering_cpuset
definition: static hwloc_obj_t hwloc_get_obj_covering_cpuset
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, hwloc_const_cpuset_t set)
briefdescription: Get the lowest object covering at least CPU set \p set.
detaileddescription:
\return \c NULL if no object matches or if \p set is empty.

\note This function cannot work if the root object does not have a CPU set,
e.g. if the topology is made of different machines.


refid: gaeea0d93522c85c3ef0acfbb00733a69c
name: hwloc_get_next_obj_covering_cpuset_by_depth
definition: static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_depth
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, hwloc_const_cpuset_t set, unsigned depth, hwloc_obj_t prev)
briefdescription: Iterate through same-depth objects covering at least CPU set \p set.
detaileddescription:
If object \p prev is \c NULL, return the first object at depth \p
depth covering at least part of CPU set \p set.  The next
invokation should pass the previous return value in \p prev so as
to obtain the next object covering at least another part of \p set.

\note This function cannot work if objects at the given depth do
not have CPU sets or if the topology is made of different machines.


refid: ga91cfae08b092e7966002e15d1e987213
name: hwloc_get_next_obj_covering_cpuset_by_type
definition: static hwloc_obj_t hwloc_get_next_obj_covering_cpuset_by_type
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, hwloc_const_cpuset_t set, hwloc_obj_type_t type, hwloc_obj_t prev)
briefdescription: Iterate through same-type objects covering at least CPU set \p set.
detaileddescription:
If object \p prev is \c NULL, return the first object of type \p
type covering at least part of CPU set \p set.  The next invokation
should pass the previous return value in \p prev so as to obtain
the next object of type \p type covering at least another part of
\p set.

If there are no or multiple depths for type \p type, \c NULL is returned.
The caller may fallback to hwloc_get_next_obj_covering_cpuset_by_depth()
for each depth.

\note This function cannot work if objects of the given type do
not have CPU sets or if the topology is made of different machines.


refid: gad108a09ce400222fe45545257d575489
name: hwloc_get_cache_type_depth
definition: static int hwloc_get_cache_type_depth
type: int
argsstring: (hwloc_topology_t topology, unsigned cachelevel, hwloc_obj_cache_type_t cachetype)
briefdescription: Find the depth of cache objects matching cache depth and type.
detaileddescription:
Return the depth of the topology level that contains cache objects
whose attributes match \p cachedepth and \p cachetype. This function
intends to disambiguate the case where hwloc_get_type_depth() returns
\p HWLOC_TYPE_DEPTH_MULTIPLE.

If no cache level matches, \p HWLOC_TYPE_DEPTH_UNKNOWN is returned.

If \p cachetype is \p HWLOC_OBJ_CACHE_UNIFIED, the depth of the
unique matching unified cache level is returned.

If \p cachetype is \p HWLOC_OBJ_CACHE_DATA or \p HWLOC_OBJ_CACHE_INSTRUCTION,
either a matching cache, or a unified cache is returned.

If \p cachetype is \c -1, it is ignored and multiple levels may
match. The function returns either the depth of a uniquely matching
level or \p HWLOC_TYPE_DEPTH_MULTIPLE.


refid: gac4cd480a5deaa4ada047fdd11ae4c070
name: hwloc_get_cache_covering_cpuset
definition: static hwloc_obj_t hwloc_get_cache_covering_cpuset
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, hwloc_const_cpuset_t set)
briefdescription: Get the first cache covering a cpuset \p set.
detaileddescription:
\return \c NULL if no cache matches.

\note This function cannot work if the root object does not have a CPU set,
e.g. if the topology is made of different machines.


refid: ga751c238a4931db5cc0ca3181b7dd7479
name: hwloc_get_pu_obj_by_os_index
definition: static hwloc_obj_t hwloc_get_pu_obj_by_os_index
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, unsigned os_index)
briefdescription: Returns the object of type ::HWLOC_OBJ_PU with \p os_index.
detaileddescription:
This function is useful for converting a CPU set into the PU
objects it contains.
When retrieving the current binding (e.g. with hwloc_get_cpubind()),
one may iterate over the bits of the resulting CPU set with
hwloc_bitmap_foreach_begin(), and find the corresponding PUs
with this function.


refid: gab89d9ed9edfaa3dd526fb6ee1a1618ea
name: hwloc_get_numanode_obj_by_os_index
definition: static hwloc_obj_t hwloc_get_numanode_obj_by_os_index
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, unsigned os_index)
briefdescription: Returns the object of type ::HWLOC_OBJ_NODE with \p os_index.
detaileddescription:
This function is useful for converting a nodeset into the NUMA node
objects it contains.
When retrieving the current binding (e.g. with hwloc_get_membind_nodeset()),
one may iterate over the bits of the resulting nodeset with
hwloc_bitmap_foreach_begin(), and find the corresponding NUMA nodes
with this function.


refid: ga2cd22a34360643f7f5bad09576dec205
name: hwloc_get_closest_objs
definition: unsigned hwloc_get_closest_objs
type: unsigned
argsstring: (hwloc_topology_t topology, hwloc_obj_t src, hwloc_obj_t *restrict objs, unsigned max)
briefdescription: Do a depth-first traversal of the topology to find and sort.
detaileddescription:
all objects that are at the same depth than \p src.
Report in \p objs up to \p max physically closest ones to \p src.

\return the number of objects returned in \p objs.

\return 0 if \p src is an I/O object.

\note This function requires the \p src object to have a CPU set.


refid: ga7a0c1046851f7a88bd52f5a1d4ba0a97
name: hwloc_get_obj_below_by_type
definition: static hwloc_obj_t hwloc_get_obj_below_by_type
type: hwloc_obj_t
briefdescription: Find an object below another object, both specified by types and indexes.
argsstring:
(hwloc_topology_t topology, hwloc_obj_type_t type1, unsigned idx1, hwloc_obj_type_t type2, unsigned idx2)

detaileddescription:
Start from the top system object and find object of type \p type1
and logical index \p idx1.  Then look below this object and find another
object of type \p type2 and logical index \p idx2.  Indexes are specified
within the parent, not withing the entire system.

For instance, if type1 is SOCKET, idx1 is 2, type2 is CORE and idx2
is 3, return the fourth core object below the third socket.

\note This function requires these objects to have a CPU set.


refid: gacb51295ff3fbd3a96f990f20c6492b1d
name: hwloc_get_obj_below_array_by_type
definition: static hwloc_obj_t hwloc_get_obj_below_array_by_type
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, int nr, hwloc_obj_type_t *typev, unsigned *idxv)
briefdescription: Find an object below a chain of objects specified by types and indexes.
detaileddescription:
This is a generalized version of hwloc_get_obj_below_by_type().

Arrays \p typev and \p idxv must contain \p nr types and indexes.

Start from the top system object and walk the arrays \p typev and \p idxv.
For each type and logical index couple in the arrays, look under the previously found
object to find the index-th object of the given type.
Indexes are specified within the parent, not withing the entire system.

For instance, if nr is 3, typev contains NODE, SOCKET and CORE,
and idxv contains 0, 1 and 2, return the third core object below
the second socket below the first NUMA node.

\note This function requires all these objects and the root object
to have a CPU set.


refid: ga2e3db06f766509ae2004ee4c8bbf5204
name: hwloc_distrib
definition: static int hwloc_distrib
type: int
briefdescription: Distribute \p n items over the topology under \p roots.
argsstring:
(hwloc_topology_t topology, hwloc_obj_t *roots, unsigned n_roots, hwloc_cpuset_t *set, unsigned n, unsigned until, unsigned long flags)

detaileddescription:
Array \p set will be filled with \p n cpusets recursively distributed
linearly over the topology under objects \p roots, down to depth \p until
(which can be INT_MAX to distribute down to the finest level).

\p n_roots is usually 1 and \p roots only contains the topology root object
so as to distribute over the entire topology.

This is typically useful when an application wants to distribute \p n
threads over a machine, giving each of them as much private cache as
possible and keeping them locally in number order.

The caller may typically want to also call hwloc_bitmap_singlify()
before binding a thread so that it does not move at all.

\p flags should be 0 or a OR'ed set of ::hwloc_distrib_flags_e.

\note This function requires the \p roots objects to have a CPU set.

\note This function replaces the now deprecated hwloc_distribute()
and hwloc_distributev() functions.


refid: ga69fbad44c685e46d80ecf51a714ba9ce
name: hwloc_topology_get_complete_cpuset
definition: static hwloc_const_cpuset_t hwloc_topology_get_complete_cpuset
type: hwloc_const_cpuset_t
argsstring: (hwloc_topology_t topology)
briefdescription: Get complete CPU set.
detaileddescription:
\return the complete CPU set of logical processors of the system. If the
topology is the result of a combination of several systems, NULL is
returned.

\note The returned cpuset is not newly allocated and should thus not be
changed or freed; hwloc_bitmap_dup() must be used to obtain a local copy.


refid: ga5c3ddcb2d19bc0b58042c9fc974f0fa5
name: hwloc_topology_get_topology_cpuset
definition: static hwloc_const_cpuset_t hwloc_topology_get_topology_cpuset
type: hwloc_const_cpuset_t
argsstring: (hwloc_topology_t topology)
briefdescription: Get topology CPU set.
detaileddescription:
\return the CPU set of logical processors of the system for which hwloc
provides topology information. This is equivalent to the cpuset of the
system object. If the topology is the result of a combination of several
systems, NULL is returned.

\note The returned cpuset is not newly allocated and should thus not be
changed or freed; hwloc_bitmap_dup() must be used to obtain a local copy.


refid: gacec35bb7656c1944c514044ca4ce9c6f
name: hwloc_topology_get_online_cpuset
definition: static hwloc_const_cpuset_t hwloc_topology_get_online_cpuset
type: hwloc_const_cpuset_t
argsstring: (hwloc_topology_t topology)
briefdescription: Get online CPU set.
detaileddescription:
\return the CPU set of online logical processors of the system. If the
topology is the result of a combination of several systems, NULL is
returned.

\note The returned cpuset is not newly allocated and should thus not be
changed or freed; hwloc_bitmap_dup() must be used to obtain a local copy.


refid: ga8cb598b3bce8d67cbdfc1f29caad28f6
name: hwloc_topology_get_allowed_cpuset
definition: static hwloc_const_cpuset_t hwloc_topology_get_allowed_cpuset
type: hwloc_const_cpuset_t
argsstring: (hwloc_topology_t topology)
briefdescription: Get allowed CPU set.
detaileddescription:
\return the CPU set of allowed logical processors of the system. If the
topology is the result of a combination of several systems, NULL is
returned.

\note The returned cpuset is not newly allocated and should thus not be
changed or freed, hwloc_bitmap_dup() must be used to obtain a local copy.


refid: ga22002d6fc14a25a3947c42cba0a70134
name: hwloc_topology_get_complete_nodeset
definition: static hwloc_const_nodeset_t hwloc_topology_get_complete_nodeset
type: hwloc_const_nodeset_t
argsstring: (hwloc_topology_t topology)
briefdescription: Get complete node set.
detaileddescription:
\return the complete node set of memory of the system. If the
topology is the result of a combination of several systems, NULL is
returned.

\note The returned nodeset is not newly allocated and should thus not be
changed or freed; hwloc_bitmap_dup() must be used to obtain a local copy.


refid: ga2f1cb5bc87dabb252b691c5c15555d21
name: hwloc_topology_get_topology_nodeset
definition: static hwloc_const_nodeset_t hwloc_topology_get_topology_nodeset
type: hwloc_const_nodeset_t
argsstring: (hwloc_topology_t topology)
briefdescription: Get topology node set.
detaileddescription:
\return the node set of memory of the system for which hwloc
provides topology information. This is equivalent to the nodeset of the
system object. If the topology is the result of a combination of several
systems, NULL is returned.

\note The returned nodeset is not newly allocated and should thus not be
changed or freed; hwloc_bitmap_dup() must be used to obtain a local copy.


refid: ga706182498ac92528e274e9b8d944273d
name: hwloc_topology_get_allowed_nodeset
definition: static hwloc_const_nodeset_t hwloc_topology_get_allowed_nodeset
type: hwloc_const_nodeset_t
argsstring: (hwloc_topology_t topology)
briefdescription: Get allowed node set.
detaileddescription:
\return the node set of allowed memory of the system. If the
topology is the result of a combination of several systems, NULL is
returned.

\note The returned nodeset is not newly allocated and should thus not be
changed or freed, hwloc_bitmap_dup() must be used to obtain a local copy.


refid: ga8fbd641f284673a3e884e8e556044eba
name: hwloc_cpuset_to_nodeset
definition: static void hwloc_cpuset_to_nodeset
type: void
argsstring: (hwloc_topology_t topology, hwloc_const_cpuset_t _cpuset, hwloc_nodeset_t nodeset)
briefdescription: Convert a CPU set into a NUMA node set and handle non-NUMA cases.
detaileddescription:
If some NUMA nodes have no CPUs at all, this function never sets their
indexes in the output node set, even if a full CPU set is given in input.

If the topology contains no NUMA nodes, the machine is considered
as a single memory node, and the following behavior is used:
If \p cpuset is empty, \p nodeset will be emptied as well.
Otherwise \p nodeset will be entirely filled.


refid: ga014490779e7012ffec2b5ccee020c0ae
name: hwloc_cpuset_to_nodeset_strict
definition: static void hwloc_cpuset_to_nodeset_strict
type: void
argsstring: (struct hwloc_topology *topology, hwloc_const_cpuset_t _cpuset, hwloc_nodeset_t nodeset)
briefdescription: Convert a CPU set into a NUMA node set without handling non-NUMA cases.
detaileddescription:
This is the strict variant of ::hwloc_cpuset_to_nodeset. It does not fix
non-NUMA cases. If the topology contains some NUMA nodes, behave exactly
the same. However, if the topology contains no NUMA nodes, return an empty
nodeset.


refid: ga2ed57313ce5bf85f3ac156932ecf639d
name: hwloc_cpuset_from_nodeset
definition: static void hwloc_cpuset_from_nodeset
type: void
argsstring: (hwloc_topology_t topology, hwloc_cpuset_t _cpuset, hwloc_const_nodeset_t nodeset)
briefdescription: Convert a NUMA node set into a CPU set and handle non-NUMA cases.
detaileddescription:
If the topology contains no NUMA nodes, the machine is considered
as a single memory node, and the following behavior is used:
If \p nodeset is empty, \p cpuset will be emptied as well.
Otherwise \p cpuset will be entirely filled.
This is useful for manipulating memory binding sets.


refid: gacde800e58b8cdb746706b371ca4b97e0
name: hwloc_cpuset_from_nodeset_strict
definition: static void hwloc_cpuset_from_nodeset_strict
type: void
argsstring: (struct hwloc_topology *topology, hwloc_cpuset_t _cpuset, hwloc_const_nodeset_t nodeset)
briefdescription: Convert a NUMA node set into a CPU set without handling non-NUMA cases.
detaileddescription:
This is the strict variant of ::hwloc_cpuset_from_nodeset. It does not fix
non-NUMA cases. If the topology contains some NUMA nodes, behave exactly
the same. However, if the topology contains no NUMA nodes, return an empty
cpuset.


refid: ga07219dc0fd6e4553a658eaa73f038c42
name: hwloc_get_whole_distance_matrix_by_depth
definition: static const struct hwloc_distances_s* hwloc_get_whole_distance_matrix_by_depth
type: const struct hwloc_distances_s *
argsstring: (hwloc_topology_t topology, unsigned depth)
briefdescription: Get the distances between all objects at the given depth.
detaileddescription:
\return a distances structure containing a matrix with all distances
between all objects at the given depth.

Slot i+nbobjs*j contains the distance from the object of logical index i
the object of logical index j.

\note This function only returns matrices covering the whole topology,
without any unknown distance value. Those matrices are available in
top-level object of the hierarchy. Matrices of lower objects are not
reported here since they cover only part of the machine.

The returned structure belongs to the hwloc library. The caller should
not modify or free it.

\return \c NULL if no such distance matrix exists.


refid: ga64529254be72b3c4343b25926c84b12f
name: hwloc_get_whole_distance_matrix_by_type
definition: static const struct hwloc_distances_s* hwloc_get_whole_distance_matrix_by_type
type: const struct hwloc_distances_s *
argsstring: (hwloc_topology_t topology, hwloc_obj_type_t type)
briefdescription: Get the distances between all objects of a given type.
detaileddescription:
\return a distances structure containing a matrix with all distances
between all objects of the given type.

Slot i+nbobjs*j contains the distance from the object of logical index i
the object of logical index j.

\note This function only returns matrices covering the whole topology,
without any unknown distance value. Those matrices are available in
top-level object of the hierarchy. Matrices of lower objects are not
reported here since they cover only part of the machine.

The returned structure belongs to the hwloc library. The caller should
not modify or free it.

\return \c NULL if no such distance matrix exists.


refid: ga2d159b21a49964cc629dde03cbf05702
name: hwloc_get_distance_matrix_covering_obj_by_depth
definition: static const struct hwloc_distances_s* hwloc_get_distance_matrix_covering_obj_by_depth
type: const struct hwloc_distances_s *
argsstring: (hwloc_topology_t topology, hwloc_obj_t obj, unsigned depth, unsigned *firstp)
briefdescription: Get distances for the given depth and covering some objects.
detaileddescription:
Return a distance matrix that describes depth \p depth and covers at
least object \p obj and all its children.

When looking for the distance between some objects, a common ancestor should
be passed in \p obj.

\p firstp is set to logical index of the first object described by the matrix.

The returned structure belongs to the hwloc library. The caller should
not modify or free it.


refid: ga79ed880a55f9d03b4ae58ef5116812d7
name: hwloc_get_latency
definition: static int hwloc_get_latency
type: int
briefdescription: Get the latency in both directions between two objects.
argsstring:
(hwloc_topology_t topology, hwloc_obj_t obj1, hwloc_obj_t obj2, float *latency, float *reverse_latency)

detaileddescription:
Look at ancestor objects from the bottom to the top until one of them
contains a distance matrix that matches the objects exactly.

\p latency gets the value from object \p obj1 to \p obj2, while
\p reverse_latency gets the reverse-direction value, which
may be different on some architectures.

\return -1 if no ancestor contains a matching latency matrix.


refid: gaf139bb61375178e90cc3f1835b452ab6
name: hwloc_get_non_io_ancestor_obj
definition: static hwloc_obj_t hwloc_get_non_io_ancestor_obj
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, hwloc_obj_t ioobj)
briefdescription: Get the first non-I/O ancestor object.
detaileddescription:
Given the I/O object \p ioobj, find the smallest non-I/O ancestor
object. This regular object may then be used for binding because
its locality is the same as \p ioobj.


refid: gacdbaf0db98872e224b7883a84bfb0455
name: hwloc_get_pcidev_by_busid
definition: static hwloc_obj_t hwloc_get_pcidev_by_busid
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, unsigned domain, unsigned bus, unsigned dev, unsigned func)
briefdescription:
Find the PCI device object matching the PCI bus id
given domain, bus device and function PCI bus id.


refid: gacd37bb612667dc437d66bfb175a8dc55
name: hwloc_obj_type_t
briefdescription: Type of topology object.
detaileddescription:
\note Do not rely on the ordering or completeness of the values as new ones
may be defined in the future!  If you need to compare types, use
hwloc_compare_types() instead.


refid: gada025d3ec20b4b420f8038d23d6e7bde
name: hwloc_topology_flags_e
briefdescription: Flags to be set onto a topology context before load.
detaileddescription:
Flags should be given to hwloc_topology_set_flags().
They may also be returned by hwloc_topology_get_flags().


refid: ga217dc8d373f8958cc93c154ebce1c71c
name: hwloc_cpubind_flags_t
briefdescription: Process/Thread binding flags.
detaileddescription:
These bit flags can be used to refine the binding policy.

The default (0) is to bind the current process, assumed to be
single-threaded, in a non-strict way.  This is the most portable
way to bind as all operating systems usually provide it.

\note Not all systems support all kinds of binding.  See the
"Detailed Description" section of \ref hwlocality_cpubinding for a
description of errors that can occur.


refid: gac9764f79505775d06407b40f5e4661e8
name: hwloc_membind_policy_t
briefdescription: Memory binding policy.
detaileddescription:
These constants can be used to choose the binding policy.  Only one policy can
be used at a time (i.e., the values cannot be OR'ed together).

Not all systems support all kinds of binding.
hwloc_topology_get_support() may be used to query about the actual memory
binding policy support in the currently used operating system.
See the "Detailed Description" section of \ref hwlocality_membinding
for a description of errors that can occur.


refid: gab00475fd98815bf4fb9aaf752030e7d2
name: hwloc_membind_flags_t
briefdescription: Memory binding flags.
detaileddescription:
These flags can be used to refine the binding policy.
All flags can be logically OR'ed together with the exception of
::HWLOC_MEMBIND_PROCESS and ::HWLOC_MEMBIND_THREAD;
these two flags are mutually exclusive.

Not all systems support all kinds of binding.
hwloc_topology_get_support() may be used to query about the actual memory
binding support in the currently used operating system.
See the "Detailed Description" section of \ref hwlocality_membinding
for a description of errors that can occur.


refid: ga4bbf39b68b6f568fb92739e7c0ea7801
name: hwloc_cpuset_t
definition: typedef hwloc_bitmap_t hwloc_cpuset_t
type: hwloc_bitmap_t
briefdescription: A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.
detaileddescription:
It may be consulted and modified with the bitmap API as any
::hwloc_bitmap_t (see hwloc/bitmap.h).

Each bit may be converted into a PU object using
hwloc_get_pu_obj_by_os_index().


refid: ga37e35730fa7e775b5bb0afe893d6d508
name: hwloc_nodeset_t
definition: typedef hwloc_bitmap_t hwloc_nodeset_t
type: hwloc_bitmap_t
briefdescription: A node set is a bitmap whose bits are set according to NUMA memory node physical OS indexes.
detaileddescription:
It may be consulted and modified with the bitmap API as any
::hwloc_bitmap_t (see hwloc/bitmap.h).
Each bit may be converted into a NUMA node object using
hwloc_get_numanode_obj_by_os_index().

When binding memory on a system without any NUMA node
(when the whole memory is considered as a single memory bank),
the nodeset may be either empty (no memory selected)
or full (whole system memory selected).

See also \ref hwlocality_helper_nodeset_convert.


refid: ga1820ea0dfd8e9dca28f9ea7624df5ae2
name: hwloc_compare_types
definition: int hwloc_compare_types
type: int
argsstring: (hwloc_obj_type_t type1, hwloc_obj_type_t type2)
briefdescription: Compare the depth of two object types.
detaileddescription:
Types shouldn't be compared as they are, since newer ones may be added in
the future.  This function returns less than, equal to, or greater than zero
respectively if \p type1 objects usually include \p type2 objects, are the
same as \p type2 objects, or are included in \p type2 objects. If the types
can not be compared (because neither is usually contained in the other),
HWLOC_TYPE_UNORDERED is returned.  Object types containing CPUs can always
be compared (usually, a system contains machines which contain nodes which
contain sockets which contain caches, which contain cores, which contain
processors).

\note HWLOC_OBJ_PU will always be the deepest.
\note This does not mean that the actual topology will respect that order:
e.g. as of today cores may also contain caches, and sockets may also contain
nodes. This is thus just to be seen as a fallback comparison method.


refid: ga03fd4a16d8b9ee1ffc32b25fd2f6bdfa
name: hwloc_topology_init
definition: int hwloc_topology_init
type: int
argsstring: (hwloc_topology_t *topologyp)
briefdescription: Allocate a topology context.
detaileddescription:
\param[out] topologyp is assigned a pointer to the new allocated context.

\return 0 on success, -1 on error.


refid: gabdf58d87ad77f6615fccdfe0535ff826
name: hwloc_topology_load
definition: int hwloc_topology_load
type: int
argsstring: (hwloc_topology_t topology)
briefdescription: Build the actual topology.
detaileddescription:
Build the actual topology once initialized with hwloc_topology_init() and
tuned with \ref hwlocality_configuration routines.
No other routine may be called earlier using this topology context.

\param topology is the topology to be loaded with objects.

\return 0 on success, -1 on error.

\note On failure, the topology is reinitialized. It should be either
destroyed with hwloc_topology_destroy() or configured and loaded again.

\note This function may be called only once per topology.

\sa hwlocality_configuration


refid: gaf6746bc3a558ef1ac8348b4491d091b5
name: hwloc_topology_check
definition: void hwloc_topology_check
type: void
argsstring: (hwloc_topology_t topology)
briefdescription: Run internal checks on a topology structure.
detaileddescription:
The program aborts if an inconsistency is detected in the given topology.

\param topology is the topology to be checked

\note This routine is only useful to developers.

\note The input topology should have been previously loaded with
hwloc_topology_load().


refid: gafcf30842e8cb47b4c3dcaebecea31e17
name: hwloc_topology_ignore_type
definition: int hwloc_topology_ignore_type
type: int
argsstring: (hwloc_topology_t topology, hwloc_obj_type_t type)
briefdescription: Ignore an object type.
detaileddescription:
Ignore all objects from the given type.
The bottom-level type HWLOC_OBJ_PU may not be ignored.
The top-level object of the hierarchy will never be ignored, even if this function
succeeds.
I/O objects may not be ignored, topology flags should be used to configure
their discovery instead.


refid: ga1f987bca941d6949faf7b1554dd7bc12
name: hwloc_topology_ignore_type_keep_structure
definition: int hwloc_topology_ignore_type_keep_structure
type: int
argsstring: (hwloc_topology_t topology, hwloc_obj_type_t type)
briefdescription: Ignore an object type if it does not bring any structure.
detaileddescription:
Ignore all objects from the given type as long as they do not bring any structure:
Each ignored object should have a single children or be the only child of its parent.
The bottom-level type HWLOC_OBJ_PU may not be ignored.
I/O objects may not be ignored, topology flags should be used to configure
their discovery instead.


refid: ga7c9cf147442d65d755c664ccde3bb3ef
name: hwloc_topology_ignore_all_keep_structure
definition: int hwloc_topology_ignore_all_keep_structure
type: int
argsstring: (hwloc_topology_t topology)
briefdescription: Ignore all objects that do not bring any structure.
detaileddescription:
Ignore all objects that do not bring any structure:
Each ignored object should have a single children or be the only child of its parent.
I/O objects may not be ignored, topology flags should be used to configure
their discovery instead.


refid: gaaeed4df656979e5f16befea9d29b814b
name: hwloc_topology_set_flags
definition: int hwloc_topology_set_flags
type: int
argsstring: (hwloc_topology_t topology, unsigned long flags)
briefdescription: Set OR'ed flags to non-yet-loaded topology.
detaileddescription:
Set a OR'ed set of ::hwloc_topology_flags_e onto a topology that was not yet loaded.

If this function is called multiple times, the last invokation will erase
and replace the set of flags that was previously set.

The flags set in a topology may be retrieved with hwloc_topology_get_flags()


refid: ga09318f81c1d4713be907d64748a6f93c
name: hwloc_topology_get_flags
definition: unsigned long hwloc_topology_get_flags
type: unsigned long
argsstring: (hwloc_topology_t topology)
briefdescription: Get OR'ed flags of a topology.
detaileddescription:
Get the OR'ed set of ::hwloc_topology_flags_e of a topology.

\return the flags previously set with hwloc_topology_set_flags().


refid: ga341fc17b5867a4715570baab131f68cd
name: hwloc_topology_set_pid
definition: int hwloc_topology_set_pid
type: int
argsstring: (hwloc_topology_t restrict topology, hwloc_pid_t pid)
briefdescription: Change which pid the topology is viewed from.
detaileddescription:
On some systems, processes may have different views of the machine, for
instance the set of allowed CPUs. By default, hwloc exposes the view from
the current process. Calling hwloc_topology_set_pid() permits to make it
expose the topology of the machine from the point of view of another
process.

\note \p hwloc_pid_t is \p pid_t on Unix platforms,
and \p HANDLE on native Windows platforms.

\note -1 is returned and errno is set to ENOSYS on platforms that do not
support this feature.


refid: gac0ea95d5f2ad78408bc267a0441c7c97
name: hwloc_topology_set_fsroot
definition: int hwloc_topology_set_fsroot
type: int
argsstring: (hwloc_topology_t restrict topology, const char *restrict fsroot_path)
briefdescription: Change the file-system root path when building the topology from sysfs/procfs.
detaileddescription:
On Linux system, use sysfs and procfs files as if they were mounted on the given
\p fsroot_path instead of the main file-system root. Setting the environment
variable HWLOC_FSROOT may also result in this behavior.
Not using the main file-system root causes hwloc_topology_is_thissystem()
to return 0.

Note that this function does not actually load topology
information; it just tells hwloc where to load it from.  You'll
still need to invoke hwloc_topology_load() to actually load the
topology information.

\return -1 with errno set to ENOSYS on non-Linux and on Linux systems that
do not support it.
\return -1 with the appropriate errno if \p fsroot_path cannot be used.

\note For convenience, this backend provides empty binding hooks which just
return success.  To have hwloc still actually call OS-specific hooks, the
HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM has to be set to assert that the loaded
file is really the underlying system.

\note On success, the Linux component replaces the previously enabled
component (if any), but the topology is not actually modified until
hwloc_topology_load().


refid: ga4fab186bb6181a00bcf585825fddd38d
name: hwloc_topology_set_synthetic
definition: int hwloc_topology_set_synthetic
type: int
argsstring: (hwloc_topology_t restrict topology, const char *restrict description)
briefdescription: Enable synthetic topology.
detaileddescription:
Gather topology information from the given \p description,
a space-separated string of numbers describing
the arity of each level.
Each number may be prefixed with a type and a colon to enforce the type
of a level.  If only some level types are enforced, hwloc will try to
choose the other types according to usual topologies, but it may fail
and you may have to specify more level types manually.
See also the \ref synthetic.

If \p description was properly parsed and describes a valid topology
configuration, this function returns 0.
Otherwise -1 is returned and errno is set to EINVAL.

Note that this function does not actually load topology
information; it just tells hwloc where to load it from.  You'll
still need to invoke hwloc_topology_load() to actually load the
topology information.

\note For convenience, this backend provides empty binding hooks which just
return success.

\note On success, the synthetic component replaces the previously enabled
component (if any), but the topology is not actually modified until
hwloc_topology_load().


refid: ga879439b7ee99407ee911b3ac64e9a25e
name: hwloc_topology_set_xml
definition: int hwloc_topology_set_xml
type: int
argsstring: (hwloc_topology_t restrict topology, const char *restrict xmlpath)
briefdescription: Enable XML-file based topology.
detaileddescription:
Gather topology information from the XML file given at \p xmlpath.
Setting the environment variable HWLOC_XMLFILE may also result in this behavior.
This file may have been generated earlier with hwloc_topology_export_xml()
or lstopo file.xml.

Note that this function does not actually load topology
information; it just tells hwloc where to load it from.  You'll
still need to invoke hwloc_topology_load() to actually load the
topology information.

\return -1 with errno set to EINVAL on failure to read the XML file.

\note See also hwloc_topology_set_userdata_import_callback()
for importing application-specific object userdata.

\note For convenience, this backend provides empty binding hooks which just
return success.  To have hwloc still actually call OS-specific hooks, the
HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM has to be set to assert that the loaded
file is really the underlying system.

\note On success, the XML component replaces the previously enabled
component (if any), but the topology is not actually modified until
hwloc_topology_load().


refid: ga2745616b65595e1c1e579ecc7e461fa8
name: hwloc_topology_set_xmlbuffer
definition: int hwloc_topology_set_xmlbuffer
type: int
argsstring: (hwloc_topology_t restrict topology, const char *restrict buffer, int size)
detaileddescription:
Gather topology information from the XML memory buffer given at \p
buffer and of length \p size.  This buffer may have been filled
earlier with hwloc_topology_export_xmlbuffer().

Note that this function does not actually load topology
information; it just tells hwloc where to load it from.  You'll
still need to invoke hwloc_topology_load() to actually load the
topology information.

\return -1 with errno set to EINVAL on failure to read the XML buffer.

\note See also hwloc_topology_set_userdata_import_callback()
for importing application-specific object userdata.

\note For convenience, this backend provides empty binding hooks which just
return success.  To have hwloc still actually call OS-specific hooks, the
HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM has to be set to assert that the loaded
file is really the underlying system.

\note On success, the XML component replaces the previously enabled
component (if any), but the topology is not actually modified until
hwloc_topology_load().

briefdescription:
Enable XML based topology using a memory buffer (instead of
a file, as with hwloc_topology_set_xml()).


refid: gad1f15795219e2c3ca6d44ba0db604c4f
name: hwloc_topology_set_custom
definition: int hwloc_topology_set_custom
type: int
argsstring: (hwloc_topology_t topology)
briefdescription: Prepare the topology for custom assembly.
detaileddescription:
The topology then contains a single root object.
It must then be built by inserting other topologies with
hwloc_custom_insert_topology() or single objects with
hwloc_custom_insert_group_object_by_parent().
hwloc_topology_load() must be called to finalize the new
topology as usual.

\note If nothing is inserted in the topology,
hwloc_topology_load() will fail with errno set to EINVAL.

\note The cpuset and nodeset of the root object are NULL because
these sets are meaningless when assembling multiple topologies.

\note On success, the custom component replaces the previously enabled
component (if any), but the topology is not actually modified until
hwloc_topology_load().


refid: ga90ed5733946b2e9aba90d2e2c1fbfbd7
name: hwloc_topology_set_distance_matrix
definition: int hwloc_topology_set_distance_matrix
type: int
briefdescription: Provide a distance matrix.
argsstring:
(hwloc_topology_t restrict topology, hwloc_obj_type_t type, unsigned nbobjs, unsigned *os_index, float *distances)

detaileddescription:
Provide the matrix of distances between a set of objects of the given type.
The set may or may not contain all the existing objects of this type.
The objects are specified by their OS/physical index in the \p os_index
array. The \p distances matrix follows the same order.
The distance from object i to object j in the i*nbobjs+j.

A single latency matrix may be defined for each type.
If another distance matrix already exists for the given type,
either because the user specified it or because the OS offers it,
it will be replaced by the given one.
If \p nbobjs is \c 0, \p os_index is \c NULL and \p distances is \c NULL,
the existing distance matrix for the given type is removed.

\note Distance matrices are ignored in multi-node topologies.


refid: ga68ffdcfd9175cdf40709801092f18017
name: hwloc_topology_is_thissystem
definition: int hwloc_topology_is_thissystem
type: int
argsstring: (hwloc_topology_t restrict topology)
briefdescription: Does the topology context come from this system?
detaileddescription:
\return 1 if this topology context was built using the system
running this program.
\return 0 instead (for instance if using another file-system root,
a XML topology file, or a synthetic topology).


refid: ga2cc7b7b155cba58dda203e54f1637b9c
name: hwloc_topology_set_userdata
definition: void hwloc_topology_set_userdata
type: void
argsstring: (hwloc_topology_t topology, const void *userdata)
briefdescription: Set the topology-specific userdata pointer.
detaileddescription:
Each topology may store one application-given private data pointer.
It is initialized to \c NULL.
hwloc will never modify it.

Use it as you wish, after hwloc_topology_init() and until hwloc_topolog_destroy().

This pointer is not exported to XML.


refid: ga91f992f8d6c4905b2d3c4f43e509c2a3
name: hwloc_topology_get_userdata
definition: void* hwloc_topology_get_userdata
type: void *
argsstring: (hwloc_topology_t topology)
briefdescription: Retrieve the topology-specific userdata pointer.
detaileddescription:
Retrieve the application-given private data pointer that was
previously set with hwloc_topology_set_userdata().


refid: ga8bec782e21be313750da70cf7428b374
name: hwloc_get_type_depth
definition: int hwloc_get_type_depth
type: int
argsstring: (hwloc_topology_t topology, hwloc_obj_type_t type)
briefdescription: Returns the depth of objects of type \p type.
detaileddescription:
If no object of this type is present on the underlying architecture, or if
the OS doesn't provide this kind of information, the function returns
HWLOC_TYPE_DEPTH_UNKNOWN.

If type is absent but a similar type is acceptable, see also
hwloc_get_type_or_below_depth() and hwloc_get_type_or_above_depth().

If some objects of the given type exist in different levels,
for instance L1 and L2 caches, or L1i and L1d caches,
the function returns HWLOC_TYPE_DEPTH_MULTIPLE.
See hwloc_get_cache_type_depth() in hwloc/helper.h to better handle this
case.

If an I/O object type is given, the function returns a virtual value
because I/O objects are stored in special levels that are not CPU-related.
This virtual depth may be passed to other hwloc functions such as
hwloc_get_obj_by_depth() but it should not be considered as an actual
depth by the application. In particular, it should not be compared with
any other object depth or with the entire topology depth.


refid: ga8125328e69eba709c33ea8055c12589b
name: hwloc_get_type_or_below_depth
definition: static int hwloc_get_type_or_below_depth
type: int
argsstring: (hwloc_topology_t topology, hwloc_obj_type_t type)
briefdescription: Returns the depth of objects of type \p type or below.
detaileddescription:
If no object of this type is present on the underlying architecture, the
function returns the depth of the first "present" object typically found
inside \p type.

If some objects of the given type exist in different levels, for instance
L1 and L2 caches, the function returns HWLOC_TYPE_DEPTH_MULTIPLE.


refid: ga8a9ee573b7d2190272095d10712a7cca
name: hwloc_get_type_or_above_depth
definition: static int hwloc_get_type_or_above_depth
type: int
argsstring: (hwloc_topology_t topology, hwloc_obj_type_t type)
briefdescription: Returns the depth of objects of type \p type or above.
detaileddescription:
If no object of this type is present on the underlying architecture, the
function returns the depth of the first "present" object typically
containing \p type.

If some objects of the given type exist in different levels, for instance
L1 and L2 caches, the function returns HWLOC_TYPE_DEPTH_MULTIPLE.


refid: ga789a3f65aedff644be64a18526a03065
name: hwloc_get_nbobjs_by_type
definition: static int hwloc_get_nbobjs_by_type
type: int
argsstring: (hwloc_topology_t topology, hwloc_obj_type_t type)
briefdescription: Returns the width of level type \p type.
detaileddescription:
If no object for that type exists, 0 is returned.
If there are several levels with objects of that type, -1 is returned.


refid: ga6f414dd80a2b943967a0ac92da3181a2
name: hwloc_get_obj_by_type
definition: static hwloc_obj_t hwloc_get_obj_by_type
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, hwloc_obj_type_t type, unsigned idx)
briefdescription: Returns the topology object at logical index \p idx with type \p type.
detaileddescription:
If no object for that type exists, \c NULL is returned.
If there are several levels with objects of that type, \c NULL is returned
and ther caller may fallback to hwloc_get_obj_by_depth().


refid: ga759e88eaf5a230ad283e9d4c42486735
name: hwloc_get_next_obj_by_type
definition: static hwloc_obj_t hwloc_get_next_obj_by_type
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, hwloc_obj_type_t type, hwloc_obj_t prev)
briefdescription: Returns the next object of type \p type.
detaileddescription:
If \p prev is \c NULL, return the first object at type \p type.  If
there are multiple or no depth for given type, return \c NULL and
let the caller fallback to hwloc_get_next_obj_by_depth().


refid: ga8f8452fa8e707cad59b8a73a6fa06059
name: hwloc_obj_type_sscanf
definition: int hwloc_obj_type_sscanf
type: int
briefdescription: Return an object type and attributes from a type string.
argsstring:
(const char *string, hwloc_obj_type_t *typep, int *depthattrp, void *typeattrp, size_t typeattrsize)

detaileddescription:
Convert strings such as "socket" or "cache" into the corresponding types.
Matching is case-insensitive, and only the first letters are actually
required to match.

Types that have specific attributes, for instance caches and groups,
may be returned in \p depthattrp and \p typeattrp. They are ignored
when these pointers are \c NULL.

For instance "L2i" or "L2iCache" would return
type HWLOC_OBJ_CACHE in \p typep, 2 in \p depthattrp,
and HWLOC_OBJ_CACHE_TYPE_INSTRUCTION in \p typeattrp
(this last pointer should point to a hwloc_obj_cache_type_t).
"Group3" would return type HWLOC_OBJ_GROUP type and 3 in \p depthattrp.
Attributes that are not specified in the string (for instance "Group"
without a depth, or "L2Cache" without a cache type) are set to -1.

\p typeattrd is only filled if the size specified in \p typeattrsize
is large enough. It is currently only used for caches, and the required
size is at least the size of hwloc_obj_cache_type_t.

\return 0 if a type was correctly identified, otherwise -1.

\note This is an extended version of the now deprecated hwloc_obj_type_of_string()


refid: gadb8765c260edea80c52cd06a76639ba4
name: hwloc_obj_type_snprintf
definition: int hwloc_obj_type_snprintf
type: int
argsstring: (char *restrict string, size_t size, hwloc_obj_t obj, int verbose)
briefdescription: Stringify the type of a given topology object into a human-readable form.
detaileddescription:
It differs from hwloc_obj_type_string() because it prints type attributes such
as cache depth and type.

If \p size is 0, \p string may safely be \c NULL.

\return the number of character that were actually written if not truncating,
or that would have been written (not including the ending \\0).


refid: ga870e876931c282a1c7aee2f031912ce3
name: hwloc_obj_attr_snprintf
definition: int hwloc_obj_attr_snprintf
type: int
argsstring: (char *restrict string, size_t size, hwloc_obj_t obj, const char *restrict separator, int verbose)
briefdescription: Stringify the attributes of a given topology object into a human-readable form.
detaileddescription:
Attribute values are separated by \p separator.

Only the major attributes are printed in non-verbose mode.

If \p size is 0, \p string may safely be \c NULL.

\return the number of character that were actually written if not truncating,
or that would have been written (not including the ending \\0).


refid: ga8e0472dfa655c68c0c9072e1ee3a1e03
name: hwloc_obj_cpuset_snprintf
definition: int hwloc_obj_cpuset_snprintf
type: int
argsstring: (char *restrict str, size_t size, size_t nobj, const hwloc_obj_t *restrict objs)
briefdescription: Stringify the cpuset containing a set of objects.
detaileddescription:
If \p size is 0, \p string may safely be \c NULL.

\return the number of character that were actually written if not truncating,
or that would have been written (not including the ending \\0).


refid: gab358661a92bb27d8542b255cc9f6f25e
name: hwloc_obj_get_info_by_name
definition: static const char* hwloc_obj_get_info_by_name
type: const char *
argsstring: (hwloc_obj_t obj, const char *name)
briefdescription: Search the given key name in object infos and return the corresponding value.
detaileddescription:
If multiple keys match the given name, only the first one is returned.

\return \c NULL if no such key exists.


refid: ga7e90c5398a9d77df31d7d45faf0f316b
name: hwloc_obj_add_info
definition: void hwloc_obj_add_info
type: void
argsstring: (hwloc_obj_t obj, const char *name, const char *value)
briefdescription: Add the given info name and value pair to the given object.
detaileddescription:
The info is appended to the existing info array even if another key
with the same name already exists.

The input strings are copied before being added in the object infos.

\note This function may be used to enforce object colors in the lstopo
graphical output by using "lstopoStyle" as a name and "Background=#rrggbb"
as a value. See CUSTOM COLORS in the lstopo(1) manpage for details.

\note If \p value contains some non-printable characters, they will
be dropped when exporting to XML, see hwloc_topology_export_xml().


refid: ga80bc07473a8edf840cae17bd7ec21d48
name: hwloc_set_cpubind
definition: int hwloc_set_cpubind
type: int
argsstring: (hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
briefdescription: Bind current process or thread on cpus given in physical bitmap \p set.
detaileddescription:
\return -1 with errno set to ENOSYS if the action is not supported
\return -1 with errno set to EXDEV if the binding cannot be enforced


refid: gacba7ecb979baf824d5240fa2cb2a8be6
name: hwloc_get_cpubind
definition: int hwloc_get_cpubind
type: int
argsstring: (hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
briefdescription: Get current process or thread binding.
detaileddescription:
Writes into \p set the physical cpuset which the process or thread (according to \e
flags) was last bound to.


refid: ga296db8a3c6d49b51fb83d6f3e45c02a6
name: hwloc_set_proc_cpubind
definition: int hwloc_set_proc_cpubind
type: int
argsstring: (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t set, int flags)
briefdescription: Bind a process \p pid on cpus given in physical bitmap \p set.
detaileddescription:
\note \p hwloc_pid_t is \p pid_t on Unix platforms,
and \p HANDLE on native Windows platforms.

\note As a special case on Linux, if a tid (thread ID) is supplied
instead of a pid (process ID) and HWLOC_CPUBIND_THREAD is passed in flags,
the binding is applied to that specific thread.

\note On non-Linux systems, HWLOC_CPUBIND_THREAD can not be used in \p flags.


refid: gac82de91f788fa82dacf99c6e0d4b7158
name: hwloc_get_proc_cpubind
definition: int hwloc_get_proc_cpubind
type: int
argsstring: (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
briefdescription: Get the current physical binding of process \p pid.
detaileddescription:
\note \p hwloc_pid_t is \p pid_t on Unix platforms,
and \p HANDLE on native Windows platforms.

\note As a special case on Linux, if a tid (thread ID) is supplied
instead of a pid (process ID) and HWLOC_CPUBIND_THREAD is passed in flags,
the binding for that specific thread is returned.

\note On non-Linux systems, HWLOC_CPUBIND_THREAD can not be used in \p flags.


refid: gae42c01b2addcfbf6048b9a516dd7a906
name: hwloc_set_thread_cpubind
definition: int hwloc_set_thread_cpubind
type: int
argsstring: (hwloc_topology_t topology, hwloc_thread_t thread, hwloc_const_cpuset_t set, int flags)
briefdescription: Bind a thread \p thread on cpus given in physical bitmap \p set.
detaileddescription:
\note \p hwloc_thread_t is \p pthread_t on Unix platforms,
and \p HANDLE on native Windows platforms.

\note HWLOC_CPUBIND_PROCESS can not be used in \p flags.


refid: gafdb374627358bf09203b5a4215b13032
name: hwloc_get_last_cpu_location
definition: int hwloc_get_last_cpu_location
type: int
argsstring: (hwloc_topology_t topology, hwloc_cpuset_t set, int flags)
briefdescription: Get the last physical CPU where the current process or thread ran.
detaileddescription:
The operating system may move some tasks from one processor
to another at any time according to their binding,
so this function may return something that is already
outdated.

\p flags can include either HWLOC_CPUBIND_PROCESS or HWLOC_CPUBIND_THREAD to
specify whether the query should be for the whole process (union of all CPUs
on which all threads are running), or only the current thread. If the
process is single-threaded, flags can be set to zero to let hwloc use
whichever method is available on the underlying OS.


refid: ga910a05c2d47f68a3155bf176b50fa555
name: hwloc_get_proc_last_cpu_location
definition: int hwloc_get_proc_last_cpu_location
type: int
argsstring: (hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t set, int flags)
briefdescription: Get the last physical CPU where a process ran.
detaileddescription:
The operating system may move some tasks from one processor
to another at any time according to their binding,
so this function may return something that is already
outdated.

\note \p hwloc_pid_t is \p pid_t on Unix platforms,
and \p HANDLE on native Windows platforms.

\note As a special case on Linux, if a tid (thread ID) is supplied
instead of a pid (process ID) and HWLOC_CPUBIND_THREAD is passed in flags,
the last CPU location of that specific thread is returned.

\note On non-Linux systems, HWLOC_CPUBIND_THREAD can not be used in \p flags.


refid: ga5cac0bcbe770b43fc63a6b00ea4a7a9d
name: hwloc_set_membind_nodeset
definition: int hwloc_set_membind_nodeset
type: int
argsstring:
(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags)

detaileddescription:
If neither ::HWLOC_MEMBIND_PROCESS nor ::HWLOC_MEMBIND_THREAD is
specified, the current process is assumed to be single-threaded.
This is the most portable form as it permits hwloc to use either
process-based OS functions or thread-based OS functions, depending
on which are available.

\return -1 with errno set to ENOSYS if the action is not supported
\return -1 with errno set to EXDEV if the binding cannot be enforced

briefdescription:
Set the default memory binding policy of the current
process or thread to prefer the NUMA node(s) specified by physical \p nodeset.


refid: ga53a493e13ad8e5f924b50c07713ee5df
name: hwloc_set_membind
definition: int hwloc_set_membind
type: int
argsstring: (hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags)
detaileddescription:
If neither ::HWLOC_MEMBIND_PROCESS nor ::HWLOC_MEMBIND_THREAD is
specified, the current process is assumed to be single-threaded.
This is the most portable form as it permits hwloc to use either
process-based OS functions or thread-based OS functions, depending
on which are available.

\return -1 with errno set to ENOSYS if the action is not supported
\return -1 with errno set to EXDEV if the binding cannot be enforced

briefdescription:
Set the default memory binding policy of the current
process or thread to prefer the NUMA node(s) near the specified physical \p
cpuset.


refid: ga84ee275e84286d17a5853c52272a6a95
name: hwloc_get_membind_nodeset
definition: int hwloc_get_membind_nodeset
type: int
argsstring: (hwloc_topology_t topology, hwloc_nodeset_t nodeset, hwloc_membind_policy_t *policy, int flags)
briefdescription: Query the default memory binding policy and physical locality of the current process or thread.
detaileddescription:
This function has two output parameters: \p nodeset and \p policy.
The values returned in these parameters depend on both the \p flags
passed in and the current memory binding policies and nodesets in
the queried target.

Passing the ::HWLOC_MEMBIND_PROCESS flag specifies that the query
target is the current policies and nodesets for all the threads in
the current process.  Passing ::HWLOC_MEMBIND_THREAD specifies that
the query target is the current policy and nodeset for only the
thread invoking this function.

If neither of these flags are passed (which is the most portable
method), the process is assumed to be single threaded.  This allows
hwloc to use either process-based OS functions or thread-based OS
functions, depending on which are available.

::HWLOC_MEMBIND_STRICT is only meaningful when ::HWLOC_MEMBIND_PROCESS
is also specified.  In this case, hwloc will check the default
memory policies and nodesets for all threads in the process.  If
they are not identical, -1 is returned and errno is set to EXDEV.
If they are identical, the values are returned in \p nodeset and \p
policy.

Otherwise, if ::HWLOC_MEMBIND_PROCESS is specified (and
::HWLOC_MEMBIND_STRICT is \em not specified), \p nodeset is set to
the logical OR of all threads' default nodeset.  If all threads'
default policies are the same, \p policy is set to that policy.  If
they are different, \p policy is set to ::HWLOC_MEMBIND_MIXED.

In the ::HWLOC_MEMBIND_THREAD case (or when neither
::HWLOC_MEMBIND_PROCESS or ::HWLOC_MEMBIND_THREAD is specified), there
is only one nodeset and policy; they are returned in \p nodeset and
\p policy, respectively.

If any other flags are specified, -1 is returned and errno is set
to EINVAL.


refid: gabf567d2e3b956591a43de0c1941943b0
name: hwloc_get_membind
definition: int hwloc_get_membind
type: int
argsstring: (hwloc_topology_t topology, hwloc_cpuset_t cpuset, hwloc_membind_policy_t *policy, int flags)
detaileddescription:
This function has two output parameters: \p cpuset and \p policy.
The values returned in these parameters depend on both the \p flags
passed in and the current memory binding policies and nodesets in
the queried target.

Passing the ::HWLOC_MEMBIND_PROCESS flag specifies that the query
target is the current policies and nodesets for all the threads in
the current process.  Passing ::HWLOC_MEMBIND_THREAD specifies that
the query target is the current policy and nodeset for only the
thread invoking this function.

If neither of these flags are passed (which is the most portable
method), the process is assumed to be single threaded.  This allows
hwloc to use either process-based OS functions or thread-based OS
functions, depending on which are available.

::HWLOC_MEMBIND_STRICT is only meaningful when ::HWLOC_MEMBIND_PROCESS
is also specified.  In this case, hwloc will check the default
memory policies and nodesets for all threads in the process.  If
they are not identical, -1 is returned and errno is set to EXDEV.
If they are identical, the policy is returned in \p policy.  \p
cpuset is set to the union of CPUs near the NUMA node(s) in the
nodeset.

Otherwise, if ::HWLOC_MEMBIND_PROCESS is specified (and
::HWLOC_MEMBIND_STRICT is \em not specified), the default nodeset
from each thread is logically OR'ed together.  \p cpuset is set to
the union of CPUs near the NUMA node(s) in the resulting nodeset.
If all threads' default policies are the same, \p policy is set to
that policy.  If they are different, \p policy is set to
::HWLOC_MEMBIND_MIXED.

In the ::HWLOC_MEMBIND_THREAD case (or when neither
::HWLOC_MEMBIND_PROCESS or ::HWLOC_MEMBIND_THREAD is specified), there
is only one nodeset and policy.  The policy is returned in \p
policy; \p cpuset is set to the union of CPUs near the NUMA node(s)
in the \p nodeset.

If any other flags are specified, -1 is returned and errno is set
to EINVAL.

briefdescription:
Query the default memory binding policy and physical locality of the
current process or thread (the locality is returned in \p cpuset as
CPUs near the locality's actual NUMA node(s)).


refid: ga21b042d94266a26a9c82b98c4bb30d01
name: hwloc_set_proc_membind_nodeset
definition: int hwloc_set_proc_membind_nodeset
type: int
argsstring:
(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags)

detaileddescription:
\return -1 with errno set to ENOSYS if the action is not supported
\return -1 with errno set to EXDEV if the binding cannot be enforced

\note \p hwloc_pid_t is \p pid_t on Unix platforms,
and \p HANDLE on native Windows platforms.

briefdescription:
Set the default memory binding policy of the specified
process to prefer the NUMA node(s) specified by physical \p nodeset.


refid: ga94b91473febe49fc7af09a0f4a72e53a
name: hwloc_set_proc_membind
definition: int hwloc_set_proc_membind
type: int
argsstring:
(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags)

detaileddescription:
\return -1 with errno set to ENOSYS if the action is not supported
\return -1 with errno set to EXDEV if the binding cannot be enforced

\note \p hwloc_pid_t is \p pid_t on Unix platforms,
and \p HANDLE on native Windows platforms.

briefdescription:
Set the default memory binding policy of the specified
process to prefer the NUMA node(s) near the specified physical \p cpuset.


refid: gac5075b7a2bf55f48f4622351817addad
name: hwloc_get_proc_membind_nodeset
definition: int hwloc_get_proc_membind_nodeset
type: int
briefdescription: Query the default memory binding policy and physical locality of the specified process.
argsstring:
(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_nodeset_t nodeset, hwloc_membind_policy_t *policy, int flags)

detaileddescription:
This function has two output parameters: \p nodeset and \p policy.
The values returned in these parameters depend on both the \p flags
passed in and the current memory binding policies and nodesets in
the queried target.

Passing the ::HWLOC_MEMBIND_PROCESS flag specifies that the query
target is the current policies and nodesets for all the threads in
the specified process.  If ::HWLOC_MEMBIND_PROCESS is not specified
(which is the most portable method), the process is assumed to be
single threaded.  This allows hwloc to use either process-based OS
functions or thread-based OS functions, depending on which are
available.

Note that it does not make sense to pass ::HWLOC_MEMBIND_THREAD to
this function.

If ::HWLOC_MEMBIND_STRICT is specified, hwloc will check the default
memory policies and nodesets for all threads in the specified
process.  If they are not identical, -1 is returned and errno is
set to EXDEV.  If they are identical, the values are returned in \p
nodeset and \p policy.

Otherwise, \p nodeset is set to the logical OR of all threads'
default nodeset.  If all threads' default policies are the same, \p
policy is set to that policy.  If they are different, \p policy is
set to ::HWLOC_MEMBIND_MIXED.

If any other flags are specified, -1 is returned and errno is set
to EINVAL.

\note \p hwloc_pid_t is \p pid_t on Unix platforms,
and \p HANDLE on native Windows platforms.


refid: gada7b3bb7f278542dbb38dc3d6f527c29
name: hwloc_get_proc_membind
definition: int hwloc_get_proc_membind
type: int
argsstring:
(hwloc_topology_t topology, hwloc_pid_t pid, hwloc_cpuset_t cpuset, hwloc_membind_policy_t *policy, int flags)

detaileddescription:
This function has two output parameters: \p cpuset and \p policy.
The values returned in these parameters depend on both the \p flags
passed in and the current memory binding policies and nodesets in
the queried target.

Passing the ::HWLOC_MEMBIND_PROCESS flag specifies that the query
target is the current policies and nodesets for all the threads in
the specified process.  If ::HWLOC_MEMBIND_PROCESS is not specified
(which is the most portable method), the process is assumed to be
single threaded.  This allows hwloc to use either process-based OS
functions or thread-based OS functions, depending on which are
available.

Note that it does not make sense to pass ::HWLOC_MEMBIND_THREAD to
this function.

If ::HWLOC_MEMBIND_STRICT is specified, hwloc will check the default
memory policies and nodesets for all threads in the specified
process.  If they are not identical, -1 is returned and errno is
set to EXDEV.  If they are identical, the policy is returned in \p
policy.  \p cpuset is set to the union of CPUs near the NUMA
node(s) in the nodeset.

Otherwise, the default nodeset from each thread is logically OR'ed
together.  \p cpuset is set to the union of CPUs near the NUMA
node(s) in the resulting nodeset.  If all threads' default policies
are the same, \p policy is set to that policy.  If they are
different, \p policy is set to ::HWLOC_MEMBIND_MIXED.

If any other flags are specified, -1 is returned and errno is set
to EINVAL.

\note \p hwloc_pid_t is \p pid_t on Unix platforms,
and \p HANDLE on native Windows platforms.

briefdescription:
Query the default memory binding policy and physical locality of the
specified process (the locality is returned in \p cpuset as CPUs
near the locality's actual NUMA node(s)).


refid: ga7f11bd709ac0cb93af613e2dd84165ad
name: hwloc_set_area_membind_nodeset
definition: int hwloc_set_area_membind_nodeset
type: int
argsstring:
(hwloc_topology_t topology, const void *addr, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags)

detaileddescription:
\return -1 with errno set to ENOSYS if the action is not supported
\return -1 with errno set to EXDEV if the binding cannot be enforced

briefdescription:
Bind the already-allocated memory identified by (addr, len)
to the NUMA node(s) in physical \p nodeset.


refid: ga93d2698ae5d7330be5e9f8ece6bc9b2c
name: hwloc_set_area_membind
definition: int hwloc_set_area_membind
type: int
argsstring:
(hwloc_topology_t topology, const void *addr, size_t len, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags)

detaileddescription:
\return -1 with errno set to ENOSYS if the action is not supported
\return -1 with errno set to EXDEV if the binding cannot be enforced

briefdescription:
Bind the already-allocated memory identified by (addr, len)
to the NUMA node(s) near physical \p cpuset.


refid: ga5b674a9e043814bfd1c927fd0137fb19
name: hwloc_get_area_membind_nodeset
definition: int hwloc_get_area_membind_nodeset
type: int
briefdescription: Query the physical NUMA node(s) and binding policy of the memory identified by (\p addr, \p len ).
argsstring:
(hwloc_topology_t topology, const void *addr, size_t len, hwloc_nodeset_t nodeset, hwloc_membind_policy_t *policy, int flags)

detaileddescription:
This function has two output parameters: \p nodeset and \p policy.
The values returned in these parameters depend on both the \p flags
passed in and the memory binding policies and nodesets of the pages
in the address range.

If ::HWLOC_MEMBIND_STRICT is specified, the target pages are first
checked to see if they all have the same memory binding policy and
nodeset.  If they do not, -1 is returned and errno is set to EXDEV.
If they are identical across all pages, the nodeset and policy are
returned in \p nodeset and \p policy, respectively.

If ::HWLOC_MEMBIND_STRICT is not specified, \p nodeset is set to the
union of all NUMA node(s) containing pages in the address range.
If all pages in the target have the same policy, it is returned in
\p policy.  Otherwise, \p policy is set to ::HWLOC_MEMBIND_MIXED.

If any other flags are specified, -1 is returned and errno is set
to EINVAL.


refid: gaf75f365807447cfdc73e4e04e3469d84
name: hwloc_get_area_membind
definition: int hwloc_get_area_membind
type: int
argsstring:
(hwloc_topology_t topology, const void *addr, size_t len, hwloc_cpuset_t cpuset, hwloc_membind_policy_t *policy, int flags)

detaileddescription:
This function has two output parameters: \p cpuset and \p policy.
The values returned in these parameters depend on both the \p flags
passed in and the memory binding policies and nodesets of the pages
in the address range.

If ::HWLOC_MEMBIND_STRICT is specified, the target pages are first
checked to see if they all have the same memory binding policy and
nodeset.  If they do not, -1 is returned and errno is set to EXDEV.
If they are identical across all pages, the policy is returned in
\p policy.  \p cpuset is set to the union of CPUs near the NUMA
node(s) in the nodeset.

If ::HWLOC_MEMBIND_STRICT is not specified, the union of all NUMA
node(s) containing pages in the address range is calculated.  \p
cpuset is then set to the CPUs near the NUMA node(s) in this union.
If all pages in the target have the same policy, it is returned in
\p policy.  Otherwise, \p policy is set to ::HWLOC_MEMBIND_MIXED.

If any other flags are specified, -1 is returned and errno is set
to EINVAL.

briefdescription:
Query the CPUs near the physical NUMA node(s) and binding policy of
the memory identified by (\p addr, \p len ).


refid: ga972b335a86a7d5e7b34bce2b243c41bc
name: hwloc_alloc
definition: void* hwloc_alloc
type: void *
argsstring: (hwloc_topology_t topology, size_t len)
briefdescription: Allocate some memory.
detaileddescription:
This is equivalent to malloc(), except that it tries to allocate
page-aligned memory from the OS.

\note The allocated memory should be freed with hwloc_free().


refid: ga0ff3076f7f3633637699b809bcceceb1
name: hwloc_alloc_membind_nodeset
definition: void* hwloc_alloc_membind_nodeset
type: void *
briefdescription: Allocate some memory on the given physical nodeset \p nodeset.
argsstring:
(hwloc_topology_t topology, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags)

detaileddescription:
\return NULL with errno set to ENOSYS if the action is not supported
and ::HWLOC_MEMBIND_STRICT is given
\return NULL with errno set to EXDEV if the binding cannot be enforced
and ::HWLOC_MEMBIND_STRICT is given
\return NULL with errno set to ENOMEM if the memory allocation failed
even before trying to bind.

\note The allocated memory should be freed with hwloc_free().


refid: ga1058b0b9216bc6fd9c3734ea9dca1e54
name: hwloc_alloc_membind
definition: void* hwloc_alloc_membind
type: void *
briefdescription: Allocate some memory on memory nodes near the given physical cpuset \p cpuset.
argsstring:
(hwloc_topology_t topology, size_t len, hwloc_const_cpuset_t cpuset, hwloc_membind_policy_t policy, int flags)

detaileddescription:
\return NULL with errno set to ENOSYS if the action is not supported
and ::HWLOC_MEMBIND_STRICT is given
\return NULL with errno set to EXDEV if the binding cannot be enforced
and ::HWLOC_MEMBIND_STRICT is given
\return NULL with errno set to ENOMEM if the memory allocation failed
even before trying to bind.

\note The allocated memory should be freed with hwloc_free().


refid: ga7d473e80f11d774421688e36e9926136
name: hwloc_alloc_membind_policy_nodeset
definition: static void* hwloc_alloc_membind_policy_nodeset
type: void *
briefdescription: Allocate some memory on the given nodeset \p nodeset.
argsstring:
(hwloc_topology_t topology, size_t len, hwloc_const_nodeset_t nodeset, hwloc_membind_policy_t policy, int flags)

detaileddescription:
This is similar to hwloc_alloc_membind except that it is allowed to change
the current memory binding policy, thus providing more binding support, at
the expense of changing the current state.


refid: ga4f7240065719cf923eb0cc078afcdcc2
name: hwloc_alloc_membind_policy
definition: static void* hwloc_alloc_membind_policy
type: void *
detaileddescription: This is similar to hwloc_alloc_membind_policy_nodeset, but for a given cpuset.
briefdescription: Allocate some memory on the memory nodes near given cpuset \p cpuset.
argsstring:
(hwloc_topology_t topology, size_t len, hwloc_const_cpuset_t set, hwloc_membind_policy_t policy, int flags)


refid: ga77c753751f3b90fac14117523fe604df
name: hwloc_topology_insert_misc_object_by_cpuset
definition: hwloc_obj_t hwloc_topology_insert_misc_object_by_cpuset
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, const char *name)
briefdescription: Add a MISC object to the topology.
detaileddescription:
A new MISC object will be created and inserted into the topology at the
position given by bitmap \p cpuset. This offers a way to add new
intermediate levels to the topology hierarchy.

\p cpuset and \p name will be copied to setup the new object attributes.

\return the newly-created object.
\return \c NULL if the insertion conflicts with the existing topology tree.

\note If \p name contains some non-printable characters, they will
be dropped when exporting to XML, see hwloc_topology_export_xml().


refid: ga1472cdf93327dfff4b5b2aedfde29cf3
name: hwloc_topology_insert_misc_object_by_parent
definition: hwloc_obj_t hwloc_topology_insert_misc_object_by_parent
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, hwloc_obj_t parent, const char *name)
briefdescription: Add a MISC object as a leaf of the topology.
detaileddescription:
A new MISC object will be created and inserted into the topology at the
position given by parent. It is appended to the list of existing children,
without ever adding any intermediate hierarchy level. This is useful for
annotating the topology without actually changing the hierarchy.

\p name will be copied to the setup the new object attributes.
However, the new leaf object will not have any \p cpuset.

\return the newly-created object

\note If \p name contains some non-printable characters, they will
be dropped when exporting to XML, see hwloc_topology_export_xml().


refid: gaffdb5403e5178b0d29852dd3319de3fc
name: hwloc_topology_restrict
definition: int hwloc_topology_restrict
type: int
argsstring: (hwloc_topology_t restrict topology, hwloc_const_cpuset_t cpuset, unsigned long flags)
briefdescription: Restrict the topology to the given CPU set.
detaileddescription:
Topology \p topology is modified so as to remove all objects that
are not included (or partially included) in the CPU set \p cpuset.
All objects CPU and node sets are restricted accordingly.

\p flags is a OR'ed set of ::hwloc_restrict_flags_e.

\note This call may not be reverted by restricting back to a larger
cpuset. Once dropped during restriction, objects may not be brought
back, except by loading another topology with hwloc_topology_load().

\return 0 on success.

\return -1 with errno set to EINVAL if the input cpuset is invalid.
The topology is not modified in this case.

\return -1 with errno set to ENOMEM on failure to allocate internal data.
The topology is reinitialized in this case. It should be either
destroyed with hwloc_topology_destroy() or configured and loaded again.


refid: ga62a161fc5e6f120344dc69a7bee4e587
name: hwloc_topology_dup
definition: int hwloc_topology_dup
type: int
argsstring: (hwloc_topology_t *newtopology, hwloc_topology_t oldtopology)
briefdescription: Duplicate a topology.
detaileddescription:
The entire topology structure as well as its objects
are duplicated into a new one.

This is useful for keeping a backup while modifying a topology.


refid: ga58220f648a972140865d11940bccec81
name: hwloc_custom_insert_topology
definition: int hwloc_custom_insert_topology
type: int
briefdescription: Insert an existing topology inside a custom topology.
argsstring:
(hwloc_topology_t newtopology, hwloc_obj_t newparent, hwloc_topology_t oldtopology, hwloc_obj_t oldroot)

detaileddescription:
Duplicate the existing topology \p oldtopology inside a new
custom topology \p newtopology as a leaf of object \p newparent.

If \p oldroot is not \c NULL, duplicate \p oldroot and all its
children instead of the entire \p oldtopology. Passing the root
object of \p oldtopology in \p oldroot is equivalent to passing
\c NULL.

The custom topology \p newtopology must have been prepared with
hwloc_topology_set_custom() and not loaded with hwloc_topology_load()
yet.

\p newparent may be either the root of \p newtopology or an object
that was added through hwloc_custom_insert_group_object_by_parent().

\note The cpuset and nodeset of the \p newparent object are not
modified based on the contents of \p oldtopology.


refid: ga60c404d4f0544e1070f549af8be6bd73
name: hwloc_custom_insert_group_object_by_parent
definition: hwloc_obj_t hwloc_custom_insert_group_object_by_parent
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, hwloc_obj_t parent, int groupdepth)
briefdescription: Insert a new group object inside a custom topology.
detaileddescription:
An object with type ::HWLOC_OBJ_GROUP is inserted as a new child
of object \p parent.

\p groupdepth is the depth attribute to be given to the new object.
It may for instance be 0 for top-level groups, 1 for their children,
and so on.

The custom topology \p newtopology must have been prepared with
hwloc_topology_set_custom() and not loaded with hwloc_topology_load()
yet.

\p parent may be either the root of \p topology or an object that
was added earlier through hwloc_custom_insert_group_object_by_parent().

\note The cpuset and nodeset of the new group object are NULL because
these sets are meaningless when assembling multiple topologies.

\note The cpuset and nodeset of the \p parent object are not modified.


refid: ga2bf166eda4d3605362ac86f77684002a
name: hwloc_topology_export_xml
definition: int hwloc_topology_export_xml
type: int
argsstring: (hwloc_topology_t topology, const char *xmlpath)
briefdescription: Export the topology into an XML file.
detaileddescription:
This file may be loaded later through hwloc_topology_set_xml().

\return -1 if a failure occured.

\note See also hwloc_topology_set_userdata_export_callback()
for exporting application-specific object userdata.

\note The topology-specific userdata pointer is ignored when exporting to XML.

\note Only printable characters may be exported to XML string attributes.
Any other character, especially any non-ASCII character, will be silently
dropped.

\note If \p name is "-", the XML output is sent to the standard output.


refid: ga7cbf8a2d8579d192911007650366fc8a
name: hwloc_topology_export_xmlbuffer
definition: int hwloc_topology_export_xmlbuffer
type: int
argsstring: (hwloc_topology_t topology, char **xmlbuffer, int *buflen)
briefdescription: Export the topology into a newly-allocated XML memory buffer.
detaileddescription:
\p xmlbuffer is allocated by the callee and should be freed with
hwloc_free_xmlbuffer() later in the caller.

This memory buffer may be loaded later through hwloc_topology_set_xmlbuffer().

\return -1 if a failure occured.

\note See also hwloc_topology_set_userdata_export_callback()
for exporting application-specific object userdata.

\note The topology-specific userdata pointer is ignored when exporting to XML.

\note Only printable characters may be exported to XML string attributes.
Any other character, especially any non-ASCII character, will be silently
dropped.


refid: ga9d6ff0f7a8dd45be9aa8575ef31978cc
name: hwloc_topology_set_userdata_export_callback
definition: void hwloc_topology_set_userdata_export_callback
type: void
briefdescription: Set the application-specific callback for exporting object userdata.
argsstring:
(hwloc_topology_t topology, void(*export_cb)(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj))

detaileddescription:
The object userdata pointer is not exported to XML by default because hwloc
does not know what it contains.

This function lets applications set \p export_cb to a callback function
that converts this opaque userdata into an exportable string.

\p export_cb is invoked during XML export for each object whose
\p userdata pointer is not \c NULL.
The callback should use hwloc_export_obj_userdata() or
hwloc_export_obj_userdata_base64() to actually export
something to XML (possibly multiple times per object).

\p export_cb may be set to \c NULL if userdata should not be exported to XML.

\note The topology-specific userdata pointer is ignored when exporting to XML.


refid: gaa541bdd628416dbbe97d0df69d3de958
name: hwloc_export_obj_userdata
definition: int hwloc_export_obj_userdata
type: int
briefdescription: Export some object userdata to XML.
argsstring:
(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length)

detaileddescription:
This function may only be called from within the export() callback passed
to hwloc_topology_set_userdata_export_callback().
It may be invoked one of multiple times to export some userdata to XML.
The \p buffer content of length \p length is stored with optional name
\p name.

When importing this XML file, the import() callback (if set) will be
called exactly as many times as hwloc_export_obj_userdata() was called
during export(). It will receive the corresponding \p name, \p buffer
and \p length arguments.

\p reserved, \p topology and \p obj must be the first three parameters
that were given to the export callback.

Only printable characters may be exported to XML string attributes.
If a non-printable character is passed in \p name or \p buffer,
the function returns -1 with errno set to EINVAL.

If exporting binary data, the application should first encode into
printable characters only (or use hwloc_export_obj_userdata_base64()).
It should also take care of portability issues if the export may
be reimported on a different architecture.


refid: ga1b7358137cec27bd073f58a606ecbaba
name: hwloc_export_obj_userdata_base64
definition: int hwloc_export_obj_userdata_base64
type: int
briefdescription: Encode and export some object userdata to XML.
argsstring:
(void *reserved, hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length)

detaileddescription:
This function is similar to hwloc_export_obj_userdata() but it encodes
the input buffer into printable characters before exporting.
On import, decoding is automatically performed before the data is given
to the import() callback if any.

This function may only be called from within the export() callback passed
to hwloc_topology_set_userdata_export_callback().

The function does not take care of portability issues if the export
may be reimported on a different architecture.


refid: ga5ac6917ea7289955fb1ffda4353af9b0
name: hwloc_topology_set_userdata_import_callback
definition: void hwloc_topology_set_userdata_import_callback
type: void
briefdescription: Set the application-specific callback for importing userdata.
argsstring:
(hwloc_topology_t topology, void(*import_cb)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length))

detaileddescription:
On XML import, userdata is ignored by default because hwloc does not know
how to store it in memory.

This function lets applications set \p import_cb to a callback function
that will get the XML-stored userdata and store it in the object as expected
by the application.

\p import_cb is called during hwloc_topology_load() as many times as
hwloc_export_obj_userdata() was called during export. The topology
is not entirely setup yet. Object attributes are ready to consult,
but links between objects are not.

\p import_cb may be \c NULL if userdata should be ignored during import.

\note \p buffer contains \p length characters followed by a null byte ('\0').

\note This function should be called before hwloc_topology_load().

\note The topology-specific userdata pointer is ignored when importing from XML.


refid: ga24b7864a1c588309c4749f621f03b4c7
name: hwloc_topology_export_synthetic
definition: int hwloc_topology_export_synthetic
type: int
argsstring: (hwloc_topology_t topology, char *buffer, size_t buflen, unsigned long flags)
briefdescription: Export the topology as a synthetic string.
detaileddescription:
At most \p buflen characters will be written in \p buffer,
including the terminating \0.

This exported string may be given back to hwloc_topology_set_synthetic().

\p flags is a OR'ed set of hwloc_topology_export_synthetic_flags_e.

\return The number of characters that were written,
not including the terminating \0.

\return -1 if the topology could not be exported,
for instance if it is not symmetric.

\note A 1024-byte buffer should be large enough for exporting
topologies in the vast majority of cases.


refid: ga91bafa51abe81527f72437e24ad5944e
name: hwloc_intel_mic_get_device_cpuset
definition: static int hwloc_intel_mic_get_device_cpuset
type: int
argsstring: (hwloc_topology_t topology, int idx, hwloc_cpuset_t set)
detaileddescription:
Return the CPU set describing the locality of the MIC device whose index is \p idx.

Topology \p topology and device index \p idx must match the local machine.
I/O devices detection is not needed in the topology.

The function only returns the locality of the device.
If more information about the device is needed, OS objects should
be used instead, see hwloc_intel_mic_get_device_osdev_by_index().

This function is currently only implemented in a meaningful way for
Linux; other systems will simply get a full cpuset.

briefdescription:
Get the CPU set of logical processors that are physically
close to MIC device whose index is \p idx.


refid: gabce0465e853de74be84cafcb96dd48ab
name: hwloc_intel_mic_get_device_osdev_by_index
definition: static hwloc_obj_t hwloc_intel_mic_get_device_osdev_by_index
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, unsigned idx)
briefdescription: Get the hwloc OS device object corresponding to the MIC device for the given index.
detaileddescription:
Return the OS device object describing the MIC device whose index is \p idx.
Return NULL if there is none.

The topology \p topology does not necessarily have to match the current
machine. For instance the topology may be an XML import of a remote host.
I/O devices detection must be enabled in the topology.

\note The corresponding PCI device object can be obtained by looking
at the OS device parent object.


refid: gae577962390f84b0b12f503314ab0f972
name: hwloc_cpuset_to_linux_libnuma_ulongs
definition: static int hwloc_cpuset_to_linux_libnuma_ulongs
type: int
briefdescription: Convert hwloc CPU set \p cpuset into the array of unsigned long \p mask.
argsstring:
(hwloc_topology_t topology, hwloc_const_cpuset_t cpuset, unsigned long *mask, unsigned long *maxnode)

detaileddescription:
\p mask is the array of unsigned long that will be filled.
\p maxnode contains the maximal node number that may be stored in \p mask.
\p maxnode will be set to the maximal node number that was found, plus one.

This function may be used before calling set_mempolicy, mbind, migrate_pages
or any other function that takes an array of unsigned long and a maximal
node number as input parameter.


refid: ga585ccf818d2f217f4e53f9c6506c3128
name: hwloc_nodeset_to_linux_libnuma_ulongs
definition: static int hwloc_nodeset_to_linux_libnuma_ulongs
type: int
briefdescription: Convert hwloc NUMA node set \p nodeset into the array of unsigned long \p mask.
argsstring:
(hwloc_topology_t topology, hwloc_const_nodeset_t nodeset, unsigned long *mask, unsigned long *maxnode)

detaileddescription:
\p mask is the array of unsigned long that will be filled.
\p maxnode contains the maximal node number that may be stored in \p mask.
\p maxnode will be set to the maximal node number that was found, plus one.

This function may be used before calling set_mempolicy, mbind, migrate_pages
or any other function that takes an array of unsigned long and a maximal
node number as input parameter.


refid: ga0e9d051e068940f722f6fdc61814149d
name: hwloc_cpuset_from_linux_libnuma_ulongs
definition: static int hwloc_cpuset_from_linux_libnuma_ulongs
type: int
briefdescription: Convert the array of unsigned long \p mask into hwloc CPU set.
argsstring:
(hwloc_topology_t topology, hwloc_cpuset_t cpuset, const unsigned long *mask, unsigned long maxnode)

detaileddescription:
\p mask is a array of unsigned long that will be read.
\p maxnode contains the maximal node number that may be read in \p mask.

This function may be used after calling get_mempolicy or any other function
that takes an array of unsigned long as output parameter (and possibly
a maximal node number as input parameter).


refid: gad8491c672eb2594cc5e7b0a026867192
name: hwloc_nodeset_from_linux_libnuma_ulongs
definition: static int hwloc_nodeset_from_linux_libnuma_ulongs
type: int
briefdescription: Convert the array of unsigned long \p mask into hwloc NUMA node set.
argsstring:
(hwloc_topology_t topology, hwloc_nodeset_t nodeset, const unsigned long *mask, unsigned long maxnode)

detaileddescription:
\p mask is a array of unsigned long that will be read.
\p maxnode contains the maximal node number that may be read in \p mask.

This function may be used after calling get_mempolicy or any other function
that takes an array of unsigned long as output parameter (and possibly
a maximal node number as input parameter).


refid: gad8769b4544c0aeef154fc8223144e343
name: hwloc_cpuset_to_linux_libnuma_bitmask
definition: static struct bitmask * hwloc_cpuset_to_linux_libnuma_bitmask
type: struct bitmask *
argsstring: (hwloc_topology_t topology, hwloc_const_cpuset_t cpuset)
briefdescription: Convert hwloc CPU set \p cpuset into the returned libnuma bitmask.
detaileddescription:
The returned bitmask should later be freed with numa_bitmask_free.

This function may be used before calling many numa_ functions
that use a struct bitmask as an input parameter.

\return newly allocated struct bitmask.


refid: ga37c8421110b1842414809019098794ef
name: hwloc_cpuset_from_linux_libnuma_bitmask
definition: static int hwloc_cpuset_from_linux_libnuma_bitmask
type: int
argsstring: (hwloc_topology_t topology, hwloc_cpuset_t cpuset, const struct bitmask *bitmask)
briefdescription: Convert libnuma bitmask \p bitmask into hwloc CPU set \p cpuset.
detaileddescription:
This function may be used after calling many numa_ functions
that use a struct bitmask as an output parameter.


refid: gaa5a608236c3c0757b0b79818f1d429fb
name: hwloc_linux_parse_cpumap_file
definition: int hwloc_linux_parse_cpumap_file
type: int
argsstring: (FILE *file, hwloc_cpuset_t set)
briefdescription: Convert a linux kernel cpumap file \p file into hwloc CPU set.
detaileddescription:
Might be used when reading CPU set from sysfs attributes such as topology
and caches for processors, or local_cpus for devices.


refid: ga630e699c56b5f3d2e534b475944c216e
name: hwloc_linux_set_tid_cpubind
definition: int hwloc_linux_set_tid_cpubind
type: int
argsstring: (hwloc_topology_t topology, pid_t tid, hwloc_const_cpuset_t set)
briefdescription: Bind a thread \p tid on cpus given in cpuset \p set.
detaileddescription:
The behavior is exactly the same as the Linux sched_setaffinity system call,
but uses a hwloc cpuset.

\note This is equivalent to calling hwloc_set_proc_cpubind() with
HWLOC_CPUBIND_THREAD as flags.


refid: gaddcb985cb56337a4d6693cee72e7bf94
name: hwloc_linux_get_tid_cpubind
definition: int hwloc_linux_get_tid_cpubind
type: int
argsstring: (hwloc_topology_t topology, pid_t tid, hwloc_cpuset_t set)
briefdescription: Get the current binding of thread \p tid.
detaileddescription:
The behavior is exactly the same as the Linux sched_getaffinity system call,
but uses a hwloc cpuset.

\note This is equivalent to calling hwloc_get_proc_cpubind() with
HWLOC_CPUBIND_THREAD as flags.


refid: gacc7945c2d06c6db1e58f8fd953009134
name: hwloc_linux_get_tid_last_cpu_location
definition: int hwloc_linux_get_tid_last_cpu_location
type: int
argsstring: (hwloc_topology_t topology, pid_t tid, hwloc_bitmap_t set)
briefdescription: Get the last physical CPU where thread \p tid ran.
detaileddescription:
\note This is equivalent to calling hwloc_get_proc_last_cpu_location() with
HWLOC_CPUBIND_THREAD as flags.


refid: ga868dfb8232333858e1e159c62ff9b682
name: hwloc_mx_board_get_device_cpuset
definition: static int hwloc_mx_board_get_device_cpuset
type: int
argsstring: (hwloc_topology_t topology, unsigned id, hwloc_cpuset_t set)
briefdescription: Get the CPU set of logical processors that are physically close the MX board \p id.
detaileddescription:
Return the CPU set describing the locality of the Myrinet Express
board whose index is \p id.

Topology \p topology and device \p id must match the local machine.
I/O devices detection is not needed in the topology.

The function only returns the locality of the device.
No additional information about the device is available.


refid: ga1d01f76cdd4a408ad01f105deeef3bba
name: hwloc_mx_endpoint_get_device_cpuset
definition: static int hwloc_mx_endpoint_get_device_cpuset
type: int
argsstring: (hwloc_topology_t topology, mx_endpoint_t endpoint, hwloc_cpuset_t set)
briefdescription: Get the CPU set of logical processors that are physically close the MX endpoint \p endpoint.
detaileddescription:
Return the CPU set describing the locality of the Myrinet Express
board that runs the MX endpoint \p endpoint.

Topology \p topology and device \p id must match the local machine.
I/O devices detection is not needed in the topology.

The function only returns the locality of the endpoint.
No additional information about the endpoint or device is available.


refid: ga26cf0036d09ec4d7cb692380fac9659d
name: hwloc_nvml_get_device_cpuset
definition: static int hwloc_nvml_get_device_cpuset
type: int
argsstring: (hwloc_topology_t topology, nvmlDevice_t device, hwloc_cpuset_t set)
briefdescription: Get the CPU set of logical processors that are physically close to NVML device \p device.
detaileddescription:
Return the CPU set describing the locality of the NVML device \p device.

Topology \p topology and device \p device must match the local machine.
I/O devices detection and the NVML component are not needed in the topology.

The function only returns the locality of the device.
If more information about the device is needed, OS objects should
be used instead, see hwloc_nvml_get_device_osdev()
and hwloc_nvml_get_device_osdev_by_index().

This function is currently only implemented in a meaningful way for
Linux; other systems will simply get a full cpuset.


refid: gacd50fd0e2766ee05bc13234b46714756
name: hwloc_nvml_get_device_osdev_by_index
definition: static hwloc_obj_t hwloc_nvml_get_device_osdev_by_index
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, unsigned idx)
briefdescription: Get the hwloc OS device object corresponding to the NVML device whose index is \p idx.
detaileddescription:
Return the OS device object describing the NVML device whose
index is \p idx. Returns NULL if there is none.

The topology \p topology does not necessarily have to match the current
machine. For instance the topology may be an XML import of a remote host.
I/O devices detection and the NVML component must be enabled in the topology.

\note The corresponding PCI device object can be obtained by looking
at the OS device parent object.


refid: gaf176159b5760a191871eff23f5a69ee9
name: hwloc_nvml_get_device_osdev
definition: static hwloc_obj_t hwloc_nvml_get_device_osdev
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, nvmlDevice_t device)
briefdescription: Get the hwloc OS device object corresponding to NVML device \p device.
detaileddescription:
Return the hwloc OS device object that describes the given
NVML device \p device. Return NULL if there is none.

Topology \p topology and device \p device must match the local machine.
I/O devices detection and the NVML component must be enabled in the topology.
If not, the locality of the object may still be found using
hwloc_nvml_get_device_cpuset().

\note The corresponding hwloc PCI device may be found by looking
at the result parent pointer.


refid: gacc32737d4648d16b0d292438f210ec90
name: hwloc_opencl_get_device_cpuset
definition: static int hwloc_opencl_get_device_cpuset
type: int
argsstring: (hwloc_topology_t topology, cl_device_id device, hwloc_cpuset_t set)
briefdescription: Get the CPU set of logical processors that are physically close to OpenCL device \p device.
detaileddescription:
Return the CPU set describing the locality of the OpenCL device \p device.

Topology \p topology and device \p device must match the local machine.
I/O devices detection and the OpenCL component are not needed in the topology.

The function only returns the locality of the device.
If more information about the device is needed, OS objects should
be used instead, see hwloc_opencl_get_device_osdev()
and hwloc_opencl_get_device_osdev_by_index().

This function is currently only implemented in a meaningful way for
Linux with the AMD OpenCL implementation; other systems will simply
get a full cpuset.


refid: gae39352d124cb330eb37b84b418ed6cc5
name: hwloc_opencl_get_device_osdev_by_index
definition: static hwloc_obj_t hwloc_opencl_get_device_osdev_by_index
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, unsigned platform_index, unsigned device_index)
briefdescription: Get the hwloc OS device object corresponding to the OpenCL device for the given indexes.
detaileddescription:
Return the OS device object describing the OpenCL device
whose platform index is \p platform_index,
and whose device index within this platform if \p device_index.
Return NULL if there is none.

The topology \p topology does not necessarily have to match the current
machine. For instance the topology may be an XML import of a remote host.
I/O devices detection and the OpenCL component must be enabled in the topology.

\note The corresponding PCI device object can be obtained by looking
at the OS device parent object.


refid: gadabfa6516aa12e5d8f79b9b4dd9f3cf8
name: hwloc_opencl_get_device_osdev
definition: static hwloc_obj_t hwloc_opencl_get_device_osdev
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, cl_device_id device)
briefdescription: Get the hwloc OS device object corresponding to OpenCL device \p device.
detaileddescription:
Return the hwloc OS device object that describes the given
OpenCL device \p device. Return NULL if there is none.

Topology \p topology and device \p device must match the local machine.
I/O devices detection and the OpenCL component must be enabled in the topology.
If not, the locality of the object may still be found using
hwloc_opencl_get_device_cpuset().

\note The corresponding hwloc PCI device may be found by looking
at the result parent pointer.


refid: ga3ea0d838c1e7f1671b35687aae2da6ae
name: hwloc_ibv_get_device_cpuset
definition: static int hwloc_ibv_get_device_cpuset
type: int
argsstring: (hwloc_topology_t topology, struct ibv_device *ibdev, hwloc_cpuset_t set)
briefdescription: Get the CPU set of logical processors that are physically close to device \p ibdev.
detaileddescription:
Return the CPU set describing the locality of the OpenFabrics
device \p ibdev.

Topology \p topology and device \p ibdev must match the local machine.
I/O devices detection is not needed in the topology.

The function only returns the locality of the device.
If more information about the device is needed, OS objects should
be used instead, see hwloc_ibv_get_device_osdev()
and hwloc_ibv_get_device_osdev_by_name().

This function is currently only implemented in a meaningful way for
Linux; other systems will simply get a full cpuset.


refid: ga31d794567f4420bbdc8baa7bf8bf6138
name: hwloc_ibv_get_device_osdev_by_name
definition: static hwloc_obj_t hwloc_ibv_get_device_osdev_by_name
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, const char *ibname)
briefdescription: Get the hwloc OS device object corresponding to the OpenFabrics device named \p ibname.
detaileddescription:
Return the OS device object describing the OpenFabrics device whose
name is \p ibname. Returns NULL if there is none.
The name \p ibname is usually obtained from ibv_get_device_name().

The topology \p topology does not necessarily have to match the current
machine. For instance the topology may be an XML import of a remote host.
I/O devices detection must be enabled in the topology.

\note The corresponding PCI device object can be obtained by looking
at the OS device parent object.


refid: ga7324cdfd5db6ed2669c051ef7e1b64e1
name: hwloc_ibv_get_device_osdev
definition: static hwloc_obj_t hwloc_ibv_get_device_osdev
type: hwloc_obj_t
argsstring: (hwloc_topology_t topology, struct ibv_device *ibdev)
briefdescription: Get the hwloc OS device object corresponding to the OpenFabrics device \p ibdev.
detaileddescription:
Return the OS device object describing the OpenFabrics device \p ibdev.
Returns NULL if there is none.

Topology \p topology and device \p ibdev must match the local machine.
I/O devices detection must be enabled in the topology.
If not, the locality of the object may still be found using
hwloc_ibv_get_device_cpuset().

\note The corresponding PCI device object can be obtained by looking
at the OS device parent object.


refid: ga330a0b581de4817d0cf1e7401db22436
name: hwloc_backend_alloc
definition: struct hwloc_backend* hwloc_backend_alloc
type: struct hwloc_backend *
argsstring: (struct hwloc_disc_component *component)
briefdescription:
Allocate a backend structure, set good default values, initialize backend->component and topology, etc.
The caller will then modify whatever needed, and call hwloc_backend_enable().


refid: gad8ac8bba9ab6b9af423baba0c8337c6b
name: hwloc_backends_notify_new_object
definition: int hwloc_backends_notify_new_object
type: int
argsstring: (struct hwloc_backend *caller, struct hwloc_obj *obj)
briefdescription: Used by backends discovery callbacks to notify other backends of new objects.
detaileddescription:
Traverse the list of enabled backends (all but caller) and invoke
their notify_new_object() method to notify them that a new object
just got added to the topology.

Currently only used for notifying of new PCI device objects.


refid: gafd853fd67e12c32916201d8303ef39d2
name: hwloc_insert_object_by_cpuset
definition: struct hwloc_obj* hwloc_insert_object_by_cpuset
type: struct hwloc_obj *
argsstring: (struct hwloc_topology *topology, hwloc_obj_t obj)
briefdescription: Add an object to the topology.
detaileddescription:
It is sorted along the tree of other objects according to the inclusion of
cpusets, to eventually be added as a child of the smallest object including
this object.

If the cpuset is empty, the type of the object (and maybe some attributes)
must be enough to find where to insert the object. This is especially true
for NUMA nodes with memory and no CPUs.

The given object should not have children.

This shall only be called before levels are built.

In case of error, hwloc_report_os_error() is called.

Returns the object on success.
Returns NULL and frees obj on error.
Returns another object and frees obj if it was merged with an identical pre-existing object.


refid: ga56d4e5fec377bf09f136b4e8e280e30f
name: hwloc__insert_object_by_cpuset
definition: struct hwloc_obj* hwloc__insert_object_by_cpuset
type: struct hwloc_obj *
argsstring: (struct hwloc_topology *topology, hwloc_obj_t obj, hwloc_report_error_t report_error)
briefdescription: Add an object to the topology and specify which error callback to use.
detaileddescription:
Aside from the error callback selection, this function is identical to hwloc_insert_object_by_cpuset()


refid: ga0ef97debde503b56367689b07bb3e901
name: hwloc_insert_object_by_parent
definition: void hwloc_insert_object_by_parent
type: void
argsstring: (struct hwloc_topology *topology, hwloc_obj_t parent, hwloc_obj_t obj)
briefdescription: Insert an object somewhere in the topology.
detaileddescription:
It is added as the last child of the given parent.
The cpuset is completely ignored, so strange objects such as I/O devices should
preferably be inserted with this.

The given object may have children.

Remember to call topology_connect() afterwards to fix handy pointers.


refid: gabb240e5b856a34963078ccec9a785ac1
name: hwloc_fill_object_sets
definition: int hwloc_fill_object_sets
type: int
argsstring: (hwloc_obj_t obj)
briefdescription: Setup object cpusets/nodesets by OR'ing its children.
detaileddescription:
Used when adding an object late in the topology, after propagating sets up and down.
The caller should use this after inserting by cpuset (which means the cpusets is already OK).
Typical case: PCI backend adding a hostbridge parent.


refid: gac2eaed287bb215cf0bd33014e9e1d374
name: hwloc_plugin_check_namespace
definition: static int hwloc_plugin_check_namespace
type: int
argsstring: (const char *pluginname, const char *symbol)
briefdescription: Make sure that plugins can lookup core symbols.
detaileddescription:
This is a sanity check to avoid lazy-lookup failures when libhwloc
is loaded within a plugin, and later tries to load its own plugins.
This may fail (and abort the program) if libhwloc symbols are in a
private namespace.

\return 0 on success.
\return -1 if the plugin cannot be successfully loaded. The caller
plugin init() callback should return a negative error code as well.

Plugins should call this function in their init() callback to avoid
later crashes if lazy symbol resolution is used by the upper layer that
loaded hwloc (e.g. OpenCL implementations using dlopen with RTLD_LAZY).

\note The build system must define HWLOC_INSIDE_PLUGIN if and only if
building the caller as a plugin.

\note This function should remain inline so plugins can call it even
when they cannot find libhwloc symbols.


refid: ga2ea3e9c02eabd8c5768745c8a99d7fed
name: hwloc_insert_pci_device_list
definition: int hwloc_insert_pci_device_list
type: int
argsstring: (struct hwloc_backend *backend, struct hwloc_obj *first_obj)
briefdescription: Insert a list of PCI devices and bridges in the backend topology.
detaileddescription:
Insert a list of objects (either PCI device or bridges) starting at first_obj
(linked by next_sibling in the topology, and ending with NULL).
Objects are placed under the right bridges, and the remaining upstream bridges
are then inserted in the topology by calling the get_obj_cpuset() callback to
find their locality.


refid: ga749e75eeea108be0608fcba7c113f736
name: hwloc_pci_find_linkspeed
definition: int hwloc_pci_find_linkspeed
type: int
argsstring: (const unsigned char *config, unsigned offset, float *linkspeed)
briefdescription: Fill linkspeed by reading the PCI config space where PCI_CAP_ID_EXP is at position offset.
detaileddescription:
Needs 20 bytes of EXP capability block starting at offset in the config space
for registers up to link status.


refid: ga80fa1e3d882b5c2225dd6dd01e098ad0
name: hwloc_pci_prepare_bridge
definition: int hwloc_pci_prepare_bridge
type: int
argsstring: (hwloc_obj_t obj, const unsigned char *config)
detaileddescription: This function requires 64 bytes of common configuration header at the beginning of config.
briefdescription:
Modify the PCI device object into a bridge and fill its attribute if a bridge is found in the PCI config space.


# params

declname: import_cb
type:
void(*)(hwloc_topology_t topology, hwloc_obj_t obj, const char *name, const void *buffer, size_t length)


