man3/pthread_setschedparam.3

   1 '\" t
   2 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   3 .\"     <mtk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .TH pthread_setschedparam 3 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 pthread_setschedparam, pthread_getschedparam \- set/get
  10 scheduling policy and parameters of a thread
  11 .SH LIBRARY
  12 POSIX threads library
  13 .RI ( libpthread ", " \-lpthread )
  14 .SH SYNOPSIS
  15 .nf
  16 .B #include <pthread.h>
  17 .P
  18 .BI "int pthread_setschedparam(pthread_t " thread ", int " policy ,
  19 .BI "                          const struct sched_param *" param );
  20 .BI "int pthread_getschedparam(pthread_t " thread ", int *restrict " policy ,
  21 .BI "                          struct sched_param *restrict " param );
  22 .fi
  23 .SH DESCRIPTION
  24 The
  25 .BR pthread_setschedparam ()
  26 function sets the scheduling policy and parameters of the thread
  27 .IR thread .
  28 .P
  29 .I policy
  30 specifies the new scheduling policy for
  31 .IR thread .
  32 The supported values for
  33 .IR policy ,
  34 and their semantics, are described in
  35 .BR sched (7).
  36 .\" FIXME . pthread_setschedparam() places no restriction on the policy,
  37 .\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER
  38 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013
  39 .P
  40 The structure pointed to by
  41 .I param
  42 specifies the new scheduling parameters for
  43 .IR thread .
  44 Scheduling parameters are maintained in the following structure:
  45 .P
  46 .in +4n
  47 .EX
  48 struct sched_param {
  49     int sched_priority;     /* Scheduling priority */
  50 };
  51 .EE
  52 .in
  53 .P
  54 As can be seen, only one scheduling parameter is supported.
  55 For details of the permitted ranges for scheduling priorities
  56 in each scheduling policy, see
  57 .BR sched (7).
  58 .P
  59 The
  60 .BR pthread_getschedparam ()
  61 function returns the scheduling policy and parameters of the thread
  62 .IR thread ,
  63 in the buffers pointed to by
  64 .I policy
  65 and
  66 .IR param ,
  67 respectively.
  68 The returned priority value is that set by the most recent
  69 .BR pthread_setschedparam (),
  70 .BR pthread_setschedprio (3),
  71 or
  72 .BR pthread_create (3)
  73 call that affected
  74 .IR thread .
  75 The returned priority does not reflect any temporary priority adjustments
  76 as a result of calls to any priority inheritance or
  77 priority ceiling functions (see, for example,
  78 .BR pthread_mutexattr_setprioceiling (3)
  79 and
  80 .BR pthread_mutexattr_setprotocol (3)).
  81 .\" FIXME . nptl/pthread_setschedparam.c has the following
  82 .\"   /* If the thread should have higher priority because of some
  83 .\"      PTHREAD_PRIO_PROTECT mutexes it holds, adjust the priority. */
  84 .\" Eventually (perhaps after writing the mutexattr pages), we
  85 .\" may want to add something on the topic to this page.
  86 .SH RETURN VALUE
  87 On success, these functions return 0;
  88 on error, they return a nonzero error number.
  89 If
  90 .BR pthread_setschedparam ()
  91 fails, the scheduling policy and parameters of
  92 .I thread
  93 are not changed.
  94 .SH ERRORS
  95 Both of these functions can fail with the following error:
  96 .TP
  97 .B ESRCH
  98 No thread with the ID
  99 .I thread
 100 could be found.
 101 .P
 102 .BR pthread_setschedparam ()
 103 may additionally fail with the following errors:
 104 .TP
 105 .B EINVAL
 106 .I policy
 107 is not a recognized policy, or
 108 .I param
 109 does not make sense for the
 110 .IR policy .
 111 .TP
 112 .B EPERM
 113 The caller does not have appropriate privileges
 114 to set the specified scheduling policy and parameters.
 115 .P
 116 POSIX.1 also documents an
 117 .B ENOTSUP
 118 ("attempt was made to set the policy or scheduling parameters
 119 to an unsupported value") error for
 120 .BR pthread_setschedparam ().
 121 .SH ATTRIBUTES
 122 For an explanation of the terms used in this section, see
 123 .BR attributes (7).
 124 .TS
 125 allbox;
 126 lbx lb lb
 127 l l l.
 128 Interface       Attribute       Value
 129 T{
 130 .na
 131 .nh
 132 .BR pthread_setschedparam (),
 133 .BR pthread_getschedparam ()
 134 T}      Thread safety   MT-Safe
 135 .TE
 136 .SH STANDARDS
 137 POSIX.1-2008.
 138 .SH HISTORY
 139 glibc 2.0
 140 POSIX.1-2001.
 141 .SH NOTES
 142 For a description of the permissions required to, and the effect of,
 143 changing a thread's scheduling policy and priority,
 144 and details of the permitted ranges for priorities
 145 in each scheduling policy, see
 146 .BR sched (7).
 147 .SH EXAMPLES
 148 The program below demonstrates the use of
 149 .BR pthread_setschedparam ()
 150 and
 151 .BR pthread_getschedparam (),
 152 as well as the use of a number of other scheduling-related
 153 pthreads functions.
 154 .P
 155 In the following run, the main thread sets its scheduling policy to
 156 .B SCHED_FIFO
 157 with a priority of 10,
 158 and initializes a thread attributes object with
 159 a scheduling policy attribute of
 160 .B SCHED_RR
 161 and a scheduling priority attribute of 20.
 162 The program then sets (using
 163 .BR pthread_attr_setinheritsched (3))
 164 the inherit scheduler attribute of the thread attributes object to
 165 .BR PTHREAD_EXPLICIT_SCHED ,
 166 meaning that threads created using this attributes object should
 167 take their scheduling attributes from the thread attributes object.
 168 The program then creates a thread using the thread attributes object,
 169 and that thread displays its scheduling policy and priority.
 170 .P
 171 .in +4n
 172 .EX
 173 $ \fBsu\fP      # Need privilege to set real\-time scheduling policies
 174 Password:
 175 # \fB./a.out \-mf10 \-ar20 \-i e\fP
 176 Scheduler settings of main thread
 177     policy=SCHED_FIFO, priority=10
 178 \&
 179 Scheduler settings in \[aq]attr\[aq]
 180     policy=SCHED_RR, priority=20
 181     inheritsched is EXPLICIT
 182 \&
 183 Scheduler attributes of new thread
 184     policy=SCHED_RR, priority=20
 185 .EE
 186 .in
 187 .P
 188 In the above output, one can see that the scheduling policy and priority
 189 were taken from the values specified in the thread attributes object.
 190 .P
 191 The next run is the same as the previous,
 192 except that the inherit scheduler attribute is set to
 193 .BR PTHREAD_INHERIT_SCHED ,
 194 meaning that threads created using the thread attributes object should
 195 ignore the scheduling attributes specified in the attributes object
 196 and instead take their scheduling attributes from the creating thread.
 197 .P
 198 .in +4n
 199 .EX
 200 # \fB./a.out \-mf10 \-ar20 \-i i\fP
 201 Scheduler settings of main thread
 202     policy=SCHED_FIFO, priority=10
 203 \&
 204 Scheduler settings in \[aq]attr\[aq]
 205     policy=SCHED_RR, priority=20
 206     inheritsched is INHERIT
 207 \&
 208 Scheduler attributes of new thread
 209     policy=SCHED_FIFO, priority=10
 210 .EE
 211 .in
 212 .P
 213 In the above output, one can see that the scheduling policy and priority
 214 were taken from the creating thread,
 215 rather than the thread attributes object.
 216 .P
 217 Note that if we had omitted the
 218 .I \-i\~i
 219 option, the output would have been the same, since
 220 .B PTHREAD_INHERIT_SCHED
 221 is the default for the inherit scheduler attribute.
 222 .SS Program source
 223 \&
 224 .\" SRC BEGIN (pthreads_sched_test.c)
 225 .EX
 226 /* pthreads_sched_test.c */
 227 \&
 228 #include <errno.h>
 229 #include <pthread.h>
 230 #include <stdio.h>
 231 #include <stdlib.h>
 232 #include <unistd.h>
 233 \&
 234 #define handle_error_en(en, msg) \e
 235         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 236 \&
 237 [[noreturn]]
 238 static void
 239 usage(char *prog_name, char *msg)
 240 {
 241     if (msg != NULL)
 242         fputs(msg, stderr);
 243 \&
 244     fprintf(stderr, "Usage: %s [options]\en", prog_name);
 245     fprintf(stderr, "Options are:\en");
 246 #define fpe(msg) fprintf(stderr, "\et%s", msg)          /* Shorter */
 247     fpe("\-a<policy><prio> Set scheduling policy and priority in\en");
 248     fpe("                 thread attributes object\en");
 249     fpe("                 <policy> can be\en");
 250     fpe("                     f  SCHED_FIFO\en");
 251     fpe("                     r  SCHED_RR\en");
 252     fpe("                     o  SCHED_OTHER\en");
 253     fpe("\-A               Use default thread attributes object\en");
 254     fpe("\-i {e|i}         Set inherit scheduler attribute to\en");
 255     fpe("                 \[aq]explicit\[aq] or \[aq]inherit\[aq]\en");
 256     fpe("\-m<policy><prio> Set scheduling policy and priority on\en");
 257     fpe("                 main thread before pthread_create() call\en");
 258     exit(EXIT_FAILURE);
 259 }
 260 \&
 261 static int
 262 get_policy(char p, int *policy)
 263 {
 264     switch (p) {
 265     case \[aq]f\[aq]: *policy = SCHED_FIFO;     return 1;
 266     case \[aq]r\[aq]: *policy = SCHED_RR;       return 1;
 267     case \[aq]o\[aq]: *policy = SCHED_OTHER;    return 1;
 268     default:  return 0;
 269     }
 270 }
 271 \&
 272 static void
 273 display_sched_attr(int policy, const struct sched_param *param)
 274 {
 275     printf("    policy=%s, priority=%d\en",
 276            (policy == SCHED_FIFO)  ? "SCHED_FIFO" :
 277            (policy == SCHED_RR)    ? "SCHED_RR" :
 278            (policy == SCHED_OTHER) ? "SCHED_OTHER" :
 279            "???",
 280            param\->sched_priority);
 281 }
 282 \&
 283 static void
 284 display_thread_sched_attr(char *msg)
 285 {
 286     int policy, s;
 287     struct sched_param param;
 288 \&
 289     s = pthread_getschedparam(pthread_self(), &policy, &param);
 290     if (s != 0)
 291         handle_error_en(s, "pthread_getschedparam");
 292 \&
 293     printf("%s\en", msg);
 294     display_sched_attr(policy, &param);
 295 }
 296 \&
 297 static void *
 298 thread_start(void *arg)
 299 {
 300     display_thread_sched_attr("Scheduler attributes of new thread");
 301 \&
 302     return NULL;
 303 }
 304 \&
 305 int
 306 main(int argc, char *argv[])
 307 {
 308     int s, opt, inheritsched, use_null_attrib, policy;
 309     pthread_t thread;
 310     pthread_attr_t attr;
 311     pthread_attr_t *attrp;
 312     char *attr_sched_str, *main_sched_str, *inheritsched_str;
 313     struct sched_param param;
 314 \&
 315     /* Process command\-line options. */
 316 \&
 317     use_null_attrib = 0;
 318     attr_sched_str = NULL;
 319     main_sched_str = NULL;
 320     inheritsched_str = NULL;
 321 \&
 322     while ((opt = getopt(argc, argv, "a:Ai:m:")) != \-1) {
 323         switch (opt) {
 324         case \[aq]a\[aq]: attr_sched_str = optarg;      break;
 325         case \[aq]A\[aq]: use_null_attrib = 1;          break;
 326         case \[aq]i\[aq]: inheritsched_str = optarg;    break;
 327         case \[aq]m\[aq]: main_sched_str = optarg;      break;
 328         default:  usage(argv[0], "Unrecognized option\en");
 329         }
 330     }
 331 \&
 332     if (use_null_attrib
 333         && (inheritsched_str != NULL || attr_sched_str != NULL))
 334     {
 335         usage(argv[0], "Can\[aq]t specify \-A with \-i or \-a\en");
 336     }
 337 \&
 338     /* Optionally set scheduling attributes of main thread,
 339        and display the attributes. */
 340 \&
 341     if (main_sched_str != NULL) {
 342         if (!get_policy(main_sched_str[0], &policy))
 343             usage(argv[0], "Bad policy for main thread (\-m)\en");
 344         param.sched_priority = strtol(&main_sched_str[1], NULL, 0);
 345 \&
 346         s = pthread_setschedparam(pthread_self(), policy, &param);
 347         if (s != 0)
 348             handle_error_en(s, "pthread_setschedparam");
 349     }
 350 \&
 351     display_thread_sched_attr("Scheduler settings of main thread");
 352     printf("\en");
 353 \&
 354     /* Initialize thread attributes object according to options. */
 355 \&
 356     attrp = NULL;
 357 \&
 358     if (!use_null_attrib) {
 359         s = pthread_attr_init(&attr);
 360         if (s != 0)
 361             handle_error_en(s, "pthread_attr_init");
 362         attrp = &attr;
 363     }
 364 \&
 365     if (inheritsched_str != NULL) {
 366         if (inheritsched_str[0] == \[aq]e\[aq])
 367             inheritsched = PTHREAD_EXPLICIT_SCHED;
 368         else if (inheritsched_str[0] == \[aq]i\[aq])
 369             inheritsched = PTHREAD_INHERIT_SCHED;
 370         else
 371             usage(argv[0], "Value for \-i must be \[aq]e\[aq] or \[aq]i\[aq]\en");
 372 \&
 373         s = pthread_attr_setinheritsched(&attr, inheritsched);
 374         if (s != 0)
 375             handle_error_en(s, "pthread_attr_setinheritsched");
 376     }
 377 \&
 378     if (attr_sched_str != NULL) {
 379         if (!get_policy(attr_sched_str[0], &policy))
 380             usage(argv[0], "Bad policy for \[aq]attr\[aq] (\-a)\en");
 381         param.sched_priority = strtol(&attr_sched_str[1], NULL, 0);
 382 \&
 383         s = pthread_attr_setschedpolicy(&attr, policy);
 384         if (s != 0)
 385             handle_error_en(s, "pthread_attr_setschedpolicy");
 386         s = pthread_attr_setschedparam(&attr, &param);
 387         if (s != 0)
 388             handle_error_en(s, "pthread_attr_setschedparam");
 389     }
 390 \&
 391     /* If we initialized a thread attributes object, display
 392        the scheduling attributes that were set in the object. */
 393 \&
 394     if (attrp != NULL) {
 395         s = pthread_attr_getschedparam(&attr, &param);
 396         if (s != 0)
 397             handle_error_en(s, "pthread_attr_getschedparam");
 398         s = pthread_attr_getschedpolicy(&attr, &policy);
 399         if (s != 0)
 400             handle_error_en(s, "pthread_attr_getschedpolicy");
 401 \&
 402         printf("Scheduler settings in \[aq]attr\[aq]\en");
 403         display_sched_attr(policy, &param);
 404 \&
 405         pthread_attr_getinheritsched(&attr, &inheritsched);
 406         printf("    inheritsched is %s\en",
 407                (inheritsched == PTHREAD_INHERIT_SCHED)  ? "INHERIT" :
 408                (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" :
 409                "???");
 410         printf("\en");
 411     }
 412 \&
 413     /* Create a thread that will display its scheduling attributes. */
 414 \&
 415     s = pthread_create(&thread, attrp, &thread_start, NULL);
 416     if (s != 0)
 417         handle_error_en(s, "pthread_create");
 418 \&
 419     /* Destroy unneeded thread attributes object. */
 420 \&
 421     if (!use_null_attrib) {
 422       s = pthread_attr_destroy(&attr);
 423       if (s != 0)
 424           handle_error_en(s, "pthread_attr_destroy");
 425     }
 426 \&
 427     s = pthread_join(thread, NULL);
 428     if (s != 0)
 429         handle_error_en(s, "pthread_join");
 430 \&
 431     exit(EXIT_SUCCESS);
 432 }
 433 .EE
 434 .\" SRC END
 435 .SH SEE ALSO
 436 .ad l
 437 .nh
 438 .BR getrlimit (2),
 439 .BR sched_get_priority_min (2),
 440 .BR pthread_attr_init (3),
 441 .BR pthread_attr_setinheritsched (3),
 442 .BR pthread_attr_setschedparam (3),
 443 .BR pthread_attr_setschedpolicy (3),
 444 .BR pthread_create (3),
 445 .BR pthread_self (3),
 446 .BR pthread_setschedprio (3),
 447 .BR pthreads (7),
 448 .BR sched (7)