]>
Commit | Line | Data |
---|---|---|
5ce8f203 UD |
1 | @node Resource Usage And Limitation, Non-Local Exits, Date and Time, Top |
2 | @c %MENU% Functions for examining resource usage and getting and setting limits | |
3 | @chapter Resource Usage And Limitation | |
4 | This chapter describes functions for examining how much of various kinds of | |
5 | resources (CPU time, memory, etc.) a process has used and getting and setting | |
6 | limits on future usage. | |
7 | ||
8 | @menu | |
9 | * Resource Usage:: Measuring various resources used. | |
10 | * Limits on Resources:: Specifying limits on resource usage. | |
11 | * Priority:: Reading or setting process run priority. | |
b642f101 UD |
12 | * Memory Resources:: Querying memory available resources. |
13 | * Processor Resources:: Learn about the processors available. | |
5ce8f203 UD |
14 | @end menu |
15 | ||
16 | ||
17 | @node Resource Usage | |
18 | @section Resource Usage | |
19 | ||
20 | @pindex sys/resource.h | |
21 | The function @code{getrusage} and the data type @code{struct rusage} | |
22 | are used to examine the resource usage of a process. They are declared | |
23 | in @file{sys/resource.h}. | |
24 | ||
5ce8f203 | 25 | @deftypefun int getrusage (int @var{processes}, struct rusage *@var{rusage}) |
d08a7e4c | 26 | @standards{BSD, sys/resource.h} |
c8ce789c AO |
27 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
28 | @c On HURD, this calls task_info 3 times. On UNIX, it's a syscall. | |
5ce8f203 UD |
29 | This function reports resource usage totals for processes specified by |
30 | @var{processes}, storing the information in @code{*@var{rusage}}. | |
31 | ||
32 | In most systems, @var{processes} has only two valid values: | |
33 | ||
a449fc68 | 34 | @vtable @code |
5ce8f203 | 35 | @item RUSAGE_SELF |
d08a7e4c | 36 | @standards{BSD, sys/resource.h} |
5ce8f203 UD |
37 | Just the current process. |
38 | ||
5ce8f203 | 39 | @item RUSAGE_CHILDREN |
d08a7e4c | 40 | @standards{BSD, sys/resource.h} |
5ce8f203 | 41 | All child processes (direct and indirect) that have already terminated. |
a449fc68 | 42 | @end vtable |
5ce8f203 | 43 | |
5ce8f203 UD |
44 | The return value of @code{getrusage} is zero for success, and @code{-1} |
45 | for failure. | |
46 | ||
47 | @table @code | |
48 | @item EINVAL | |
49 | The argument @var{processes} is not valid. | |
50 | @end table | |
51 | @end deftypefun | |
52 | ||
53 | One way of getting resource usage for a particular child process is with | |
54 | the function @code{wait4}, which returns totals for a child when it | |
55 | terminates. @xref{BSD Wait Functions}. | |
56 | ||
5ce8f203 | 57 | @deftp {Data Type} {struct rusage} |
d08a7e4c | 58 | @standards{BSD, sys/resource.h} |
5ce8f203 UD |
59 | This data type stores various resource usage statistics. It has the |
60 | following members, and possibly others: | |
61 | ||
62 | @table @code | |
63 | @item struct timeval ru_utime | |
64 | Time spent executing user instructions. | |
65 | ||
66 | @item struct timeval ru_stime | |
67 | Time spent in operating system code on behalf of @var{processes}. | |
68 | ||
69 | @item long int ru_maxrss | |
70 | The maximum resident set size used, in kilobytes. That is, the maximum | |
71 | number of kilobytes of physical memory that @var{processes} used | |
72 | simultaneously. | |
73 | ||
74 | @item long int ru_ixrss | |
75 | An integral value expressed in kilobytes times ticks of execution, which | |
76 | indicates the amount of memory used by text that was shared with other | |
77 | processes. | |
78 | ||
79 | @item long int ru_idrss | |
80 | An integral value expressed the same way, which is the amount of | |
81 | unshared memory used for data. | |
82 | ||
83 | @item long int ru_isrss | |
84 | An integral value expressed the same way, which is the amount of | |
85 | unshared memory used for stack space. | |
86 | ||
87 | @item long int ru_minflt | |
88 | The number of page faults which were serviced without requiring any I/O. | |
89 | ||
90 | @item long int ru_majflt | |
91 | The number of page faults which were serviced by doing I/O. | |
92 | ||
93 | @item long int ru_nswap | |
94 | The number of times @var{processes} was swapped entirely out of main memory. | |
95 | ||
96 | @item long int ru_inblock | |
97 | The number of times the file system had to read from the disk on behalf | |
98 | of @var{processes}. | |
99 | ||
100 | @item long int ru_oublock | |
101 | The number of times the file system had to write to the disk on behalf | |
102 | of @var{processes}. | |
103 | ||
104 | @item long int ru_msgsnd | |
105 | Number of IPC messages sent. | |
106 | ||
107 | @item long int ru_msgrcv | |
108 | Number of IPC messages received. | |
109 | ||
110 | @item long int ru_nsignals | |
111 | Number of signals received. | |
112 | ||
113 | @item long int ru_nvcsw | |
114 | The number of times @var{processes} voluntarily invoked a context switch | |
115 | (usually to wait for some service). | |
116 | ||
117 | @item long int ru_nivcsw | |
118 | The number of times an involuntary context switch took place (because | |
119 | a time slice expired, or another process of higher priority was | |
120 | scheduled). | |
121 | @end table | |
122 | @end deftp | |
123 | ||
124 | @code{vtimes} is a historical function that does some of what | |
125 | @code{getrusage} does. @code{getrusage} is a better choice. | |
126 | ||
127 | @code{vtimes} and its @code{vtimes} data structure are declared in | |
128 | @file{sys/vtimes.h}. | |
129 | @pindex sys/vtimes.h | |
5ce8f203 | 130 | |
8ded91fb | 131 | @deftypefun int vtimes (struct vtimes *@var{current}, struct vtimes *@var{child}) |
d08a7e4c | 132 | @standards{???, sys/vtimes.h} |
c8ce789c AO |
133 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
134 | @c Calls getrusage twice. | |
5ce8f203 UD |
135 | |
136 | @code{vtimes} reports resource usage totals for a process. | |
137 | ||
138 | If @var{current} is non-null, @code{vtimes} stores resource usage totals for | |
139 | the invoking process alone in the structure to which it points. If | |
140 | @var{child} is non-null, @code{vtimes} stores resource usage totals for all | |
141 | past children (which have terminated) of the invoking process in the structure | |
142 | to which it points. | |
143 | ||
144 | @deftp {Data Type} {struct vtimes} | |
145 | This data type contains information about the resource usage of a process. | |
146 | Each member corresponds to a member of the @code{struct rusage} data type | |
147 | described above. | |
148 | ||
149 | @table @code | |
150 | @item vm_utime | |
151 | User CPU time. Analogous to @code{ru_utime} in @code{struct rusage} | |
152 | @item vm_stime | |
153 | System CPU time. Analogous to @code{ru_stime} in @code{struct rusage} | |
154 | @item vm_idsrss | |
155 | Data and stack memory. The sum of the values that would be reported as | |
156 | @code{ru_idrss} and @code{ru_isrss} in @code{struct rusage} | |
157 | @item vm_ixrss | |
158 | Shared memory. Analogous to @code{ru_ixrss} in @code{struct rusage} | |
159 | @item vm_maxrss | |
160 | Maximent resident set size. Analogous to @code{ru_maxrss} in | |
161 | @code{struct rusage} | |
162 | @item vm_majflt | |
163 | Major page faults. Analogous to @code{ru_majflt} in @code{struct rusage} | |
164 | @item vm_minflt | |
165 | Minor page faults. Analogous to @code{ru_minflt} in @code{struct rusage} | |
166 | @item vm_nswap | |
167 | Swap count. Analogous to @code{ru_nswap} in @code{struct rusage} | |
168 | @item vm_inblk | |
169 | Disk reads. Analogous to @code{ru_inblk} in @code{struct rusage} | |
170 | @item vm_oublk | |
171 | Disk writes. Analogous to @code{ru_oublk} in @code{struct rusage} | |
172 | @end table | |
173 | @end deftp | |
174 | ||
175 | ||
176 | The return value is zero if the function succeeds; @code{-1} otherwise. | |
177 | ||
178 | ||
179 | ||
180 | @end deftypefun | |
181 | An additional historical function for examining resource usage, | |
182 | @code{vtimes}, is supported but not documented here. It is declared in | |
183 | @file{sys/vtimes.h}. | |
184 | ||
185 | @node Limits on Resources | |
186 | @section Limiting Resource Usage | |
187 | @cindex resource limits | |
188 | @cindex limits on resource usage | |
189 | @cindex usage limits | |
190 | ||
191 | You can specify limits for the resource usage of a process. When the | |
192 | process tries to exceed a limit, it may get a signal, or the system call | |
193 | by which it tried to do so may fail, depending on the resource. Each | |
194 | process initially inherits its limit values from its parent, but it can | |
195 | subsequently change them. | |
196 | ||
197 | There are two per-process limits associated with a resource: | |
198 | @cindex limit | |
199 | ||
200 | @table @dfn | |
201 | @item current limit | |
202 | The current limit is the value the system will not allow usage to | |
203 | exceed. It is also called the ``soft limit'' because the process being | |
204 | limited can generally raise the current limit at will. | |
205 | @cindex current limit | |
206 | @cindex soft limit | |
207 | ||
208 | @item maximum limit | |
209 | The maximum limit is the maximum value to which a process is allowed to | |
210 | set its current limit. It is also called the ``hard limit'' because | |
211 | there is no way for a process to get around it. A process may lower | |
212 | its own maximum limit, but only the superuser may increase a maximum | |
213 | limit. | |
214 | @cindex maximum limit | |
215 | @cindex hard limit | |
216 | @end table | |
217 | ||
218 | @pindex sys/resource.h | |
219 | The symbols for use with @code{getrlimit}, @code{setrlimit}, | |
0bc93a2f | 220 | @code{getrlimit64}, and @code{setrlimit64} are defined in |
5ce8f203 UD |
221 | @file{sys/resource.h}. |
222 | ||
5ce8f203 | 223 | @deftypefun int getrlimit (int @var{resource}, struct rlimit *@var{rlp}) |
d08a7e4c | 224 | @standards{BSD, sys/resource.h} |
c8ce789c AO |
225 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
226 | @c Direct syscall on most systems. | |
5ce8f203 UD |
227 | Read the current and maximum limits for the resource @var{resource} |
228 | and store them in @code{*@var{rlp}}. | |
229 | ||
230 | The return value is @code{0} on success and @code{-1} on failure. The | |
231 | only possible @code{errno} error condition is @code{EFAULT}. | |
232 | ||
233 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a | |
234 | 32-bit system this function is in fact @code{getrlimit64}. Thus, the | |
235 | LFS interface transparently replaces the old interface. | |
236 | @end deftypefun | |
237 | ||
5ce8f203 | 238 | @deftypefun int getrlimit64 (int @var{resource}, struct rlimit64 *@var{rlp}) |
d08a7e4c | 239 | @standards{Unix98, sys/resource.h} |
c8ce789c AO |
240 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
241 | @c Direct syscall on most systems, wrapper to getrlimit otherwise. | |
5ce8f203 UD |
242 | This function is similar to @code{getrlimit} but its second parameter is |
243 | a pointer to a variable of type @code{struct rlimit64}, which allows it | |
244 | to read values which wouldn't fit in the member of a @code{struct | |
245 | rlimit}. | |
246 | ||
247 | If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a | |
248 | 32-bit machine, this function is available under the name | |
249 | @code{getrlimit} and so transparently replaces the old interface. | |
250 | @end deftypefun | |
251 | ||
5ce8f203 | 252 | @deftypefun int setrlimit (int @var{resource}, const struct rlimit *@var{rlp}) |
d08a7e4c | 253 | @standards{BSD, sys/resource.h} |
c8ce789c AO |
254 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
255 | @c Direct syscall on most systems; lock-taking critical section on HURD. | |
5ce8f203 UD |
256 | Store the current and maximum limits for the resource @var{resource} |
257 | in @code{*@var{rlp}}. | |
258 | ||
259 | The return value is @code{0} on success and @code{-1} on failure. The | |
260 | following @code{errno} error condition is possible: | |
261 | ||
262 | @table @code | |
263 | @item EPERM | |
264 | @itemize @bullet | |
265 | @item | |
266 | The process tried to raise a current limit beyond the maximum limit. | |
267 | ||
268 | @item | |
269 | The process tried to raise a maximum limit, but is not superuser. | |
270 | @end itemize | |
271 | @end table | |
272 | ||
273 | When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a | |
274 | 32-bit system this function is in fact @code{setrlimit64}. Thus, the | |
275 | LFS interface transparently replaces the old interface. | |
276 | @end deftypefun | |
277 | ||
5ce8f203 | 278 | @deftypefun int setrlimit64 (int @var{resource}, const struct rlimit64 *@var{rlp}) |
d08a7e4c | 279 | @standards{Unix98, sys/resource.h} |
c8ce789c AO |
280 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
281 | @c Wrapper for setrlimit or direct syscall. | |
5ce8f203 UD |
282 | This function is similar to @code{setrlimit} but its second parameter is |
283 | a pointer to a variable of type @code{struct rlimit64} which allows it | |
284 | to set values which wouldn't fit in the member of a @code{struct | |
285 | rlimit}. | |
286 | ||
287 | If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a | |
288 | 32-bit machine this function is available under the name | |
289 | @code{setrlimit} and so transparently replaces the old interface. | |
290 | @end deftypefun | |
291 | ||
5ce8f203 | 292 | @deftp {Data Type} {struct rlimit} |
d08a7e4c | 293 | @standards{BSD, sys/resource.h} |
5ce8f203 UD |
294 | This structure is used with @code{getrlimit} to receive limit values, |
295 | and with @code{setrlimit} to specify limit values for a particular process | |
296 | and resource. It has two fields: | |
297 | ||
298 | @table @code | |
299 | @item rlim_t rlim_cur | |
300 | The current limit | |
301 | ||
302 | @item rlim_t rlim_max | |
303 | The maximum limit. | |
304 | @end table | |
305 | ||
306 | For @code{getrlimit}, the structure is an output; it receives the current | |
307 | values. For @code{setrlimit}, it specifies the new values. | |
308 | @end deftp | |
309 | ||
310 | For the LFS functions a similar type is defined in @file{sys/resource.h}. | |
311 | ||
5ce8f203 | 312 | @deftp {Data Type} {struct rlimit64} |
d08a7e4c | 313 | @standards{Unix98, sys/resource.h} |
5ce8f203 UD |
314 | This structure is analogous to the @code{rlimit} structure above, but |
315 | its components have wider ranges. It has two fields: | |
316 | ||
317 | @table @code | |
318 | @item rlim64_t rlim_cur | |
319 | This is analogous to @code{rlimit.rlim_cur}, but with a different type. | |
320 | ||
321 | @item rlim64_t rlim_max | |
322 | This is analogous to @code{rlimit.rlim_max}, but with a different type. | |
323 | @end table | |
324 | ||
325 | @end deftp | |
326 | ||
327 | Here is a list of resources for which you can specify a limit. Memory | |
328 | and file sizes are measured in bytes. | |
329 | ||
2fe82ca6 | 330 | @vtable @code |
5ce8f203 | 331 | @item RLIMIT_CPU |
d08a7e4c | 332 | @standards{BSD, sys/resource.h} |
5ce8f203 UD |
333 | The maximum amount of CPU time the process can use. If it runs for |
334 | longer than this, it gets a signal: @code{SIGXCPU}. The value is | |
335 | measured in seconds. @xref{Operation Error Signals}. | |
336 | ||
5ce8f203 | 337 | @item RLIMIT_FSIZE |
d08a7e4c | 338 | @standards{BSD, sys/resource.h} |
5ce8f203 UD |
339 | The maximum size of file the process can create. Trying to write a |
340 | larger file causes a signal: @code{SIGXFSZ}. @xref{Operation Error | |
341 | Signals}. | |
342 | ||
5ce8f203 | 343 | @item RLIMIT_DATA |
d08a7e4c | 344 | @standards{BSD, sys/resource.h} |
5ce8f203 UD |
345 | The maximum size of data memory for the process. If the process tries |
346 | to allocate data memory beyond this amount, the allocation function | |
347 | fails. | |
348 | ||
5ce8f203 | 349 | @item RLIMIT_STACK |
d08a7e4c | 350 | @standards{BSD, sys/resource.h} |
5ce8f203 UD |
351 | The maximum stack size for the process. If the process tries to extend |
352 | its stack past this size, it gets a @code{SIGSEGV} signal. | |
353 | @xref{Program Error Signals}. | |
354 | ||
5ce8f203 | 355 | @item RLIMIT_CORE |
d08a7e4c | 356 | @standards{BSD, sys/resource.h} |
5ce8f203 UD |
357 | The maximum size core file that this process can create. If the process |
358 | terminates and would dump a core file larger than this, then no core | |
359 | file is created. So setting this limit to zero prevents core files from | |
360 | ever being created. | |
361 | ||
5ce8f203 | 362 | @item RLIMIT_RSS |
d08a7e4c | 363 | @standards{BSD, sys/resource.h} |
5ce8f203 UD |
364 | The maximum amount of physical memory that this process should get. |
365 | This parameter is a guide for the system's scheduler and memory | |
366 | allocator; the system may give the process more memory when there is a | |
367 | surplus. | |
368 | ||
5ce8f203 | 369 | @item RLIMIT_MEMLOCK |
d08a7e4c | 370 | @standards{BSD, sys/resource.h} |
5ce8f203 UD |
371 | The maximum amount of memory that can be locked into physical memory (so |
372 | it will never be paged out). | |
373 | ||
5ce8f203 | 374 | @item RLIMIT_NPROC |
d08a7e4c | 375 | @standards{BSD, sys/resource.h} |
5ce8f203 UD |
376 | The maximum number of processes that can be created with the same user ID. |
377 | If you have reached the limit for your user ID, @code{fork} will fail | |
378 | with @code{EAGAIN}. @xref{Creating a Process}. | |
379 | ||
5ce8f203 | 380 | @item RLIMIT_NOFILE |
5ce8f203 | 381 | @itemx RLIMIT_OFILE |
d08a7e4c | 382 | @standardsx{RLIMIT_NOFILE, BSD, sys/resource.h} |
5ce8f203 UD |
383 | The maximum number of files that the process can open. If it tries to |
384 | open more files than this, its open attempt fails with @code{errno} | |
385 | @code{EMFILE}. @xref{Error Codes}. Not all systems support this limit; | |
386 | GNU does, and 4.4 BSD does. | |
387 | ||
5ce8f203 | 388 | @item RLIMIT_AS |
d08a7e4c | 389 | @standards{Unix98, sys/resource.h} |
5ce8f203 UD |
390 | The maximum size of total memory that this process should get. If the |
391 | process tries to allocate more memory beyond this amount with, for | |
392 | example, @code{brk}, @code{malloc}, @code{mmap} or @code{sbrk}, the | |
393 | allocation function fails. | |
394 | ||
5ce8f203 | 395 | @item RLIM_NLIMITS |
d08a7e4c | 396 | @standards{BSD, sys/resource.h} |
5ce8f203 UD |
397 | The number of different resource limits. Any valid @var{resource} |
398 | operand must be less than @code{RLIM_NLIMITS}. | |
2fe82ca6 | 399 | @end vtable |
5ce8f203 | 400 | |
8ded91fb | 401 | @deftypevr Constant rlim_t RLIM_INFINITY |
d08a7e4c | 402 | @standards{BSD, sys/resource.h} |
5ce8f203 UD |
403 | This constant stands for a value of ``infinity'' when supplied as |
404 | the limit value in @code{setrlimit}. | |
405 | @end deftypevr | |
406 | ||
407 | ||
408 | The following are historical functions to do some of what the functions | |
409 | above do. The functions above are better choices. | |
410 | ||
411 | @code{ulimit} and the command symbols are declared in @file{ulimit.h}. | |
412 | @pindex ulimit.h | |
5ce8f203 | 413 | |
8ded91fb | 414 | @deftypefun {long int} ulimit (int @var{cmd}, @dots{}) |
d08a7e4c | 415 | @standards{BSD, ulimit.h} |
c8ce789c AO |
416 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
417 | @c Wrapper for getrlimit, setrlimit or | |
418 | @c sysconf(_SC_OPEN_MAX)->getdtablesize->getrlimit. | |
5ce8f203 UD |
419 | |
420 | @code{ulimit} gets the current limit or sets the current and maximum | |
421 | limit for a particular resource for the calling process according to the | |
d3e22d59 | 422 | command @var{cmd}. |
5ce8f203 UD |
423 | |
424 | If you are getting a limit, the command argument is the only argument. | |
425 | If you are setting a limit, there is a second argument: | |
426 | @code{long int} @var{limit} which is the value to which you are setting | |
427 | the limit. | |
428 | ||
429 | The @var{cmd} values and the operations they specify are: | |
2fe82ca6 | 430 | @vtable @code |
5ce8f203 UD |
431 | |
432 | @item GETFSIZE | |
433 | Get the current limit on the size of a file, in units of 512 bytes. | |
434 | ||
435 | @item SETFSIZE | |
436 | Set the current and maximum limit on the size of a file to @var{limit} * | |
437 | 512 bytes. | |
438 | ||
2fe82ca6 | 439 | @end vtable |
5ce8f203 UD |
440 | |
441 | There are also some other @var{cmd} values that may do things on some | |
442 | systems, but they are not supported. | |
443 | ||
444 | Only the superuser may increase a maximum limit. | |
445 | ||
446 | When you successfully get a limit, the return value of @code{ulimit} is | |
447 | that limit, which is never negative. When you successfully set a limit, | |
448 | the return value is zero. When the function fails, the return value is | |
449 | @code{-1} and @code{errno} is set according to the reason: | |
450 | ||
451 | @table @code | |
452 | @item EPERM | |
453 | A process tried to increase a maximum limit, but is not superuser. | |
454 | @end table | |
455 | ||
456 | ||
457 | @end deftypefun | |
458 | ||
459 | @code{vlimit} and its resource symbols are declared in @file{sys/vlimit.h}. | |
5ce8f203 | 460 | @pindex sys/vlimit.h |
5ce8f203 UD |
461 | |
462 | @deftypefun int vlimit (int @var{resource}, int @var{limit}) | |
d08a7e4c | 463 | @standards{BSD, sys/vlimit.h} |
c8ce789c AO |
464 | @safety{@prelim{}@mtunsafe{@mtasurace{:setrlimit}}@asunsafe{}@acsafe{}} |
465 | @c It calls getrlimit and modifies the rlim_cur field before calling | |
466 | @c setrlimit. There's a window for a concurrent call to setrlimit that | |
467 | @c modifies e.g. rlim_max, which will be lost if running as super-user. | |
5ce8f203 UD |
468 | |
469 | @code{vlimit} sets the current limit for a resource for a process. | |
470 | ||
471 | @var{resource} identifies the resource: | |
472 | ||
2fe82ca6 | 473 | @vtable @code |
5ce8f203 UD |
474 | @item LIM_CPU |
475 | Maximum CPU time. Same as @code{RLIMIT_CPU} for @code{setrlimit}. | |
476 | @item LIM_FSIZE | |
477 | Maximum file size. Same as @code{RLIMIT_FSIZE} for @code{setrlimit}. | |
478 | @item LIM_DATA | |
479 | Maximum data memory. Same as @code{RLIMIT_DATA} for @code{setrlimit}. | |
480 | @item LIM_STACK | |
481 | Maximum stack size. Same as @code{RLIMIT_STACK} for @code{setrlimit}. | |
482 | @item LIM_CORE | |
483 | Maximum core file size. Same as @code{RLIMIT_COR} for @code{setrlimit}. | |
484 | @item LIM_MAXRSS | |
485 | Maximum physical memory. Same as @code{RLIMIT_RSS} for @code{setrlimit}. | |
2fe82ca6 | 486 | @end vtable |
5ce8f203 UD |
487 | |
488 | The return value is zero for success, and @code{-1} with @code{errno} set | |
489 | accordingly for failure: | |
490 | ||
491 | @table @code | |
492 | @item EPERM | |
493 | The process tried to set its current limit beyond its maximum limit. | |
494 | @end table | |
495 | ||
496 | @end deftypefun | |
497 | ||
498 | @node Priority | |
639c6286 | 499 | @section Process CPU Priority And Scheduling |
5ce8f203 | 500 | @cindex process priority |
639c6286 | 501 | @cindex cpu priority |
5ce8f203 UD |
502 | @cindex priority of a process |
503 | ||
639c6286 UD |
504 | When multiple processes simultaneously require CPU time, the system's |
505 | scheduling policy and process CPU priorities determine which processes | |
506 | get it. This section describes how that determination is made and | |
1f77f049 | 507 | @glibcadj{} functions to control it. |
639c6286 UD |
508 | |
509 | It is common to refer to CPU scheduling simply as scheduling and a | |
510 | process' CPU priority simply as the process' priority, with the CPU | |
511 | resource being implied. Bear in mind, though, that CPU time is not the | |
512 | only resource a process uses or that processes contend for. In some | |
513 | cases, it is not even particularly important. Giving a process a high | |
514 | ``priority'' may have very little effect on how fast a process runs with | |
515 | respect to other processes. The priorities discussed in this section | |
516 | apply only to CPU time. | |
517 | ||
518 | CPU scheduling is a complex issue and different systems do it in wildly | |
519 | different ways. New ideas continually develop and find their way into | |
520 | the intricacies of the various systems' scheduling algorithms. This | |
87b56f36 | 521 | section discusses the general concepts, some specifics of systems |
1f77f049 | 522 | that commonly use @theglibc{}, and some standards. |
639c6286 UD |
523 | |
524 | For simplicity, we talk about CPU contention as if there is only one CPU | |
525 | in the system. But all the same principles apply when a processor has | |
526 | multiple CPUs, and knowing that the number of processes that can run at | |
527 | any one time is equal to the number of CPUs, you can easily extrapolate | |
528 | the information. | |
529 | ||
530 | The functions described in this section are all defined by the POSIX.1 | |
95fdc6a0 | 531 | and POSIX.1b standards (the @code{sched@dots{}} functions are POSIX.1b). |
639c6286 UD |
532 | However, POSIX does not define any semantics for the values that these |
533 | functions get and set. In this chapter, the semantics are based on the | |
534 | Linux kernel's implementation of the POSIX standard. As you will see, | |
535 | the Linux implementation is quite the inverse of what the authors of the | |
536 | POSIX syntax had in mind. | |
537 | ||
538 | @menu | |
539 | * Absolute Priority:: The first tier of priority. Posix | |
540 | * Realtime Scheduling:: Scheduling among the process nobility | |
541 | * Basic Scheduling Functions:: Get/set scheduling policy, priority | |
542 | * Traditional Scheduling:: Scheduling among the vulgar masses | |
d9997a45 | 543 | * CPU Affinity:: Limiting execution to certain CPUs |
639c6286 UD |
544 | @end menu |
545 | ||
546 | ||
547 | ||
548 | @node Absolute Priority | |
549 | @subsection Absolute Priority | |
550 | @cindex absolute priority | |
551 | @cindex priority, absolute | |
552 | ||
553 | Every process has an absolute priority, and it is represented by a number. | |
554 | The higher the number, the higher the absolute priority. | |
555 | ||
556 | @cindex realtime CPU scheduling | |
557 | On systems of the past, and most systems today, all processes have | |
558 | absolute priority 0 and this section is irrelevant. In that case, | |
559 | @xref{Traditional Scheduling}. Absolute priorities were invented to | |
0bc93a2f | 560 | accommodate realtime systems, in which it is vital that certain processes |
639c6286 UD |
561 | be able to respond to external events happening in real time, which |
562 | means they cannot wait around while some other process that @emph{wants | |
563 | to}, but doesn't @emph{need to} run occupies the CPU. | |
564 | ||
565 | @cindex ready to run | |
566 | @cindex preemptive scheduling | |
567 | When two processes are in contention to use the CPU at any instant, the | |
568 | one with the higher absolute priority always gets it. This is true even if the | |
11bf311e | 569 | process with the lower priority is already using the CPU (i.e., the |
639c6286 UD |
570 | scheduling is preemptive). Of course, we're only talking about |
571 | processes that are running or ``ready to run,'' which means they are | |
572 | ready to execute instructions right now. When a process blocks to wait | |
573 | for something like I/O, its absolute priority is irrelevant. | |
574 | ||
575 | @cindex runnable process | |
48b22986 | 576 | @strong{NB:} The term ``runnable'' is a synonym for ``ready to run.'' |
639c6286 UD |
577 | |
578 | When two processes are running or ready to run and both have the same | |
579 | absolute priority, it's more interesting. In that case, who gets the | |
0bc93a2f | 580 | CPU is determined by the scheduling policy. If the processes have |
639c6286 UD |
581 | absolute priority 0, the traditional scheduling policy described in |
582 | @ref{Traditional Scheduling} applies. Otherwise, the policies described | |
583 | in @ref{Realtime Scheduling} apply. | |
584 | ||
585 | You normally give an absolute priority above 0 only to a process that | |
586 | can be trusted not to hog the CPU. Such processes are designed to block | |
587 | (or terminate) after relatively short CPU runs. | |
588 | ||
589 | A process begins life with the same absolute priority as its parent | |
590 | process. Functions described in @ref{Basic Scheduling Functions} can | |
591 | change it. | |
592 | ||
593 | Only a privileged process can change a process' absolute priority to | |
594 | something other than @code{0}. Only a privileged process or the | |
595 | target process' owner can change its absolute priority at all. | |
596 | ||
597 | POSIX requires absolute priority values used with the realtime | |
598 | scheduling policies to be consecutive with a range of at least 32. On | |
599 | Linux, they are 1 through 99. The functions | |
600 | @code{sched_get_priority_max} and @code{sched_set_priority_min} portably | |
601 | tell you what the range is on a particular system. | |
602 | ||
603 | ||
604 | @subsubsection Using Absolute Priority | |
605 | ||
606 | One thing you must keep in mind when designing real time applications is | |
607 | that having higher absolute priority than any other process doesn't | |
608 | guarantee the process can run continuously. Two things that can wreck a | |
87b56f36 | 609 | good CPU run are interrupts and page faults. |
639c6286 UD |
610 | |
611 | Interrupt handlers live in that limbo between processes. The CPU is | |
612 | executing instructions, but they aren't part of any process. An | |
613 | interrupt will stop even the highest priority process. So you must | |
614 | allow for slight delays and make sure that no device in the system has | |
615 | an interrupt handler that could cause too long a delay between | |
616 | instructions for your process. | |
617 | ||
618 | Similarly, a page fault causes what looks like a straightforward | |
619 | sequence of instructions to take a long time. The fact that other | |
620 | processes get to run while the page faults in is of no consequence, | |
d3e22d59 | 621 | because as soon as the I/O is complete, the higher priority process will |
639c6286 UD |
622 | kick them out and run again, but the wait for the I/O itself could be a |
623 | problem. To neutralize this threat, use @code{mlock} or | |
624 | @code{mlockall}. | |
625 | ||
626 | There are a few ramifications of the absoluteness of this priority on a | |
627 | single-CPU system that you need to keep in mind when you choose to set a | |
628 | priority and also when you're working on a program that runs with high | |
629 | absolute priority. Consider a process that has higher absolute priority | |
630 | than any other process in the system and due to a bug in its program, it | |
631 | gets into an infinite loop. It will never cede the CPU. You can't run | |
632 | a command to kill it because your command would need to get the CPU in | |
633 | order to run. The errant program is in complete control. It controls | |
634 | the vertical, it controls the horizontal. | |
635 | ||
636 | There are two ways to avoid this: 1) keep a shell running somewhere with | |
d3e22d59 | 637 | a higher absolute priority or 2) keep a controlling terminal attached to |
639c6286 UD |
638 | the high priority process group. All the priority in the world won't |
639 | stop an interrupt handler from running and delivering a signal to the | |
640 | process if you hit Control-C. | |
641 | ||
95fdc6a0 | 642 | Some systems use absolute priority as a means of allocating a fixed |
0bc93a2f | 643 | percentage of CPU time to a process. To do this, a super high priority |
639c6286 UD |
644 | privileged process constantly monitors the process' CPU usage and raises |
645 | its absolute priority when the process isn't getting its entitled share | |
646 | and lowers it when the process is exceeding it. | |
647 | ||
48b22986 | 648 | @strong{NB:} The absolute priority is sometimes called the ``static |
639c6286 UD |
649 | priority.'' We don't use that term in this manual because it misses the |
650 | most important feature of the absolute priority: its absoluteness. | |
651 | ||
652 | ||
653 | @node Realtime Scheduling | |
654 | @subsection Realtime Scheduling | |
b642f101 | 655 | @cindex realtime scheduling |
639c6286 UD |
656 | |
657 | Whenever two processes with the same absolute priority are ready to run, | |
658 | the kernel has a decision to make, because only one can run at a time. | |
659 | If the processes have absolute priority 0, the kernel makes this decision | |
660 | as described in @ref{Traditional Scheduling}. Otherwise, the decision | |
661 | is as described in this section. | |
662 | ||
663 | If two processes are ready to run but have different absolute priorities, | |
664 | the decision is much simpler, and is described in @ref{Absolute | |
665 | Priority}. | |
666 | ||
87b56f36 | 667 | Each process has a scheduling policy. For processes with absolute |
639c6286 UD |
668 | priority other than zero, there are two available: |
669 | ||
670 | @enumerate | |
671 | @item | |
672 | First Come First Served | |
673 | @item | |
674 | Round Robin | |
675 | @end enumerate | |
676 | ||
677 | The most sensible case is where all the processes with a certain | |
678 | absolute priority have the same scheduling policy. We'll discuss that | |
679 | first. | |
680 | ||
681 | In Round Robin, processes share the CPU, each one running for a small | |
682 | quantum of time (``time slice'') and then yielding to another in a | |
683 | circular fashion. Of course, only processes that are ready to run and | |
684 | have the same absolute priority are in this circle. | |
685 | ||
686 | In First Come First Served, the process that has been waiting the | |
687 | longest to run gets the CPU, and it keeps it until it voluntarily | |
688 | relinquishes the CPU, runs out of things to do (blocks), or gets | |
689 | preempted by a higher priority process. | |
690 | ||
691 | First Come First Served, along with maximal absolute priority and | |
692 | careful control of interrupts and page faults, is the one to use when a | |
693 | process absolutely, positively has to run at full CPU speed or not at | |
694 | all. | |
695 | ||
696 | Judicious use of @code{sched_yield} function invocations by processes | |
697 | with First Come First Served scheduling policy forms a good compromise | |
698 | between Round Robin and First Come First Served. | |
699 | ||
700 | To understand how scheduling works when processes of different scheduling | |
701 | policies occupy the same absolute priority, you have to know the nitty | |
d3e22d59 | 702 | gritty details of how processes enter and exit the ready to run list. |
639c6286 UD |
703 | |
704 | In both cases, the ready to run list is organized as a true queue, where | |
705 | a process gets pushed onto the tail when it becomes ready to run and is | |
706 | popped off the head when the scheduler decides to run it. Note that | |
707 | ready to run and running are two mutually exclusive states. When the | |
708 | scheduler runs a process, that process is no longer ready to run and no | |
709 | longer in the ready to run list. When the process stops running, it | |
710 | may go back to being ready to run again. | |
711 | ||
712 | The only difference between a process that is assigned the Round Robin | |
713 | scheduling policy and a process that is assigned First Come First Serve | |
714 | is that in the former case, the process is automatically booted off the | |
715 | CPU after a certain amount of time. When that happens, the process goes | |
716 | back to being ready to run, which means it enters the queue at the tail. | |
717 | The time quantum we're talking about is small. Really small. This is | |
718 | not your father's timesharing. For example, with the Linux kernel, the | |
719 | round robin time slice is a thousand times shorter than its typical | |
720 | time slice for traditional scheduling. | |
721 | ||
722 | A process begins life with the same scheduling policy as its parent process. | |
723 | Functions described in @ref{Basic Scheduling Functions} can change it. | |
724 | ||
725 | Only a privileged process can set the scheduling policy of a process | |
726 | that has absolute priority higher than 0. | |
727 | ||
728 | @node Basic Scheduling Functions | |
729 | @subsection Basic Scheduling Functions | |
730 | ||
1f77f049 | 731 | This section describes functions in @theglibc{} for setting the |
639c6286 UD |
732 | absolute priority and scheduling policy of a process. |
733 | ||
734 | @strong{Portability Note:} On systems that have the functions in this | |
735 | section, the macro _POSIX_PRIORITY_SCHEDULING is defined in | |
736 | @file{<unistd.h>}. | |
737 | ||
738 | For the case that the scheduling policy is traditional scheduling, more | |
739 | functions to fine tune the scheduling are in @ref{Traditional Scheduling}. | |
740 | ||
741 | Don't try to make too much out of the naming and structure of these | |
742 | functions. They don't match the concepts described in this manual | |
743 | because the functions are as defined by POSIX.1b, but the implementation | |
1f77f049 | 744 | on systems that use @theglibc{} is the inverse of what the POSIX |
639c6286 UD |
745 | structure contemplates. The POSIX scheme assumes that the primary |
746 | scheduling parameter is the scheduling policy and that the priority | |
747 | value, if any, is a parameter of the scheduling policy. In the | |
748 | implementation, though, the priority value is king and the scheduling | |
749 | policy, if anything, only fine tunes the effect of that priority. | |
750 | ||
751 | The symbols in this section are declared by including file @file{sched.h}. | |
752 | ||
639c6286 | 753 | @deftp {Data Type} {struct sched_param} |
d08a7e4c | 754 | @standards{POSIX, sched.h} |
639c6286 UD |
755 | This structure describes an absolute priority. |
756 | @table @code | |
757 | @item int sched_priority | |
758 | absolute priority value | |
759 | @end table | |
760 | @end deftp | |
761 | ||
639c6286 | 762 | @deftypefun int sched_setscheduler (pid_t @var{pid}, int @var{policy}, const struct sched_param *@var{param}) |
d08a7e4c | 763 | @standards{POSIX, sched.h} |
c8ce789c AO |
764 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
765 | @c Direct syscall, Linux only. | |
639c6286 UD |
766 | |
767 | This function sets both the absolute priority and the scheduling policy | |
768 | for a process. | |
769 | ||
770 | It assigns the absolute priority value given by @var{param} and the | |
771 | scheduling policy @var{policy} to the process with Process ID @var{pid}, | |
772 | or the calling process if @var{pid} is zero. If @var{policy} is | |
0bc93a2f | 773 | negative, @code{sched_setscheduler} keeps the existing scheduling policy. |
639c6286 UD |
774 | |
775 | The following macros represent the valid values for @var{policy}: | |
776 | ||
2fe82ca6 | 777 | @vtable @code |
639c6286 UD |
778 | @item SCHED_OTHER |
779 | Traditional Scheduling | |
780 | @item SCHED_FIFO | |
87b56f36 | 781 | First In First Out |
639c6286 UD |
782 | @item SCHED_RR |
783 | Round Robin | |
2fe82ca6 | 784 | @end vtable |
639c6286 UD |
785 | |
786 | @c The Linux kernel code (in sched.c) actually reschedules the process, | |
787 | @c but it puts it at the head of the run queue, so I'm not sure just what | |
788 | @c the effect is, but it must be subtle. | |
789 | ||
790 | On success, the return value is @code{0}. Otherwise, it is @code{-1} | |
791 | and @code{ERRNO} is set accordingly. The @code{errno} values specific | |
792 | to this function are: | |
793 | ||
794 | @table @code | |
795 | @item EPERM | |
796 | @itemize @bullet | |
797 | @item | |
798 | The calling process does not have @code{CAP_SYS_NICE} permission and | |
799 | @var{policy} is not @code{SCHED_OTHER} (or it's negative and the | |
800 | existing policy is not @code{SCHED_OTHER}. | |
801 | ||
802 | @item | |
803 | The calling process does not have @code{CAP_SYS_NICE} permission and its | |
11bf311e | 804 | owner is not the target process' owner. I.e., the effective uid of the |
639c6286 UD |
805 | calling process is neither the effective nor the real uid of process |
806 | @var{pid}. | |
807 | @c We need a cross reference to the capabilities section, when written. | |
808 | @end itemize | |
809 | ||
810 | @item ESRCH | |
811 | There is no process with pid @var{pid} and @var{pid} is not zero. | |
812 | ||
813 | @item EINVAL | |
814 | @itemize @bullet | |
815 | @item | |
816 | @var{policy} does not identify an existing scheduling policy. | |
817 | ||
818 | @item | |
819 | The absolute priority value identified by *@var{param} is outside the | |
820 | valid range for the scheduling policy @var{policy} (or the existing | |
821 | scheduling policy if @var{policy} is negative) or @var{param} is | |
822 | null. @code{sched_get_priority_max} and @code{sched_get_priority_min} | |
823 | tell you what the valid range is. | |
824 | ||
825 | @item | |
826 | @var{pid} is negative. | |
827 | @end itemize | |
828 | @end table | |
829 | ||
830 | @end deftypefun | |
831 | ||
832 | ||
639c6286 | 833 | @deftypefun int sched_getscheduler (pid_t @var{pid}) |
d08a7e4c | 834 | @standards{POSIX, sched.h} |
c8ce789c AO |
835 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
836 | @c Direct syscall, Linux only. | |
639c6286 UD |
837 | |
838 | This function returns the scheduling policy assigned to the process with | |
839 | Process ID (pid) @var{pid}, or the calling process if @var{pid} is zero. | |
840 | ||
841 | The return value is the scheduling policy. See | |
842 | @code{sched_setscheduler} for the possible values. | |
843 | ||
844 | If the function fails, the return value is instead @code{-1} and | |
845 | @code{errno} is set accordingly. | |
846 | ||
847 | The @code{errno} values specific to this function are: | |
848 | ||
849 | @table @code | |
850 | ||
851 | @item ESRCH | |
852 | There is no process with pid @var{pid} and it is not zero. | |
853 | ||
854 | @item EINVAL | |
855 | @var{pid} is negative. | |
856 | ||
857 | @end table | |
858 | ||
859 | Note that this function is not an exact mate to @code{sched_setscheduler} | |
860 | because while that function sets the scheduling policy and the absolute | |
861 | priority, this function gets only the scheduling policy. To get the | |
862 | absolute priority, use @code{sched_getparam}. | |
863 | ||
864 | @end deftypefun | |
865 | ||
866 | ||
639c6286 | 867 | @deftypefun int sched_setparam (pid_t @var{pid}, const struct sched_param *@var{param}) |
d08a7e4c | 868 | @standards{POSIX, sched.h} |
c8ce789c AO |
869 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
870 | @c Direct syscall, Linux only. | |
639c6286 UD |
871 | |
872 | This function sets a process' absolute priority. | |
873 | ||
874 | It is functionally identical to @code{sched_setscheduler} with | |
875 | @var{policy} = @code{-1}. | |
876 | ||
877 | @c in fact, that's how it's implemented in Linux. | |
878 | ||
879 | @end deftypefun | |
880 | ||
8ded91fb | 881 | @deftypefun int sched_getparam (pid_t @var{pid}, struct sched_param *@var{param}) |
d08a7e4c | 882 | @standards{POSIX, sched.h} |
c8ce789c AO |
883 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
884 | @c Direct syscall, Linux only. | |
639c6286 UD |
885 | |
886 | This function returns a process' absolute priority. | |
887 | ||
888 | @var{pid} is the Process ID (pid) of the process whose absolute priority | |
889 | you want to know. | |
890 | ||
891 | @var{param} is a pointer to a structure in which the function stores the | |
892 | absolute priority of the process. | |
893 | ||
894 | On success, the return value is @code{0}. Otherwise, it is @code{-1} | |
d3e22d59 | 895 | and @code{errno} is set accordingly. The @code{errno} values specific |
639c6286 UD |
896 | to this function are: |
897 | ||
898 | @table @code | |
899 | ||
900 | @item ESRCH | |
901 | There is no process with pid @var{pid} and it is not zero. | |
902 | ||
903 | @item EINVAL | |
904 | @var{pid} is negative. | |
905 | ||
906 | @end table | |
907 | ||
908 | @end deftypefun | |
909 | ||
910 | ||
8ded91fb | 911 | @deftypefun int sched_get_priority_min (int @var{policy}) |
d08a7e4c | 912 | @standards{POSIX, sched.h} |
c8ce789c AO |
913 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
914 | @c Direct syscall, Linux only. | |
639c6286 UD |
915 | |
916 | This function returns the lowest absolute priority value that is | |
917 | allowable for a process with scheduling policy @var{policy}. | |
918 | ||
919 | On Linux, it is 0 for SCHED_OTHER and 1 for everything else. | |
920 | ||
921 | On success, the return value is @code{0}. Otherwise, it is @code{-1} | |
922 | and @code{ERRNO} is set accordingly. The @code{errno} values specific | |
923 | to this function are: | |
924 | ||
925 | @table @code | |
926 | @item EINVAL | |
927 | @var{policy} does not identify an existing scheduling policy. | |
928 | @end table | |
929 | ||
930 | @end deftypefun | |
931 | ||
8ded91fb | 932 | @deftypefun int sched_get_priority_max (int @var{policy}) |
d08a7e4c | 933 | @standards{POSIX, sched.h} |
c8ce789c AO |
934 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
935 | @c Direct syscall, Linux only. | |
639c6286 UD |
936 | |
937 | This function returns the highest absolute priority value that is | |
938 | allowable for a process that with scheduling policy @var{policy}. | |
939 | ||
940 | On Linux, it is 0 for SCHED_OTHER and 99 for everything else. | |
941 | ||
942 | On success, the return value is @code{0}. Otherwise, it is @code{-1} | |
943 | and @code{ERRNO} is set accordingly. The @code{errno} values specific | |
944 | to this function are: | |
945 | ||
946 | @table @code | |
947 | @item EINVAL | |
948 | @var{policy} does not identify an existing scheduling policy. | |
949 | @end table | |
950 | ||
951 | @end deftypefun | |
952 | ||
639c6286 | 953 | @deftypefun int sched_rr_get_interval (pid_t @var{pid}, struct timespec *@var{interval}) |
d08a7e4c | 954 | @standards{POSIX, sched.h} |
c8ce789c AO |
955 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
956 | @c Direct syscall, Linux only. | |
639c6286 | 957 | |
87b56f36 | 958 | This function returns the length of the quantum (time slice) used with |
639c6286 UD |
959 | the Round Robin scheduling policy, if it is used, for the process with |
960 | Process ID @var{pid}. | |
961 | ||
87b56f36 | 962 | It returns the length of time as @var{interval}. |
639c6286 UD |
963 | @c We need a cross-reference to where timespec is explained. But that |
964 | @c section doesn't exist yet, and the time chapter needs to be slightly | |
965 | @c reorganized so there is a place to put it (which will be right next | |
966 | @c to timeval, which is presently misplaced). 2000.05.07. | |
967 | ||
968 | With a Linux kernel, the round robin time slice is always 150 | |
969 | microseconds, and @var{pid} need not even be a real pid. | |
970 | ||
971 | The return value is @code{0} on success and in the pathological case | |
972 | that it fails, the return value is @code{-1} and @code{errno} is set | |
973 | accordingly. There is nothing specific that can go wrong with this | |
974 | function, so there are no specific @code{errno} values. | |
975 | ||
976 | @end deftypefun | |
977 | ||
3c44837c | 978 | @deftypefun int sched_yield (void) |
d08a7e4c | 979 | @standards{POSIX, sched.h} |
c8ce789c AO |
980 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
981 | @c Direct syscall on Linux; alias to swtch on HURD. | |
639c6286 UD |
982 | |
983 | This function voluntarily gives up the process' claim on the CPU. | |
984 | ||
985 | Technically, @code{sched_yield} causes the calling process to be made | |
986 | immediately ready to run (as opposed to running, which is what it was | |
987 | before). This means that if it has absolute priority higher than 0, it | |
988 | gets pushed onto the tail of the queue of processes that share its | |
989 | absolute priority and are ready to run, and it will run again when its | |
990 | turn next arrives. If its absolute priority is 0, it is more | |
991 | complicated, but still has the effect of yielding the CPU to other | |
992 | processes. | |
993 | ||
994 | If there are no other processes that share the calling process' absolute | |
995 | priority, this function doesn't have any effect. | |
996 | ||
997 | To the extent that the containing program is oblivious to what other | |
998 | processes in the system are doing and how fast it executes, this | |
999 | function appears as a no-op. | |
1000 | ||
1001 | The return value is @code{0} on success and in the pathological case | |
1002 | that it fails, the return value is @code{-1} and @code{errno} is set | |
1003 | accordingly. There is nothing specific that can go wrong with this | |
1004 | function, so there are no specific @code{errno} values. | |
1005 | ||
1006 | @end deftypefun | |
1007 | ||
1008 | @node Traditional Scheduling | |
1009 | @subsection Traditional Scheduling | |
1010 | @cindex scheduling, traditional | |
1011 | ||
1012 | This section is about the scheduling among processes whose absolute | |
1013 | priority is 0. When the system hands out the scraps of CPU time that | |
0bc93a2f | 1014 | are left over after the processes with higher absolute priority have |
639c6286 UD |
1015 | taken all they want, the scheduling described herein determines who |
1016 | among the great unwashed processes gets them. | |
1017 | ||
1018 | @menu | |
1019 | * Traditional Scheduling Intro:: | |
1020 | * Traditional Scheduling Functions:: | |
1021 | @end menu | |
1022 | ||
1023 | @node Traditional Scheduling Intro | |
1024 | @subsubsection Introduction To Traditional Scheduling | |
1025 | ||
1026 | Long before there was absolute priority (See @ref{Absolute Priority}), | |
d3e22d59 | 1027 | Unix systems were scheduling the CPU using this system. When POSIX came |
0bc93a2f | 1028 | in like the Romans and imposed absolute priorities to accommodate the |
639c6286 UD |
1029 | needs of realtime processing, it left the indigenous Absolute Priority |
1030 | Zero processes to govern themselves by their own familiar scheduling | |
1031 | policy. | |
1032 | ||
1033 | Indeed, absolute priorities higher than zero are not available on many | |
1034 | systems today and are not typically used when they are, being intended | |
1035 | mainly for computers that do realtime processing. So this section | |
1036 | describes the only scheduling many programmers need to be concerned | |
1037 | about. | |
1038 | ||
1039 | But just to be clear about the scope of this scheduling: Any time a | |
9dcc8f11 | 1040 | process with an absolute priority of 0 and a process with an absolute |
639c6286 UD |
1041 | priority higher than 0 are ready to run at the same time, the one with |
1042 | absolute priority 0 does not run. If it's already running when the | |
1043 | higher priority ready-to-run process comes into existence, it stops | |
1044 | immediately. | |
1045 | ||
1046 | In addition to its absolute priority of zero, every process has another | |
1047 | priority, which we will refer to as "dynamic priority" because it changes | |
87b56f36 | 1048 | over time. The dynamic priority is meaningless for processes with |
639c6286 UD |
1049 | an absolute priority higher than zero. |
1050 | ||
1051 | The dynamic priority sometimes determines who gets the next turn on the | |
1052 | CPU. Sometimes it determines how long turns last. Sometimes it | |
1053 | determines whether a process can kick another off the CPU. | |
1054 | ||
d3e22d59 | 1055 | In Linux, the value is a combination of these things, but mostly it |
639c6286 UD |
1056 | just determines the length of the time slice. The higher a process' |
1057 | dynamic priority, the longer a shot it gets on the CPU when it gets one. | |
1058 | If it doesn't use up its time slice before giving up the CPU to do | |
1059 | something like wait for I/O, it is favored for getting the CPU back when | |
1060 | it's ready for it, to finish out its time slice. Other than that, | |
1061 | selection of processes for new time slices is basically round robin. | |
1062 | But the scheduler does throw a bone to the low priority processes: A | |
1063 | process' dynamic priority rises every time it is snubbed in the | |
1064 | scheduling process. In Linux, even the fat kid gets to play. | |
1065 | ||
1066 | The fluctuation of a process' dynamic priority is regulated by another | |
1067 | value: The ``nice'' value. The nice value is an integer, usually in the | |
1068 | range -20 to 20, and represents an upper limit on a process' dynamic | |
1069 | priority. The higher the nice number, the lower that limit. | |
1070 | ||
1071 | On a typical Linux system, for example, a process with a nice value of | |
1072 | 20 can get only 10 milliseconds on the CPU at a time, whereas a process | |
1073 | with a nice value of -20 can achieve a high enough priority to get 400 | |
1074 | milliseconds. | |
1075 | ||
1076 | The idea of the nice value is deferential courtesy. In the beginning, | |
1077 | in the Unix garden of Eden, all processes shared equally in the bounty | |
1078 | of the computer system. But not all processes really need the same | |
1079 | share of CPU time, so the nice value gave a courteous process the | |
1080 | ability to refuse its equal share of CPU time that others might prosper. | |
1081 | Hence, the higher a process' nice value, the nicer the process is. | |
1082 | (Then a snake came along and offered some process a negative nice value | |
1083 | and the system became the crass resource allocation system we know | |
d3e22d59 | 1084 | today.) |
639c6286 UD |
1085 | |
1086 | Dynamic priorities tend upward and downward with an objective of | |
1087 | smoothing out allocation of CPU time and giving quick response time to | |
1088 | infrequent requests. But they never exceed their nice limits, so on a | |
1089 | heavily loaded CPU, the nice value effectively determines how fast a | |
1090 | process runs. | |
1091 | ||
1092 | In keeping with the socialistic heritage of Unix process priority, a | |
1093 | process begins life with the same nice value as its parent process and | |
1094 | can raise it at will. A process can also raise the nice value of any | |
1095 | other process owned by the same user (or effective user). But only a | |
1096 | privileged process can lower its nice value. A privileged process can | |
1097 | also raise or lower another process' nice value. | |
1098 | ||
1f77f049 | 1099 | @glibcadj{} functions for getting and setting nice values are described in |
639c6286 UD |
1100 | @xref{Traditional Scheduling Functions}. |
1101 | ||
1102 | @node Traditional Scheduling Functions | |
1103 | @subsubsection Functions For Traditional Scheduling | |
1104 | ||
5ce8f203 | 1105 | @pindex sys/resource.h |
639c6286 UD |
1106 | This section describes how you can read and set the nice value of a |
1107 | process. All these symbols are declared in @file{sys/resource.h}. | |
1108 | ||
1109 | The function and macro names are defined by POSIX, and refer to | |
1110 | "priority," but the functions actually have to do with nice values, as | |
1111 | the terms are used both in the manual and POSIX. | |
1112 | ||
1113 | The range of valid nice values depends on the kernel, but typically it | |
1114 | runs from @code{-20} to @code{20}. A lower nice value corresponds to | |
1115 | higher priority for the process. These constants describe the range of | |
5ce8f203 UD |
1116 | priority values: |
1117 | ||
b642f101 | 1118 | @vtable @code |
5ce8f203 | 1119 | @item PRIO_MIN |
d08a7e4c | 1120 | @standards{BSD, sys/resource.h} |
639c6286 | 1121 | The lowest valid nice value. |
5ce8f203 | 1122 | |
5ce8f203 | 1123 | @item PRIO_MAX |
d08a7e4c | 1124 | @standards{BSD, sys/resource.h} |
639c6286 | 1125 | The highest valid nice value. |
b642f101 | 1126 | @end vtable |
5ce8f203 | 1127 | |
5ce8f203 | 1128 | @deftypefun int getpriority (int @var{class}, int @var{id}) |
d08a7e4c RJ |
1129 | @standards{BSD, sys/resource.h} |
1130 | @standards{POSIX, sys/resource.h} | |
c8ce789c AO |
1131 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1132 | @c Direct syscall on UNIX. On HURD, calls _hurd_priority_which_map. | |
639c6286 | 1133 | Return the nice value of a set of processes; @var{class} and @var{id} |
5ce8f203 | 1134 | specify which ones (see below). If the processes specified do not all |
639c6286 | 1135 | have the same nice value, this returns the lowest value that any of them |
5ce8f203 UD |
1136 | has. |
1137 | ||
639c6286 | 1138 | On success, the return value is @code{0}. Otherwise, it is @code{-1} |
d3e22d59 | 1139 | and @code{errno} is set accordingly. The @code{errno} values specific |
639c6286 | 1140 | to this function are: |
5ce8f203 UD |
1141 | |
1142 | @table @code | |
1143 | @item ESRCH | |
1144 | The combination of @var{class} and @var{id} does not match any existing | |
1145 | process. | |
1146 | ||
1147 | @item EINVAL | |
1148 | The value of @var{class} is not valid. | |
1149 | @end table | |
1150 | ||
639c6286 UD |
1151 | If the return value is @code{-1}, it could indicate failure, or it could |
1152 | be the nice value. The only way to make certain is to set @code{errno = | |
1153 | 0} before calling @code{getpriority}, then use @code{errno != 0} | |
1154 | afterward as the criterion for failure. | |
5ce8f203 UD |
1155 | @end deftypefun |
1156 | ||
639c6286 | 1157 | @deftypefun int setpriority (int @var{class}, int @var{id}, int @var{niceval}) |
d08a7e4c RJ |
1158 | @standards{BSD, sys/resource.h} |
1159 | @standards{POSIX, sys/resource.h} | |
c8ce789c AO |
1160 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1161 | @c Direct syscall on UNIX. On HURD, calls _hurd_priority_which_map. | |
639c6286 | 1162 | Set the nice value of a set of processes to @var{niceval}; @var{class} |
5ce8f203 UD |
1163 | and @var{id} specify which ones (see below). |
1164 | ||
6a7a8b22 | 1165 | The return value is @code{0} on success, and @code{-1} on |
639c6286 UD |
1166 | failure. The following @code{errno} error condition are possible for |
1167 | this function: | |
5ce8f203 UD |
1168 | |
1169 | @table @code | |
1170 | @item ESRCH | |
1171 | The combination of @var{class} and @var{id} does not match any existing | |
1172 | process. | |
1173 | ||
1174 | @item EINVAL | |
1175 | The value of @var{class} is not valid. | |
1176 | ||
1177 | @item EPERM | |
639c6286 | 1178 | The call would set the nice value of a process which is owned by a different |
11bf311e | 1179 | user than the calling process (i.e., the target process' real or effective |
639c6286 UD |
1180 | uid does not match the calling process' effective uid) and the calling |
1181 | process does not have @code{CAP_SYS_NICE} permission. | |
5ce8f203 UD |
1182 | |
1183 | @item EACCES | |
639c6286 UD |
1184 | The call would lower the process' nice value and the process does not have |
1185 | @code{CAP_SYS_NICE} permission. | |
5ce8f203 | 1186 | @end table |
639c6286 | 1187 | |
5ce8f203 UD |
1188 | @end deftypefun |
1189 | ||
1190 | The arguments @var{class} and @var{id} together specify a set of | |
1191 | processes in which you are interested. These are the possible values of | |
1192 | @var{class}: | |
1193 | ||
b642f101 | 1194 | @vtable @code |
5ce8f203 | 1195 | @item PRIO_PROCESS |
d08a7e4c | 1196 | @standards{BSD, sys/resource.h} |
639c6286 | 1197 | One particular process. The argument @var{id} is a process ID (pid). |
5ce8f203 | 1198 | |
5ce8f203 | 1199 | @item PRIO_PGRP |
d08a7e4c | 1200 | @standards{BSD, sys/resource.h} |
639c6286 UD |
1201 | All the processes in a particular process group. The argument @var{id} is |
1202 | a process group ID (pgid). | |
5ce8f203 | 1203 | |
5ce8f203 | 1204 | @item PRIO_USER |
d08a7e4c | 1205 | @standards{BSD, sys/resource.h} |
11bf311e | 1206 | All the processes owned by a particular user (i.e., whose real uid |
639c6286 | 1207 | indicates the user). The argument @var{id} is a user ID (uid). |
b642f101 | 1208 | @end vtable |
5ce8f203 | 1209 | |
639c6286 UD |
1210 | If the argument @var{id} is 0, it stands for the calling process, its |
1211 | process group, or its owner (real uid), according to @var{class}. | |
5ce8f203 | 1212 | |
5ce8f203 | 1213 | @deftypefun int nice (int @var{increment}) |
d08a7e4c | 1214 | @standards{BSD, unistd.h} |
c8ce789c AO |
1215 | @safety{@prelim{}@mtunsafe{@mtasurace{:setpriority}}@asunsafe{}@acsafe{}} |
1216 | @c Calls getpriority before and after setpriority, using the result of | |
1217 | @c the first call to compute the argument for setpriority. This creates | |
1218 | @c a window for a concurrent setpriority (or nice) call to be lost or | |
1219 | @c exhibit surprising behavior. | |
639c6286 | 1220 | Increment the nice value of the calling process by @var{increment}. |
6a7a8b22 AJ |
1221 | The return value is the new nice value on success, and @code{-1} on |
1222 | failure. In the case of failure, @code{errno} will be set to the | |
1223 | same values as for @code{setpriority}. | |
1224 | ||
5ce8f203 UD |
1225 | |
1226 | Here is an equivalent definition of @code{nice}: | |
1227 | ||
1228 | @smallexample | |
1229 | int | |
1230 | nice (int increment) | |
1231 | @{ | |
6a7a8b22 AJ |
1232 | int result, old = getpriority (PRIO_PROCESS, 0); |
1233 | result = setpriority (PRIO_PROCESS, 0, old + increment); | |
1234 | if (result != -1) | |
1235 | return old + increment; | |
1236 | else | |
1237 | return -1; | |
5ce8f203 UD |
1238 | @} |
1239 | @end smallexample | |
1240 | @end deftypefun | |
b642f101 | 1241 | |
d9997a45 UD |
1242 | |
1243 | @node CPU Affinity | |
1244 | @subsection Limiting execution to certain CPUs | |
1245 | ||
1246 | On a multi-processor system the operating system usually distributes | |
1247 | the different processes which are runnable on all available CPUs in a | |
1248 | way which allows the system to work most efficiently. Which processes | |
1249 | and threads run can be to some extend be control with the scheduling | |
1250 | functionality described in the last sections. But which CPU finally | |
1251 | executes which process or thread is not covered. | |
1252 | ||
1253 | There are a number of reasons why a program might want to have control | |
1254 | over this aspect of the system as well: | |
1255 | ||
1256 | @itemize @bullet | |
1257 | @item | |
1258 | One thread or process is responsible for absolutely critical work | |
1259 | which under no circumstances must be interrupted or hindered from | |
d3e22d59 | 1260 | making progress by other processes or threads using CPU resources. In |
d9997a45 UD |
1261 | this case the special process would be confined to a CPU which no |
1262 | other process or thread is allowed to use. | |
1263 | ||
1264 | @item | |
1265 | The access to certain resources (RAM, I/O ports) has different costs | |
1266 | from different CPUs. This is the case in NUMA (Non-Uniform Memory | |
11bf311e | 1267 | Architecture) machines. Preferably memory should be accessed locally |
d9997a45 UD |
1268 | but this requirement is usually not visible to the scheduler. |
1269 | Therefore forcing a process or thread to the CPUs which have local | |
d3e22d59 | 1270 | access to the most-used memory helps to significantly boost the |
d9997a45 UD |
1271 | performance. |
1272 | ||
1273 | @item | |
1274 | In controlled runtimes resource allocation and book-keeping work (for | |
1275 | instance garbage collection) is performance local to processors. This | |
1276 | can help to reduce locking costs if the resources do not have to be | |
1277 | protected from concurrent accesses from different processors. | |
1278 | @end itemize | |
1279 | ||
1280 | The POSIX standard up to this date is of not much help to solve this | |
1281 | problem. The Linux kernel provides a set of interfaces to allow | |
1282 | specifying @emph{affinity sets} for a process. The scheduler will | |
bbf70ae9 | 1283 | schedule the thread or process on CPUs specified by the affinity |
1f77f049 | 1284 | masks. The interfaces which @theglibc{} define follow to some |
d3e22d59 | 1285 | extent the Linux kernel interface. |
d9997a45 | 1286 | |
d9997a45 | 1287 | @deftp {Data Type} cpu_set_t |
d08a7e4c | 1288 | @standards{GNU, sched.h} |
d9997a45 UD |
1289 | This data set is a bitset where each bit represents a CPU. How the |
1290 | system's CPUs are mapped to bits in the bitset is system dependent. | |
1291 | The data type has a fixed size; in the unlikely case that the number | |
1292 | of bits are not sufficient to describe the CPUs of the system a | |
1293 | different interface has to be used. | |
1294 | ||
1295 | This type is a GNU extension and is defined in @file{sched.h}. | |
1296 | @end deftp | |
1297 | ||
d3e22d59 | 1298 | To manipulate the bitset, to set and reset bits, a number of macros are |
d9997a45 UD |
1299 | defined. Some of the macros take a CPU number as a parameter. Here |
1300 | it is important to never exceed the size of the bitset. The following | |
1301 | macro specifies the number of bits in the @code{cpu_set_t} bitset. | |
1302 | ||
d9997a45 | 1303 | @deftypevr Macro int CPU_SETSIZE |
d08a7e4c | 1304 | @standards{GNU, sched.h} |
d9997a45 UD |
1305 | The value of this macro is the maximum number of CPUs which can be |
1306 | handled with a @code{cpu_set_t} object. | |
1307 | @end deftypevr | |
1308 | ||
1309 | The type @code{cpu_set_t} should be considered opaque; all | |
1310 | manipulation should happen via the next four macros. | |
1311 | ||
d9997a45 | 1312 | @deftypefn Macro void CPU_ZERO (cpu_set_t *@var{set}) |
d08a7e4c | 1313 | @standards{GNU, sched.h} |
c8ce789c AO |
1314 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1315 | @c CPU_ZERO ok | |
1316 | @c __CPU_ZERO_S ok | |
1317 | @c memset dup ok | |
d9997a45 UD |
1318 | This macro initializes the CPU set @var{set} to be the empty set. |
1319 | ||
1320 | This macro is a GNU extension and is defined in @file{sched.h}. | |
1321 | @end deftypefn | |
1322 | ||
d9997a45 | 1323 | @deftypefn Macro void CPU_SET (int @var{cpu}, cpu_set_t *@var{set}) |
d08a7e4c | 1324 | @standards{GNU, sched.h} |
c8ce789c AO |
1325 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1326 | @c CPU_SET ok | |
1327 | @c __CPU_SET_S ok | |
1328 | @c __CPUELT ok | |
1329 | @c __CPUMASK ok | |
d9997a45 UD |
1330 | This macro adds @var{cpu} to the CPU set @var{set}. |
1331 | ||
1332 | The @var{cpu} parameter must not have side effects since it is | |
1333 | evaluated more than once. | |
1334 | ||
1335 | This macro is a GNU extension and is defined in @file{sched.h}. | |
1336 | @end deftypefn | |
1337 | ||
d9997a45 | 1338 | @deftypefn Macro void CPU_CLR (int @var{cpu}, cpu_set_t *@var{set}) |
d08a7e4c | 1339 | @standards{GNU, sched.h} |
c8ce789c AO |
1340 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1341 | @c CPU_CLR ok | |
1342 | @c __CPU_CLR_S ok | |
1343 | @c __CPUELT dup ok | |
1344 | @c __CPUMASK dup ok | |
d9997a45 UD |
1345 | This macro removes @var{cpu} from the CPU set @var{set}. |
1346 | ||
1347 | The @var{cpu} parameter must not have side effects since it is | |
1348 | evaluated more than once. | |
1349 | ||
1350 | This macro is a GNU extension and is defined in @file{sched.h}. | |
1351 | @end deftypefn | |
1352 | ||
d9997a45 | 1353 | @deftypefn Macro int CPU_ISSET (int @var{cpu}, const cpu_set_t *@var{set}) |
d08a7e4c | 1354 | @standards{GNU, sched.h} |
c8ce789c AO |
1355 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1356 | @c CPU_ISSET ok | |
1357 | @c __CPU_ISSET_S ok | |
1358 | @c __CPUELT dup ok | |
1359 | @c __CPUMASK dup ok | |
d9997a45 UD |
1360 | This macro returns a nonzero value (true) if @var{cpu} is a member |
1361 | of the CPU set @var{set}, and zero (false) otherwise. | |
1362 | ||
1363 | The @var{cpu} parameter must not have side effects since it is | |
1364 | evaluated more than once. | |
1365 | ||
1366 | This macro is a GNU extension and is defined in @file{sched.h}. | |
1367 | @end deftypefn | |
1368 | ||
1369 | ||
1370 | CPU bitsets can be constructed from scratch or the currently installed | |
1371 | affinity mask can be retrieved from the system. | |
1372 | ||
6f0b2e1f | 1373 | @deftypefun int sched_getaffinity (pid_t @var{pid}, size_t @var{cpusetsize}, cpu_set_t *@var{cpuset}) |
d08a7e4c | 1374 | @standards{GNU, sched.h} |
c8ce789c AO |
1375 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1376 | @c Wrapped syscall to zero out past the kernel cpu set size; Linux | |
1377 | @c only. | |
d9997a45 | 1378 | |
d3e22d59 | 1379 | This function stores the CPU affinity mask for the process or thread |
6f0b2e1f RM |
1380 | with the ID @var{pid} in the @var{cpusetsize} bytes long bitmap |
1381 | pointed to by @var{cpuset}. If successful, the function always | |
1382 | initializes all bits in the @code{cpu_set_t} object and returns zero. | |
d9997a45 UD |
1383 | |
1384 | If @var{pid} does not correspond to a process or thread on the system | |
1385 | the or the function fails for some other reason, it returns @code{-1} | |
1386 | and @code{errno} is set to represent the error condition. | |
1387 | ||
1388 | @table @code | |
1389 | @item ESRCH | |
1390 | No process or thread with the given ID found. | |
1391 | ||
1392 | @item EFAULT | |
d3e22d59 | 1393 | The pointer @var{cpuset} does not point to a valid object. |
d9997a45 UD |
1394 | @end table |
1395 | ||
1396 | This function is a GNU extension and is declared in @file{sched.h}. | |
1397 | @end deftypefun | |
1398 | ||
1399 | Note that it is not portably possible to use this information to | |
1400 | retrieve the information for different POSIX threads. A separate | |
1401 | interface must be provided for that. | |
1402 | ||
6f0b2e1f | 1403 | @deftypefun int sched_setaffinity (pid_t @var{pid}, size_t @var{cpusetsize}, const cpu_set_t *@var{cpuset}) |
d08a7e4c | 1404 | @standards{GNU, sched.h} |
c8ce789c AO |
1405 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1406 | @c Wrapped syscall to detect attempts to set bits past the kernel cpu | |
1407 | @c set size; Linux only. | |
d9997a45 | 1408 | |
6f0b2e1f RM |
1409 | This function installs the @var{cpusetsize} bytes long affinity mask |
1410 | pointed to by @var{cpuset} for the process or thread with the ID @var{pid}. | |
d3e22d59 | 1411 | If successful the function returns zero and the scheduler will in the future |
6f0b2e1f | 1412 | take the affinity information into account. |
d9997a45 UD |
1413 | |
1414 | If the function fails it will return @code{-1} and @code{errno} is set | |
1415 | to the error code: | |
1416 | ||
1417 | @table @code | |
1418 | @item ESRCH | |
1419 | No process or thread with the given ID found. | |
1420 | ||
1421 | @item EFAULT | |
d3e22d59 | 1422 | The pointer @var{cpuset} does not point to a valid object. |
d9997a45 UD |
1423 | |
1424 | @item EINVAL | |
1425 | The bitset is not valid. This might mean that the affinity set might | |
1426 | not leave a processor for the process or thread to run on. | |
1427 | @end table | |
1428 | ||
1429 | This function is a GNU extension and is declared in @file{sched.h}. | |
1430 | @end deftypefun | |
1431 | ||
a092ca94 L |
1432 | @deftypefun int getcpu (unsigned int *cpu, unsigned int *node) |
1433 | @standards{Linux, <sched.h>} | |
1434 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
1435 | The @code{getcpu} function identifies the processor and node on which | |
1436 | the calling thread or process is currently running and writes them into | |
1437 | the integers pointed to by the @var{cpu} and @var{node} arguments. The | |
1438 | processor is a unique nonnegative integer identifying a CPU. The node | |
1439 | is a unique nonnegative integer identifying a NUMA node. When either | |
1440 | @var{cpu} or @var{node} is @code{NULL}, nothing is written to the | |
1441 | respective pointer. | |
1442 | ||
1443 | The return value is @code{0} on success and @code{-1} on failure. The | |
1444 | following @code{errno} error condition is defined for this function: | |
1445 | ||
1446 | @table @code | |
1447 | @item ENOSYS | |
1448 | The operating system does not support this function. | |
1449 | @end table | |
1450 | ||
1451 | This function is Linux-specific and is declared in @file{sched.h}. | |
1452 | @end deftypefun | |
d9997a45 | 1453 | |
b642f101 UD |
1454 | @node Memory Resources |
1455 | @section Querying memory available resources | |
1456 | ||
1457 | The amount of memory available in the system and the way it is organized | |
1458 | determines oftentimes the way programs can and have to work. For | |
5a7eedfb | 1459 | functions like @code{mmap} it is necessary to know about the size of |
b642f101 UD |
1460 | individual memory pages and knowing how much memory is available enables |
1461 | a program to select appropriate sizes for, say, caches. Before we get | |
1462 | into these details a few words about memory subsystems in traditional | |
5a7eedfb | 1463 | Unix systems will be given. |
b642f101 UD |
1464 | |
1465 | @menu | |
1466 | * Memory Subsystem:: Overview about traditional Unix memory handling. | |
1467 | * Query Memory Parameters:: How to get information about the memory | |
1468 | subsystem? | |
1469 | @end menu | |
1470 | ||
1471 | @node Memory Subsystem | |
1472 | @subsection Overview about traditional Unix memory handling | |
1473 | ||
1474 | @cindex address space | |
1475 | @cindex physical memory | |
1476 | @cindex physical address | |
1477 | Unix systems normally provide processes virtual address spaces. This | |
1478 | means that the addresses of the memory regions do not have to correspond | |
1479 | directly to the addresses of the actual physical memory which stores the | |
1480 | data. An extra level of indirection is introduced which translates | |
1481 | virtual addresses into physical addresses. This is normally done by the | |
1482 | hardware of the processor. | |
1483 | ||
1484 | @cindex shared memory | |
d3e22d59 | 1485 | Using a virtual address space has several advantages. The most important |
b642f101 UD |
1486 | is process isolation. The different processes running on the system |
1487 | cannot interfere directly with each other. No process can write into | |
1488 | the address space of another process (except when shared memory is used | |
1489 | but then it is wanted and controlled). | |
1490 | ||
1491 | Another advantage of virtual memory is that the address space the | |
1492 | processes see can actually be larger than the physical memory available. | |
1493 | The physical memory can be extended by storage on an external media | |
1494 | where the content of currently unused memory regions is stored. The | |
1495 | address translation can then intercept accesses to these memory regions | |
1496 | and make memory content available again by loading the data back into | |
1497 | memory. This concept makes it necessary that programs which have to use | |
1498 | lots of memory know the difference between available virtual address | |
1499 | space and available physical memory. If the working set of virtual | |
1500 | memory of all the processes is larger than the available physical memory | |
1501 | the system will slow down dramatically due to constant swapping of | |
1502 | memory content from the memory to the storage media and back. This is | |
1503 | called ``thrashing''. | |
1504 | @cindex thrashing | |
1505 | ||
1506 | @cindex memory page | |
1507 | @cindex page, memory | |
1508 | A final aspect of virtual memory which is important and follows from | |
1509 | what is said in the last paragraph is the granularity of the virtual | |
1510 | address space handling. When we said that the virtual address handling | |
1511 | stores memory content externally it cannot do this on a byte-by-byte | |
1512 | basis. The administrative overhead does not allow this (leaving alone | |
1513 | the processor hardware). Instead several thousand bytes are handled | |
1514 | together and form a @dfn{page}. The size of each page is always a power | |
d3e22d59 | 1515 | of two bytes. The smallest page size in use today is 4096, with 8192, |
b642f101 UD |
1516 | 16384, and 65536 being other popular sizes. |
1517 | ||
1518 | @node Query Memory Parameters | |
1519 | @subsection How to get information about the memory subsystem? | |
1520 | ||
1521 | The page size of the virtual memory the process sees is essential to | |
d3e22d59 | 1522 | know in several situations. Some programming interfaces (e.g., |
b642f101 | 1523 | @code{mmap}, @pxref{Memory-mapped I/O}) require the user to provide |
d3e22d59 | 1524 | information adjusted to the page size. In the case of @code{mmap} it is |
b642f101 UD |
1525 | necessary to provide a length argument which is a multiple of the page |
1526 | size. Another place where the knowledge about the page size is useful | |
1527 | is in memory allocation. If one allocates pieces of memory in larger | |
1528 | chunks which are then subdivided by the application code it is useful to | |
1529 | adjust the size of the larger blocks to the page size. If the total | |
1530 | memory requirement for the block is close (but not larger) to a multiple | |
1531 | of the page size the kernel's memory handling can work more effectively | |
1532 | since it only has to allocate memory pages which are fully used. (To do | |
1533 | this optimization it is necessary to know a bit about the memory | |
1534 | allocator which will require a bit of memory itself for each block and | |
d3e22d59 | 1535 | this overhead must not push the total size over the page size multiple.) |
b642f101 UD |
1536 | |
1537 | The page size traditionally was a compile time constant. But recent | |
1538 | development of processors changed this. Processors now support | |
1539 | different page sizes and they can possibly even vary among different | |
1540 | processes on the same system. Therefore the system should be queried at | |
1541 | runtime about the current page size and no assumptions (except about it | |
1542 | being a power of two) should be made. | |
1543 | ||
1544 | @vindex _SC_PAGESIZE | |
1545 | The correct interface to query about the page size is @code{sysconf} | |
1546 | (@pxref{Sysconf Definition}) with the parameter @code{_SC_PAGESIZE}. | |
1547 | There is a much older interface available, too. | |
1548 | ||
b642f101 | 1549 | @deftypefun int getpagesize (void) |
d08a7e4c | 1550 | @standards{BSD, unistd.h} |
c8ce789c AO |
1551 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} |
1552 | @c Obtained from the aux vec at program startup time. GNU/Linux/m68k is | |
1553 | @c the exception, with the possibility of a syscall. | |
b642f101 UD |
1554 | The @code{getpagesize} function returns the page size of the process. |
1555 | This value is fixed for the runtime of the process but can vary in | |
1556 | different runs of the application. | |
1557 | ||
1558 | The function is declared in @file{unistd.h}. | |
1559 | @end deftypefun | |
1560 | ||
1561 | Widely available on @w{System V} derived systems is a method to get | |
1562 | information about the physical memory the system has. The call | |
1563 | ||
1564 | @vindex _SC_PHYS_PAGES | |
1565 | @cindex sysconf | |
1566 | @smallexample | |
1567 | sysconf (_SC_PHYS_PAGES) | |
1568 | @end smallexample | |
1569 | ||
cb4fe8a2 | 1570 | @noindent |
d3e22d59 | 1571 | returns the total number of pages of physical memory the system has. |
b642f101 UD |
1572 | This does not mean all this memory is available. This information can |
1573 | be found using | |
1574 | ||
1575 | @vindex _SC_AVPHYS_PAGES | |
1576 | @cindex sysconf | |
1577 | @smallexample | |
1578 | sysconf (_SC_AVPHYS_PAGES) | |
1579 | @end smallexample | |
1580 | ||
1581 | These two values help to optimize applications. The value returned for | |
1582 | @code{_SC_AVPHYS_PAGES} is the amount of memory the application can use | |
1583 | without hindering any other process (given that no other process | |
1584 | increases its memory usage). The value returned for | |
1585 | @code{_SC_PHYS_PAGES} is more or less a hard limit for the working set. | |
1586 | If all applications together constantly use more than that amount of | |
1587 | memory the system is in trouble. | |
1588 | ||
1f77f049 | 1589 | @Theglibc{} provides in addition to these already described way to |
cb4fe8a2 UD |
1590 | get this information two functions. They are declared in the file |
1591 | @file{sys/sysinfo.h}. Programmers should prefer to use the | |
1592 | @code{sysconf} method described above. | |
1593 | ||
4c78249d | 1594 | @deftypefun {long int} get_phys_pages (void) |
d08a7e4c | 1595 | @standards{GNU, sys/sysinfo.h} |
c8ce789c AO |
1596 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} |
1597 | @c This fopens a /proc file and scans it for the requested information. | |
cb4fe8a2 | 1598 | The @code{get_phys_pages} function returns the total number of pages of |
d3e22d59 | 1599 | physical memory the system has. To get the amount of memory this number has to |
cb4fe8a2 UD |
1600 | be multiplied by the page size. |
1601 | ||
1602 | This function is a GNU extension. | |
1603 | @end deftypefun | |
1604 | ||
4c78249d | 1605 | @deftypefun {long int} get_avphys_pages (void) |
d08a7e4c | 1606 | @standards{GNU, sys/sysinfo.h} |
c8ce789c | 1607 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} |
cd1fb604 | 1608 | The @code{get_avphys_pages} function returns the number of available pages of |
d3e22d59 | 1609 | physical memory the system has. To get the amount of memory this number has to |
cb4fe8a2 UD |
1610 | be multiplied by the page size. |
1611 | ||
1612 | This function is a GNU extension. | |
1613 | @end deftypefun | |
1614 | ||
b642f101 UD |
1615 | @node Processor Resources |
1616 | @section Learn about the processors available | |
1617 | ||
1618 | The use of threads or processes with shared memory allows an application | |
1619 | to take advantage of all the processing power a system can provide. If | |
1620 | the task can be parallelized the optimal way to write an application is | |
1621 | to have at any time as many processes running as there are processors. | |
1622 | To determine the number of processors available to the system one can | |
1623 | run | |
1624 | ||
1625 | @vindex _SC_NPROCESSORS_CONF | |
1626 | @cindex sysconf | |
1627 | @smallexample | |
1628 | sysconf (_SC_NPROCESSORS_CONF) | |
1629 | @end smallexample | |
1630 | ||
1631 | @noindent | |
1632 | which returns the number of processors the operating system configured. | |
1633 | But it might be possible for the operating system to disable individual | |
1634 | processors and so the call | |
1635 | ||
1636 | @vindex _SC_NPROCESSORS_ONLN | |
1637 | @cindex sysconf | |
1638 | @smallexample | |
1639 | sysconf (_SC_NPROCESSORS_ONLN) | |
1640 | @end smallexample | |
1641 | ||
1642 | @noindent | |
26428b7c | 1643 | returns the number of processors which are currently online (i.e., |
b642f101 | 1644 | available). |
e4cf5229 | 1645 | |
1f77f049 | 1646 | For these two pieces of information @theglibc{} also provides |
cb4fe8a2 UD |
1647 | functions to get the information directly. The functions are declared |
1648 | in @file{sys/sysinfo.h}. | |
1649 | ||
cb4fe8a2 | 1650 | @deftypefun int get_nprocs_conf (void) |
d08a7e4c | 1651 | @standards{GNU, sys/sysinfo.h} |
c8ce789c AO |
1652 | @safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} |
1653 | @c This function reads from from /sys using dir streams (single user, so | |
1654 | @c no @mtasurace issue), and on some arches, from /proc using streams. | |
cb4fe8a2 UD |
1655 | The @code{get_nprocs_conf} function returns the number of processors the |
1656 | operating system configured. | |
1657 | ||
1658 | This function is a GNU extension. | |
1659 | @end deftypefun | |
1660 | ||
cb4fe8a2 | 1661 | @deftypefun int get_nprocs (void) |
d08a7e4c | 1662 | @standards{GNU, sys/sysinfo.h} |
c8ce789c AO |
1663 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} |
1664 | @c This function reads from /proc using file descriptor I/O. | |
cb4fe8a2 UD |
1665 | The @code{get_nprocs} function returns the number of available processors. |
1666 | ||
1667 | This function is a GNU extension. | |
1668 | @end deftypefun | |
1669 | ||
e4cf5229 UD |
1670 | @cindex load average |
1671 | Before starting more threads it should be checked whether the processors | |
1672 | are not already overused. Unix systems calculate something called the | |
1673 | @dfn{load average}. This is a number indicating how many processes were | |
d3e22d59 | 1674 | running. This number is an average over different periods of time |
e4cf5229 UD |
1675 | (normally 1, 5, and 15 minutes). |
1676 | ||
e4cf5229 | 1677 | @deftypefun int getloadavg (double @var{loadavg}[], int @var{nelem}) |
d08a7e4c | 1678 | @standards{BSD, stdlib.h} |
c8ce789c AO |
1679 | @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}} |
1680 | @c Calls host_info on HURD; on Linux, opens /proc/loadavg, reads from | |
1681 | @c it, closes it, without cancellation point, and calls strtod_l with | |
1682 | @c the C locale to convert the strings to doubles. | |
e4cf5229 | 1683 | This function gets the 1, 5 and 15 minute load averages of the |
cf822e3c | 1684 | system. The values are placed in @var{loadavg}. @code{getloadavg} will |
e4cf5229 UD |
1685 | place at most @var{nelem} elements into the array but never more than |
1686 | three elements. The return value is the number of elements written to | |
1687 | @var{loadavg}, or -1 on error. | |
1688 | ||
1689 | This function is declared in @file{stdlib.h}. | |
1690 | @end deftypefun |