| 1 |
.TH "hwlocality_cpubinding" 3 "Version 2.14.0" "Hardware Locality (hwloc)" \" -*- nroff -*- |
| 2 |
.ad l |
| 3 |
.nh |
| 4 |
.SH NAME |
| 5 |
hwlocality_cpubinding \- CPU binding |
| 6 |
.SH SYNOPSIS |
| 7 |
.br |
| 8 |
.PP |
| 9 |
.SS "Enumerations" |
| 10 |
|
| 11 |
.in +1c |
| 12 |
.ti -1c |
| 13 |
.RI "enum \fBhwloc_cpubind_flags_t\fP { \fBHWLOC_CPUBIND_PROCESS\fP, \fBHWLOC_CPUBIND_THREAD\fP, \fBHWLOC_CPUBIND_STRICT\fP, \fBHWLOC_CPUBIND_NOMEMBIND\fP }" |
| 14 |
.br |
| 15 |
.in -1c |
| 16 |
.SS "Functions" |
| 17 |
|
| 18 |
.in +1c |
| 19 |
.ti -1c |
| 20 |
.RI "int \fBhwloc_set_cpubind\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_const_cpuset_t\fP set, int flags)" |
| 21 |
.br |
| 22 |
.ti -1c |
| 23 |
.RI "int \fBhwloc_get_cpubind\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_cpuset_t\fP set, int flags)" |
| 24 |
.br |
| 25 |
.ti -1c |
| 26 |
.RI "int \fBhwloc_set_proc_cpubind\fP (\fBhwloc_topology_t\fP topology, hwloc_pid_t pid, \fBhwloc_const_cpuset_t\fP set, int flags)" |
| 27 |
.br |
| 28 |
.ti -1c |
| 29 |
.RI "int \fBhwloc_get_proc_cpubind\fP (\fBhwloc_topology_t\fP topology, hwloc_pid_t pid, \fBhwloc_cpuset_t\fP set, int flags)" |
| 30 |
.br |
| 31 |
.ti -1c |
| 32 |
.RI "int \fBhwloc_set_thread_cpubind\fP (\fBhwloc_topology_t\fP topology, hwloc_thread_t thread, \fBhwloc_const_cpuset_t\fP set, int flags)" |
| 33 |
.br |
| 34 |
.ti -1c |
| 35 |
.RI "int \fBhwloc_get_thread_cpubind\fP (\fBhwloc_topology_t\fP topology, hwloc_thread_t thread, \fBhwloc_cpuset_t\fP set, int flags)" |
| 36 |
.br |
| 37 |
.ti -1c |
| 38 |
.RI "int \fBhwloc_get_last_cpu_location\fP (\fBhwloc_topology_t\fP topology, \fBhwloc_cpuset_t\fP set, int flags)" |
| 39 |
.br |
| 40 |
.ti -1c |
| 41 |
.RI "int \fBhwloc_get_proc_last_cpu_location\fP (\fBhwloc_topology_t\fP topology, hwloc_pid_t pid, \fBhwloc_cpuset_t\fP set, int flags)" |
| 42 |
.br |
| 43 |
.in -1c |
| 44 |
.SH "Detailed Description" |
| 45 |
.PP |
| 46 |
Some operating systems only support binding threads or processes to a single PU\&. Others allow binding to larger sets such as entire Cores or Packages or even random sets of individual PUs\&. In such operating system, the scheduler is free to run the task on one of these PU, then migrate it to another PU, etc\&. It is often useful to call \fBhwloc_bitmap_singlify()\fP on the target CPU set before passing it to the binding function to avoid these expensive migrations\&. See the documentation of \fBhwloc_bitmap_singlify()\fP for details\&. |
| 47 |
|
| 48 |
.PP |
| 49 |
Some operating systems do not provide all hwloc-supported mechanisms to bind processes, threads, etc\&. \fBhwloc_topology_get_support()\fP may be used to query about the actual CPU binding support in the currently used operating system\&. |
| 50 |
|
| 51 |
.PP |
| 52 |
When the requested binding operation is not available and the \fBHWLOC_CPUBIND_STRICT\fP flag was passed, the function returns -1\&. \fRerrno\fP is set to \fRENOSYS\fP when it is not possible to bind the requested kind of object processes/threads\&. errno is set to \fREXDEV\fP 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)\&. |
| 53 |
|
| 54 |
.PP |
| 55 |
If \fBHWLOC_CPUBIND_STRICT\fP was not passed, the function may fail as well, or the operating system may use a slightly different operation (with side-effects, smaller binding set, etc\&.) when the requested operation is not exactly supported\&. |
| 56 |
|
| 57 |
.PP |
| 58 |
The most portable version that should be preferred over the others, whenever possible, is the following one which just binds the current program, assuming it is single-threaded: |
| 59 |
|
| 60 |
.PP |
| 61 |
.PP |
| 62 |
.nf |
| 63 |
hwloc_set_cpubind(topology, set, 0), |
| 64 |
.fi |
| 65 |
.PP |
| 66 |
|
| 67 |
.PP |
| 68 |
If the program may be multithreaded, the following one should be preferred to only bind the current thread: |
| 69 |
|
| 70 |
.PP |
| 71 |
.PP |
| 72 |
.nf |
| 73 |
hwloc_set_cpubind(topology, set, HWLOC_CPUBIND_THREAD), |
| 74 |
.fi |
| 75 |
.PP |
| 76 |
|
| 77 |
.PP |
| 78 |
\fBSee also\fP |
| 79 |
.RS 4 |
| 80 |
Some example codes are available under doc/examples/ in the source tree\&. |
| 81 |
.RE |
| 82 |
.PP |
| 83 |
\fBNote\fP |
| 84 |
.RS 4 |
| 85 |
To unbind, just call the binding function with either a full cpuset or a cpuset equal to the system cpuset\&. |
| 86 |
|
| 87 |
.PP |
| 88 |
On some operating systems, CPU binding may have effects on memory binding, see \fBHWLOC_CPUBIND_NOMEMBIND\fP |
| 89 |
|
| 90 |
.PP |
| 91 |
Running lstopo --top or hwloc-ps can be a very convenient tool to check how binding actually happened\&. |
| 92 |
.RE |
| 93 |
.PP |
| 94 |
|
| 95 |
.SH "Enumeration Type Documentation" |
| 96 |
.PP |
| 97 |
.SS "enum \fBhwloc_cpubind_flags_t\fP" |
| 98 |
|
| 99 |
.PP |
| 100 |
Process/Thread binding flags\&. These bit flags can be used to refine the binding policy\&. |
| 101 |
|
| 102 |
.PP |
| 103 |
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\&. |
| 104 |
|
| 105 |
.PP |
| 106 |
\fBNote\fP |
| 107 |
.RS 4 |
| 108 |
Not all systems support all kinds of binding\&. See the "Detailed Description" section of \fBCPU binding\fP for a description of errors that can occur\&. |
| 109 |
.RE |
| 110 |
.PP |
| 111 |
|
| 112 |
.PP |
| 113 |
\fBEnumerator\fP |
| 114 |
.in +1c |
| 115 |
.TP |
| 116 |
\f(BIHWLOC_CPUBIND_PROCESS \fP |
| 117 |
Bind all threads of the current (possibly) multithreaded process\&. |
| 118 |
.TP |
| 119 |
\f(BIHWLOC_CPUBIND_THREAD \fP |
| 120 |
Bind current thread of current process\&. |
| 121 |
.TP |
| 122 |
\f(BIHWLOC_CPUBIND_STRICT \fP |
| 123 |
Request for strict binding from the OS\&. By default, when the designated CPUs are all busy while other CPUs are idle, operating systems 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\&. |
| 124 |
|
| 125 |
.PP |
| 126 |
\fBNote\fP |
| 127 |
.RS 4 |
| 128 |
Depending on the operating system, strict binding may not be possible (e\&.g\&., the OS does not implement it) or not allowed (e\&.g\&., for an administrative reasons), and the function will fail in that case\&. |
| 129 |
.RE |
| 130 |
.PP |
| 131 |
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\&. |
| 132 |
|
| 133 |
.PP |
| 134 |
\fBNote\fP |
| 135 |
.RS 4 |
| 136 |
This flag is meaningless when retrieving the binding of a thread\&. |
| 137 |
.RE |
| 138 |
.PP |
| 139 |
|
| 140 |
.TP |
| 141 |
\f(BIHWLOC_CPUBIND_NOMEMBIND \fP |
| 142 |
Avoid any effect on memory binding\&. On some operating systems, some CPU binding function would also bind the memory on the corresponding NUMA node\&. It is often not a problem for the application, but if it is, setting this flag will make hwloc avoid using OS functions that would also bind memory\&. This will however reduce the support of CPU bindings, i\&.e\&. potentially return -1 with errno set to \fRENOSYS\fP in some cases\&. |
| 143 |
|
| 144 |
.PP |
| 145 |
This flag is only meaningful when used with functions that set the CPU binding\&. It is ignored when used with functions that get CPU binding information\&. |
| 146 |
.SH "Function Documentation" |
| 147 |
.PP |
| 148 |
.SS "int hwloc_get_cpubind (\fBhwloc_topology_t\fP topology, \fBhwloc_cpuset_t\fP set, int flags)" |
| 149 |
|
| 150 |
.PP |
| 151 |
Get current process or thread binding\&. The CPU-set \fRset\fP (previously allocated by the caller) is filled with the list of PUs which the process or thread (according to \fIflags\fP) was last bound to\&. |
| 152 |
|
| 153 |
.PP |
| 154 |
\fBReturns\fP |
| 155 |
.RS 4 |
| 156 |
0 on success, -1 on error\&. |
| 157 |
.RE |
| 158 |
.PP |
| 159 |
|
| 160 |
.SS "int hwloc_get_last_cpu_location (\fBhwloc_topology_t\fP topology, \fBhwloc_cpuset_t\fP set, int flags)" |
| 161 |
|
| 162 |
.PP |
| 163 |
Get the last physical CPU where the current process or thread ran\&. The CPU-set \fRset\fP (previously allocated by the caller) is filled with the list of PUs which the process or thread (according to \fIflags\fP) last ran on\&. |
| 164 |
|
| 165 |
.PP |
| 166 |
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\&. |
| 167 |
|
| 168 |
.PP |
| 169 |
\fRflags\fP can include either \fBHWLOC_CPUBIND_PROCESS\fP or \fBHWLOC_CPUBIND_THREAD\fP 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\&. |
| 170 |
|
| 171 |
.PP |
| 172 |
\fBReturns\fP |
| 173 |
.RS 4 |
| 174 |
0 on success, -1 on error\&. |
| 175 |
.RE |
| 176 |
.PP |
| 177 |
|
| 178 |
.SS "int hwloc_get_proc_cpubind (\fBhwloc_topology_t\fP topology, hwloc_pid_t pid, \fBhwloc_cpuset_t\fP set, int flags)" |
| 179 |
|
| 180 |
.PP |
| 181 |
Get the current physical binding of process \fRpid\fP\&. The CPU-set \fRset\fP (previously allocated by the caller) is filled with the list of PUs which the process was last bound to\&. |
| 182 |
|
| 183 |
.PP |
| 184 |
\fBReturns\fP |
| 185 |
.RS 4 |
| 186 |
0 on success, -1 on error\&. |
| 187 |
.RE |
| 188 |
.PP |
| 189 |
\fBNote\fP |
| 190 |
.RS 4 |
| 191 |
\fRhwloc_pid_t\fP is \fRpid_t\fP on Unix platforms, and \fRHANDLE\fP on native Windows platforms\&. |
| 192 |
|
| 193 |
.PP |
| 194 |
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\&. |
| 195 |
|
| 196 |
.PP |
| 197 |
On non-Linux systems, HWLOC_CPUBIND_THREAD can not be used in \fRflags\fP\&. |
| 198 |
.RE |
| 199 |
.PP |
| 200 |
|
| 201 |
.SS "int hwloc_get_proc_last_cpu_location (\fBhwloc_topology_t\fP topology, hwloc_pid_t pid, \fBhwloc_cpuset_t\fP set, int flags)" |
| 202 |
|
| 203 |
.PP |
| 204 |
Get the last physical CPU where a process ran\&. The CPU-set \fRset\fP (previously allocated by the caller) is filled with the list of PUs which the process last ran on\&. |
| 205 |
|
| 206 |
.PP |
| 207 |
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\&. |
| 208 |
|
| 209 |
.PP |
| 210 |
\fBReturns\fP |
| 211 |
.RS 4 |
| 212 |
0 on success, -1 on error\&. |
| 213 |
.RE |
| 214 |
.PP |
| 215 |
\fBNote\fP |
| 216 |
.RS 4 |
| 217 |
\fRhwloc_pid_t\fP is \fRpid_t\fP on Unix platforms, and \fRHANDLE\fP on native Windows platforms\&. |
| 218 |
|
| 219 |
.PP |
| 220 |
As a special case on Linux, if a tid (thread ID) is supplied instead of a pid (process ID) and \fBHWLOC_CPUBIND_THREAD\fP is passed in flags, the last CPU location of that specific thread is returned\&. |
| 221 |
|
| 222 |
.PP |
| 223 |
On non-Linux systems, \fBHWLOC_CPUBIND_THREAD\fP can not be used in \fRflags\fP\&. |
| 224 |
.RE |
| 225 |
.PP |
| 226 |
|
| 227 |
.SS "int hwloc_get_thread_cpubind (\fBhwloc_topology_t\fP topology, hwloc_thread_t thread, \fBhwloc_cpuset_t\fP set, int flags)" |
| 228 |
|
| 229 |
.PP |
| 230 |
Get the current physical binding of thread \fRtid\fP\&. The CPU-set \fRset\fP (previously allocated by the caller) is filled with the list of PUs which the thread was last bound to\&. |
| 231 |
|
| 232 |
.PP |
| 233 |
\fBReturns\fP |
| 234 |
.RS 4 |
| 235 |
0 on success, -1 on error\&. |
| 236 |
.RE |
| 237 |
.PP |
| 238 |
\fBNote\fP |
| 239 |
.RS 4 |
| 240 |
\fRhwloc_thread_t\fP is \fRpthread_t\fP on Unix platforms, and \fRHANDLE\fP on native Windows platforms\&. |
| 241 |
|
| 242 |
.PP |
| 243 |
\fBHWLOC_CPUBIND_PROCESS\fP can not be used in \fRflags\fP\&. |
| 244 |
.RE |
| 245 |
.PP |
| 246 |
|
| 247 |
.SS "int hwloc_set_cpubind (\fBhwloc_topology_t\fP topology, \fBhwloc_const_cpuset_t\fP set, int flags)" |
| 248 |
|
| 249 |
.PP |
| 250 |
Bind current process or thread on CPUs given in physical bitmap \fRset\fP\&. |
| 251 |
.PP |
| 252 |
\fBReturns\fP |
| 253 |
.RS 4 |
| 254 |
0 on success\&. |
| 255 |
|
| 256 |
.PP |
| 257 |
-1 with errno set to \fRENOSYS\fP if the action is not supported\&. |
| 258 |
|
| 259 |
.PP |
| 260 |
-1 with errno set to \fREXDEV\fP if the binding cannot be enforced\&. |
| 261 |
.RE |
| 262 |
.PP |
| 263 |
|
| 264 |
.SS "int hwloc_set_proc_cpubind (\fBhwloc_topology_t\fP topology, hwloc_pid_t pid, \fBhwloc_const_cpuset_t\fP set, int flags)" |
| 265 |
|
| 266 |
.PP |
| 267 |
Bind a process \fRpid\fP on CPUs given in physical bitmap \fRset\fP\&. |
| 268 |
.PP |
| 269 |
\fBReturns\fP |
| 270 |
.RS 4 |
| 271 |
0 on success, -1 on error\&. |
| 272 |
.RE |
| 273 |
.PP |
| 274 |
\fBNote\fP |
| 275 |
.RS 4 |
| 276 |
\fRhwloc_pid_t\fP is \fRpid_t\fP on Unix platforms, and \fRHANDLE\fP on native Windows platforms\&. |
| 277 |
|
| 278 |
.PP |
| 279 |
As a special case on Linux, if a tid (thread ID) is supplied instead of a pid (process ID) and \fBHWLOC_CPUBIND_THREAD\fP is passed in flags, the binding is applied to that specific thread\&. |
| 280 |
|
| 281 |
.PP |
| 282 |
On non-Linux systems, \fBHWLOC_CPUBIND_THREAD\fP can not be used in \fRflags\fP\&. |
| 283 |
.RE |
| 284 |
.PP |
| 285 |
|
| 286 |
.SS "int hwloc_set_thread_cpubind (\fBhwloc_topology_t\fP topology, hwloc_thread_t thread, \fBhwloc_const_cpuset_t\fP set, int flags)" |
| 287 |
|
| 288 |
.PP |
| 289 |
Bind a thread \fRthread\fP on CPUs given in physical bitmap \fRset\fP\&. |
| 290 |
.PP |
| 291 |
\fBReturns\fP |
| 292 |
.RS 4 |
| 293 |
0 on success, -1 on error\&. |
| 294 |
.RE |
| 295 |
.PP |
| 296 |
\fBNote\fP |
| 297 |
.RS 4 |
| 298 |
\fRhwloc_thread_t\fP is \fRpthread_t\fP on Unix platforms, and \fRHANDLE\fP on native Windows platforms\&. |
| 299 |
|
| 300 |
.PP |
| 301 |
\fBHWLOC_CPUBIND_PROCESS\fP can not be used in \fRflags\fP\&. |
| 302 |
.RE |
| 303 |
.PP |
| 304 |
|
| 305 |
.SH "Author" |
| 306 |
.PP |
| 307 |
Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&. |