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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
|
.TH "hwlocality_distances_add" 3 "Version 2.12.0" "Hardware Locality (hwloc)" \" -*- nroff -*-
.ad l
.nh
.SH NAME
hwlocality_distances_add \- Add distances between objects
.SH SYNOPSIS
.br
.PP
.SS "Typedefs"
.in +1c
.ti -1c
.RI "typedef void * \fBhwloc_distances_add_handle_t\fP"
.br
.in -1c
.SS "Enumerations"
.in +1c
.ti -1c
.RI "enum \fBhwloc_distances_add_flag_e\fP { \fBHWLOC_DISTANCES_ADD_FLAG_GROUP\fP, \fBHWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE\fP }"
.br
.in -1c
.SS "Functions"
.in +1c
.ti -1c
.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)"
.br
.ti -1c
.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)"
.br
.ti -1c
.RI "int \fBhwloc_distances_add_commit\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_distances_add_handle_t\fP handle, unsigned long flags)"
.br
.in -1c
.SH "Detailed Description"
.PP
The usual way to add distances is:
.PP
.nf
hwloc_distances_add_handle_t handle;
int err = \-1;
handle = hwloc_distances_add_create(topology, "name", kind, 0);
if (handle) {
err = hwloc_distances_add_values(topology, handle, nbobjs, objs, values, 0);
if (!err)
err = hwloc_distances_add_commit(topology, handle, flags);
}
.fi
.PP
If \fCerr\fP is \fC0\fP at the end, then addition was successful\&.
.SH "Typedef Documentation"
.PP
.SS "typedef void* \fBhwloc_distances_add_handle_t\fP"
.PP
Handle to a new distances structure during its addition to the topology\&.
.SH "Enumeration Type Documentation"
.PP
.SS "enum \fBhwloc_distances_add_flag_e\fP"
.PP
Flags for adding a new distances to a topology\&.
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIHWLOC_DISTANCES_ADD_FLAG_GROUP \fP\fP
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\&.
.TP
\fB\fIHWLOC_DISTANCES_ADD_FLAG_GROUP_INACCURATE \fP\fP
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\fP)\&.
.SH "Function Documentation"
.PP
.SS "int hwloc_distances_add_commit (\fBhwloc_topology_t\fP topology, \fBhwloc_distances_add_handle_t\fP handle, unsigned long flags)"
.PP
Commit a new distances structure\&. This function finalizes the distances structure and inserts in it the topology\&.
.PP
Parameter \fChandle\fP was previously returned by \fBhwloc_distances_add_create()\fP\&. Then objects and values were specified with \fBhwloc_distances_add_values()\fP\&.
.PP
\fCflags\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\&.
.PP
On error, the temporary distances structure and its content are destroyed\&.
.PP
\fBReturns\fP
.RS 4
0 on success\&.
.PP
-1 on error\&.
.RE
.PP
.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)"
.PP
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\&.
.PP
Parameter \fCname\fP is optional, it may be \fCNULL\fP\&. Otherwise, it will be copied internally and may later be freed by the caller\&.
.PP
\fCkind\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\&.
.PP
\fCflags\fP must be \fC0\fP for now\&.
.PP
\fBReturns\fP
.RS 4
A hwloc_distances_add_handle_t that should then be passed to \fBhwloc_distances_add_values()\fP and \fBhwloc_distances_add_commit()\fP\&.
.PP
\fCNULL\fP on error\&.
.RE
.PP
.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)"
.PP
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\&.
.PP
The number of objects is \fCnbobjs\fP and the array of objects is \fCobjs\fP\&. Distance values are stored as a one-dimension array in \fCvalues\fP\&. The distance from object i to object j is in slot i*nbobjs+j\&.
.PP
\fCnbobjs\fP must be at least 2\&.
.PP
Arrays \fCobjs\fP and \fCvalues\fP will be copied internally, they may later be freed by the caller\&.
.PP
On error, the temporary distances structure and its content are destroyed\&.
.PP
\fCflags\fP must be \fC0\fP for now\&.
.PP
\fBReturns\fP
.RS 4
0 on success\&.
.PP
-1 on error\&.
.RE
.PP
.SH "Author"
.PP
Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.
|
