Debian Codegraph @

doc/doxygen-doc/man/man3/hwlocality_distances_add.3

raw
1 .TH "hwlocality_distances_add" 3 "Version 2.14.0" "Hardware Locality (hwloc)" \" -*- nroff -*-
2 .ad l
3 .nh
4 .SH NAME
5 hwlocality_distances_add \- Add distances between objects
6 .SH SYNOPSIS
7 .br
8 .PP
9 .SS "Typedefs"
10
11 .in +1c
12 .ti -1c
13 .RI "typedef void * \fBhwloc_distances_add_handle_t\fP"
14 .br
15 .in -1c
16 .SS "Enumerations"
17
18 .in +1c
19 .ti -1c
20 .RI "enum \fBhwloc_distances_add_flag_e\fP { \fBHWLOC_DISTANCES_ADD_FLAG_GROUP\fP, \fBHWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE\fP }"
21 .br
22 .in -1c
23 .SS "Functions"
24
25 .in +1c
26 .ti -1c
27 .RI "\fBhwloc_distances_add_handle_t\fP \fBhwloc_distances_add_create\fP (\fBhwloc_topology_t\fP topology, const char *name, unsigned long kind, unsigned long flags)"
28 .br
29 .ti -1c
30 .RI "int \fBhwloc_distances_add_values\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_distances_add_handle_t\fP handle, unsigned nbobjs, \fBhwloc_obj_t\fP *objs, hwloc_uint64_t *values, unsigned long flags)"
31 .br
32 .ti -1c
33 .RI "int \fBhwloc_distances_add_commit\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_distances_add_handle_t\fP handle, unsigned long flags)"
34 .br
35 .in -1c
36 .SH "Detailed Description"
37 .PP
38 The usual way to add distances is:
39 .PP
40 .nf
41 hwloc_distances_add_handle_t handle;
42 int err = \-1;
43 handle = hwloc_distances_add_create(topology, "name", kind, 0);
44 if (handle) {
45 err = hwloc_distances_add_values(topology, handle, nbobjs, objs, values, 0);
46 if (!err)
47 err = hwloc_distances_add_commit(topology, handle, flags);
48 }
49
50 .fi
51 .PP
52 If \fRerr\fP is \fR0\fP at the end, then addition was successful\&.
53 .SH "Typedef Documentation"
54 .PP
55 .SS "typedef void* \fBhwloc_distances_add_handle_t\fP"
56
57 .PP
58 Handle to a new distances structure during its addition to the topology\&.
59 .SH "Enumeration Type Documentation"
60 .PP
61 .SS "enum \fBhwloc_distances_add_flag_e\fP"
62
63 .PP
64 Flags for adding a new distances to a topology\&.
65 .PP
66 \fBEnumerator\fP
67 .in +1c
68 .TP
69 \f(BIHWLOC_DISTANCES_ADD_FLAG_GROUP \fP
70 Try to group objects based on the newly provided distance information\&. Grouping is only performed when the distances structure contains latencies, and when all objects are of the same type\&.
71 .TP
72 \f(BIHWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE \fP
73 If grouping, consider the distance values as inaccurate and relax the comparisons during the grouping algorithms\&. The actual accuracy may be modified through the HWLOC_GROUPING_ACCURACY environment variable (see \fBEnvironment variables for tweaking hwloc heuristics\fP)\&.
74 .SH "Function Documentation"
75 .PP
76 .SS "int hwloc_distances_add_commit (\fBhwloc_topology_t\fP topology, \fBhwloc_distances_add_handle_t\fP handle, unsigned long flags)"
77
78 .PP
79 Commit a new distances structure\&. This function finalizes the distances structure and inserts in it the topology\&.
80
81 .PP
82 Parameter \fRhandle\fP was previously returned by \fBhwloc_distances_add_create()\fP\&. Then objects and values were specified with \fBhwloc_distances_add_values()\fP\&.
83
84 .PP
85 \fRflags\fP configures the behavior of the function using an optional OR'ed set of \fBhwloc_distances_add_flag_e\fP\&. It may be used to request the grouping of existing objects based on distances\&.
86
87 .PP
88 On error, the temporary distances structure and its content are destroyed\&.
89
90 .PP
91 \fBReturns\fP
92 .RS 4
93 0 on success\&.
94
95 .PP
96 -1 on error\&.
97 .RE
98 .PP
99
100 .SS "\fBhwloc_distances_add_handle_t\fP hwloc_distances_add_create (\fBhwloc_topology_t\fP topology, const char * name, unsigned long kind, unsigned long flags)"
101
102 .PP
103 Create a new empty distances structure\&. Create an empty distances structure to be filled with \fBhwloc_distances_add_values()\fP and then committed with \fBhwloc_distances_add_commit()\fP\&.
104
105 .PP
106 Parameter \fRname\fP is optional, it may be \fRNULL\fP\&. Otherwise, it will be copied internally and may later be freed by the caller\&.
107
108 .PP
109 \fRkind\fP specifies the kind of distance as a OR'ed set of \fBhwloc_distances_kind_e\fP\&. Only one kind of meaning and one kind of provenance may be given if appropriate (e\&.g\&. \fBHWLOC_DISTANCES_KIND_MEANS_BANDWIDTH\fP and \fBHWLOC_DISTANCES_KIND_FROM_USER\fP)\&. Kind \fBHWLOC_DISTANCES_KIND_HETEROGENEOUS_TYPES\fP will be automatically set according to objects having different types in \fBhwloc_distances_add_values()\fP\&.
110
111 .PP
112 \fRflags\fP must be \fR0\fP for now\&.
113
114 .PP
115 \fBReturns\fP
116 .RS 4
117 A \fBhwloc_distances_add_handle_t\fP that should then be passed to \fBhwloc_distances_add_values()\fP and \fBhwloc_distances_add_commit()\fP\&.
118
119 .PP
120 \fRNULL\fP on error\&.
121 .RE
122 .PP
123
124 .SS "int hwloc_distances_add_values (\fBhwloc_topology_t\fP topology, \fBhwloc_distances_add_handle_t\fP handle, unsigned nbobjs, \fBhwloc_obj_t\fP * objs, hwloc_uint64_t * values, unsigned long flags)"
125
126 .PP
127 Specify the objects and values in a new empty distances structure\&. Specify the objects and values for a new distances structure that was returned as a handle by \fBhwloc_distances_add_create()\fP\&. The structure must then be committed with \fBhwloc_distances_add_commit()\fP\&.
128
129 .PP
130 The number of objects is \fRnbobjs\fP and the array of objects is \fRobjs\fP\&. Distance values are stored as a one-dimension array in \fRvalues\fP\&. The distance from object i to object j is in slot i*nbobjs+j\&.
131
132 .PP
133 \fRnbobjs\fP must be at least 2\&.
134
135 .PP
136 Arrays \fRobjs\fP and \fRvalues\fP will be copied internally, they may later be freed by the caller\&.
137
138 .PP
139 On error, the temporary distances structure and its content are destroyed\&.
140
141 .PP
142 \fRflags\fP must be \fR0\fP for now\&.
143
144 .PP
145 \fBReturns\fP
146 .RS 4
147 0 on success\&.
148
149 .PP
150 -1 on error\&.
151 .RE
152 .PP
153
154 .SH "Author"
155 .PP
156 Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.