man3/pthread_setschedparam.3

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