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
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
.TH "Binding" 3 "20 Jul 2010" "Version 1.0.2" "Hardware Locality (hwloc)" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Binding \-
.SS "Enumerations"
.in +1c
.ti -1c
.RI "enum \fBhwloc_cpubind_policy_t\fP { \fBHWLOC_CPUBIND_PROCESS\fP, \fBHWLOC_CPUBIND_THREAD\fP, \fBHWLOC_CPUBIND_STRICT\fP }"
.br
.RI "\fIProcess/Thread binding policy. \fP"
.in -1c
.SS "Functions"
.in +1c
.ti -1c
.RI "HWLOC_DECLSPEC int \fBhwloc_set_cpubind\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_const_cpuset_t\fP set, int policy)"
.br
.RI "\fIBind current process or thread on cpus given in cpuset \fCset\fP. \fP"
.ti -1c
.RI "HWLOC_DECLSPEC int \fBhwloc_get_cpubind\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_cpuset_t\fP set, int policy)"
.br
.RI "\fIGet current process or thread binding. \fP"
.ti -1c
.RI "HWLOC_DECLSPEC int \fBhwloc_set_proc_cpubind\fP (\fBhwloc_topology_t\fP topology, hwloc_pid_t pid, \fBhwloc_const_cpuset_t\fP set, int policy)"
.br
.RI "\fIBind a process \fCpid\fP on cpus given in cpuset \fCset\fP. \fP"
.ti -1c
.RI "HWLOC_DECLSPEC int \fBhwloc_get_proc_cpubind\fP (\fBhwloc_topology_t\fP topology, hwloc_pid_t pid, \fBhwloc_cpuset_t\fP set, int policy)"
.br
.RI "\fIGet the current binding of process \fCpid\fP. \fP"
.ti -1c
.RI "HWLOC_DECLSPEC int \fBhwloc_set_thread_cpubind\fP (\fBhwloc_topology_t\fP topology, hwloc_thread_t tid, \fBhwloc_const_cpuset_t\fP set, int policy)"
.br
.RI "\fIBind a thread \fCtid\fP on cpus given in cpuset \fCset\fP. \fP"
.ti -1c
.RI "HWLOC_DECLSPEC int \fBhwloc_get_thread_cpubind\fP (\fBhwloc_topology_t\fP topology, hwloc_thread_t tid, \fBhwloc_cpuset_t\fP set, int policy)"
.br
.RI "\fIGet the current binding of thread \fCtid\fP. \fP"
.in -1c
.SH "Detailed Description"
.PP
It is often useful to call \fBhwloc_cpuset_singlify()\fP first so that a single CPU remains in the set. This way, the process will not even migrate between different CPUs. Some OSes also only support that kind of binding.
.PP
\fBNote:\fP
.RS 4
Some OSes do not provide all ways to bind processes, threads, etc and the corresponding binding functions may fail. ENOSYS is returned when it is not possible to bind the requested kind of object processes/threads). EXDEV is returned when the requested cpuset can not be enforced (e.g. some systems only allow one CPU, and some other systems only allow one NUMA node)
.RE
.PP
The most portable version that should be preferred over the others, whenever possible, is
.PP
.PP
.nf
hwloc_set_cpubind(topology, set, 0),
.fi
.PP
.PP
as it just binds the current program, assuming it is monothread, or
.PP
.PP
.nf
hwloc_set_cpubind(topology, set, HWLOC_CPUBIND_THREAD),
.fi
.PP
.PP
which binds the current thread of the current program (which may be multithreaded).
.PP
\fBNote:\fP
.RS 4
To unbind, just call the binding function with either a full cpuset or a cpuset equal to the system cpuset.
.RE
.PP
.SH "Enumeration Type Documentation"
.PP
.SS "enum \fBhwloc_cpubind_policy_t\fP"
.PP
Process/Thread binding policy. These flags can be used to refine the binding policy.
.PP
The default (0) is to bind the current process, assumed to be mono-thread, in a non-strict way. This is the most portable way to bind as all OSes usually provide it.
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fIHWLOC_CPUBIND_PROCESS \fP\fP
Bind all threads of the current multithreaded process. This may not be supported by some OSes (e.g. Linux).
.TP
\fB\fIHWLOC_CPUBIND_THREAD \fP\fP
Bind current thread of current process.
.TP
\fB\fIHWLOC_CPUBIND_STRICT \fP\fP
Request for strict binding from the OS. By default, when the designated CPUs are all busy while other CPUs are idle, OSes may execute the thread/process on those other CPUs instead of the designated CPUs, to let them progress anyway. Strict binding means that the thread/process will _never_ execute on other cpus than the designated CPUs, even when those are busy with other tasks and other CPUs are idle.
.PP
\fBNote:\fP
.RS 4
Depending on OSes and implementations, strict binding may not be possible (implementation reason) or not allowed (administrative reasons), and the function will fail in that case.
.RE
.PP
When retrieving the binding of a process, this flag checks whether all its threads actually have the same binding. If the flag is not given, the binding of each thread will be accumulated.
.PP
\fBNote:\fP
.RS 4
This flag is meaningless when retrieving the binding of a thread.
.RE
.PP
.SH "Function Documentation"
.PP
.SS "HWLOC_DECLSPEC int hwloc_get_cpubind (\fBhwloc_topology_t\fP topology, \fBhwloc_cpuset_t\fP set, int policy)"
.PP
Get current process or thread binding.
.SS "HWLOC_DECLSPEC int hwloc_get_proc_cpubind (\fBhwloc_topology_t\fP topology, hwloc_pid_t pid, \fBhwloc_cpuset_t\fP set, int policy)"
.PP
Get the current binding of process \fCpid\fP. \fBNote:\fP
.RS 4
hwloc_pid_t is pid_t on unix platforms, and HANDLE on native Windows platforms
.PP
HWLOC_CPUBIND_THREAD can not be used in \fCpolicy\fP.
.RE
.PP
.SS "HWLOC_DECLSPEC int hwloc_get_thread_cpubind (\fBhwloc_topology_t\fP topology, hwloc_thread_t tid, \fBhwloc_cpuset_t\fP set, int policy)"
.PP
Get the current binding of thread \fCtid\fP. \fBNote:\fP
.RS 4
hwloc_thread_t is pthread_t on unix platforms, and HANDLE on native Windows platforms
.PP
HWLOC_CPUBIND_PROCESS can not be used in \fCpolicy\fP.
.RE
.PP
.SS "HWLOC_DECLSPEC int hwloc_set_cpubind (\fBhwloc_topology_t\fP topology, \fBhwloc_const_cpuset_t\fP set, int policy)"
.PP
Bind current process or thread on cpus given in cpuset \fCset\fP. \fBReturns:\fP
.RS 4
ENOSYS if the action is not supported
.PP
EXDEV if the binding cannot be enforced
.RE
.PP
.SS "HWLOC_DECLSPEC int hwloc_set_proc_cpubind (\fBhwloc_topology_t\fP topology, hwloc_pid_t pid, \fBhwloc_const_cpuset_t\fP set, int policy)"
.PP
Bind a process \fCpid\fP on cpus given in cpuset \fCset\fP. \fBNote:\fP
.RS 4
hwloc_pid_t is pid_t on unix platforms, and HANDLE on native Windows platforms
.PP
HWLOC_CPUBIND_THREAD can not be used in \fCpolicy\fP.
.RE
.PP
.SS "HWLOC_DECLSPEC int hwloc_set_thread_cpubind (\fBhwloc_topology_t\fP topology, hwloc_thread_t tid, \fBhwloc_const_cpuset_t\fP set, int policy)"
.PP
Bind a thread \fCtid\fP on cpus given in cpuset \fCset\fP. \fBNote:\fP
.RS 4
hwloc_thread_t is pthread_t on unix platforms, and HANDLE on native Windows platforms
.PP
HWLOC_CPUBIND_PROCESS can not be used in \fCpolicy\fP.
.RE
.PP
.SH "Author"
.PP
Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code.
|
