1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
.TH "hwlocality_components_core_funcs" 3 "Thu Feb 11 2021" "Version 2.4.1" "Hardware Locality (hwloc)" \" -*- nroff -*-
.ad l
.nh
.SH NAME
hwlocality_components_core_funcs \- Components and Plugins: Core functions to be used by components
.SH SYNOPSIS
.br
.PP
.SS "Functions"
.in +1c
.ti -1c
.RI "int \fBhwloc_hide_errors\fP (void)"
.br
.ti -1c
.RI "\fBhwloc_obj_t\fP \fBhwloc__insert_object_by_cpuset\fP (struct hwloc_topology *topology, \fBhwloc_obj_t\fP root, \fBhwloc_obj_t\fP obj, const char *reason)"
.br
.ti -1c
.RI "void \fBhwloc_insert_object_by_parent\fP (struct hwloc_topology *topology, \fBhwloc_obj_t\fP parent, \fBhwloc_obj_t\fP obj)"
.br
.ti -1c
.RI "\fBhwloc_obj_t\fP \fBhwloc_alloc_setup_object\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_obj_type_t\fP type, unsigned os_index)"
.br
.ti -1c
.RI "int \fBhwloc_obj_add_children_sets\fP (\fBhwloc_obj_t\fP obj)"
.br
.ti -1c
.RI "int \fBhwloc_topology_reconnect\fP (\fBhwloc_topology_t\fP topology, unsigned long flags)"
.br
.ti -1c
.RI "static int \fBhwloc_plugin_check_namespace\fP (const char *pluginname, const char *symbol)"
.br
.in -1c
.SH "Detailed Description"
.PP
.SH "Function Documentation"
.PP
.SS "\fBhwloc_obj_t\fP hwloc__insert_object_by_cpuset (struct hwloc_topology * topology, \fBhwloc_obj_t\fP root, \fBhwloc_obj_t\fP obj, const char * reason)"
.PP
Add an object to the topology\&. Insert new object \fCobj\fP in the topology starting under existing object \fCroot\fP (if \fCNULL\fP, the topology root object is used)\&.
.PP
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\&.
.PP
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\&.
.PP
The given object should not have children\&.
.PP
This shall only be called before levels are built\&.
.PP
The caller should check whether the object type is filtered-out before calling this function\&.
.PP
The topology cpuset/nodesets will be enlarged to include the object sets\&.
.PP
\fCreason\fP is a unique string identifying where and why this insertion call was performed (it will be displayed in case of internal insertion error)\&.
.PP
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\&.
.SS "\fBhwloc_obj_t\fP hwloc_alloc_setup_object (\fBhwloc_topology_t\fP topology, \fBhwloc_obj_type_t\fP type, unsigned os_index)"
.PP
Allocate and initialize an object of the given type and physical index\&. If \fCos_index\fP is unknown or irrelevant, use \fCHWLOC_UNKNOWN_INDEX\fP\&.
.SS "int hwloc_hide_errors (void)"
.PP
Check whether insertion errors are hidden\&.
.SS "void hwloc_insert_object_by_parent (struct hwloc_topology * topology, \fBhwloc_obj_t\fP parent, \fBhwloc_obj_t\fP obj)"
.PP
Insert an object somewhere in the topology\&. 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\&.
.PP
When used for 'normal' children with cpusets (when importing from XML when duplicating a topology), the caller should make sure that:
.IP "\(bu" 2
children are inserted in order,
.IP "\(bu" 2
children cpusets do not intersect\&.
.PP
.PP
The given object may have normal, I/O or Misc children, as long as they are in order as well\&. These children must have valid parent and next_sibling pointers\&.
.PP
The caller should check whether the object type is filtered-out before calling this function\&.
.SS "int hwloc_obj_add_children_sets (\fBhwloc_obj_t\fP obj)"
.PP
Setup object cpusets/nodesets by OR'ing its children\&. Used when adding an object late in the topology\&. Will update the new object by OR'ing all its new children sets\&.
.PP
Used when PCI backend adds a hostbridge parent, when distances add a new Group, etc\&.
.SS "static int hwloc_plugin_check_namespace (const char * pluginname, const char * symbol)\fC [inline]\fP, \fC [static]\fP"
.PP
Make sure that plugins can lookup core symbols\&. 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\&.
.PP
\fBReturns\fP
.RS 4
0 on success\&.
.PP
-1 if the plugin cannot be successfully loaded\&. The caller plugin init() callback should return a negative error code as well\&.
.RE
.PP
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)\&.
.PP
\fBNote\fP
.RS 4
The build system must define HWLOC_INSIDE_PLUGIN if and only if building the caller as a plugin\&.
.PP
This function should remain inline so plugins can call it even when they cannot find libhwloc symbols\&.
.RE
.PP
.SS "int hwloc_topology_reconnect (\fBhwloc_topology_t\fP topology, unsigned long flags)"
.PP
Request a reconnection of children and levels in the topology\&. May be used by backends during discovery if they need arrays or lists of object within levels or children to be fully connected\&.
.PP
\fCflags\fP is currently unused, must 0\&.
.SH "Author"
.PP
Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.
|
