draft/man3/pthread_setschedparam.3

   1 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   2 .\"     <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\"*******************************************************************
  27 .\"
  28 .\" This file was generated with po4a. Translate the source file.
  29 .\"
  30 .\"*******************************************************************
  31 .TH PTHREAD_SETSCHEDPARAM 3 2008\-11\-17 Linux "Linux Programmer's Manual"
  32 .SH 名前
  33 pthread_setschedparam, pthread_getschedparam \- スレッドの
  34 スケジューリングポリシーとパラメータを設定/取得する
  35 .SH 書式
  36 .nf
  37 \fB#include <pthread.h>\fP
  38
  39 \fBpthread_setschedparam(pthread_t \fP\fIthread\fP\fB, int \fP\fIpolicy\fP\fB,\fP
  40 \fB                      const struct sched_param *\fP\fIparam\fP\fB);\fP
  41 \fBpthread_getschedparam(pthread_t \fP\fIthread\fP\fB, int *\fP\fIpolicy\fP\fB,\fP
  42 \fB                      struct sched_param *\fP\fIparam\fP\fB);\fP
  43 .sp
  44 \fI\-pthread\fP でコンパイルしてリンクする。
  45 .fi
  46 .SH 説明
  47 \fBpthread_setschedparam\fP() 関数は、スレッド \fIthread\fP の
  48 スケジューリングポリシーとスケジューリングパラメータを設定する。
  49
  50 .\" FIXME . pthread_setschedparam() places no restriction on the policy,
  51 .\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER
  52 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013
  53 \fIpolicy\fP は \fIthread\fP の新しいスケジューリングポリシーを指定する。
  54 \fIpolicy\fP に指定できる値とその意味は \fBsched_setscheduler\fP(2) で
  55 説明されている。
  56
  57 \fIparam\fP が指す構造体は \fIthread\fP の新しいスケジューリングパラメータを
  58 指定する。スケジューリングパラメータは以下の構造体で管理される。
  59
  60 .in +4n
  61 .nf
  62 struct sched_param {
  63     int sched_priority;     /* Scheduling priority */
  64 };
  65 .fi
  66 .in
  67
  68 見て分かる通り、サポートされているスケジューリングパラメータは一つだけ
  69 である。各スケジューリングポリシーで許可されるスケジューリング優先度の
  70 詳細については、\fBsched_setscheduler\fP(2) を参照のこと。
  71
  72 .\" FIXME . nptl/pthread_setschedparam.c has the following
  73 .\"   /* If the thread should have higher priority because of some
  74 .\"      PTHREAD_PRIO_PROTECT mutexes it holds, adjust the priority. */
  75 .\" Eventually (perhaps after writing the mutexattr pages), we
  76 .\" may want to add something on the topic to this page.
  77 \fBpthread_getschedparam\fP() 関数は、スレッド \fIthread\fP の
  78 スケジューリングポリシーとパラメータを、
  79 それぞれ \fIpolicy\fP と \fIparam\fP が指すバッファに入れて返す。
  80 返された優先度の値は、最も最近実行した \fIthread\fP に影響を与える
  81 \fBpthread_setschedparam\fP(), \fBpthread_setschedprio\fP,
  82 \fBpthread_create\fP で設定された値となる。
  83 返された優先度は、優先度の継承や優先度の上限を設定する関数
  84 (例えば \fBpthread_mutexattr_setprioceiling\fP(3) や
  85 \fBpthread_mutexattr_setprotocol\fP(3) を参照) の呼び出しの結果
  86 行われる一時的な優先度の調整の影響を受けない。
  87 .SH 返り値
  88 成功すると、これらの関数は 0 を返す。
  89 エラーの場合、0 以外のエラー番号を返す。
  90 \fBpthread_setschedparam\fP() が失敗した場合、 \fIthread\fP の
  91 スケジューリングポリシーとパラメータは変更されない。
  92 .SH エラー
  93 これらの関数はどちらも以下のエラーで失敗する場合がある。
  94 .TP
  95 \fBESRCH\fP
  96 ID が \fIthread\fP のスレッドが見つからなかった。
  97 .PP
  98 \fBpthread_setschedparam\fP() はさらに以下のエラーで失敗する場合がある。
  99 .TP
 100 \fBEINVAL\fP
 101 \fIpolicy\fP が認識できないポリシーであるか、
 102 \fIparam\fP が \fIpolicy\fP では意味を持たない値である。
 103 .TP
 104 \fBEPERM\fP
 105 呼び出し側が、指定されたスケジューリングポリシーやパラメータを設定する
 106 のに必要な特権を持たない。
 107 .PP
 108 .\" .SH VERSIONS
 109 .\" Available since glibc 2.0
 110 POSIX.1\-2001 では、 \fBpthread_setschedparam\fP() に関して
 111 エラー \fBENOTSUP\fP ("サポートされていない値をスケジューリングポリシーや
 112 パラメータに設定しようとした") も追加で規定されている。
 113 .SH 準拠
 114 POSIX.1\-2001.
 115 .SH 注意
 116 スレッドのスケジューリングポリシーや優先度を変更するために必要な許可や
 117 変更した場合の影響、および各スケジューリングポリシーで認められる優先度
 118 の範囲の詳細については、 \fBsched_setscheduler\fP(2) を参照。
 119 .SH 例
 120 以下のプログラムは \fBpthread_setschedparam\fP() と
 121 \fBpthread_getschedparam\fP() やスケジューリングに関連する pthreads の
 122 他のいろいろな関数の使用例を示すものである。
 123
 124 以下の実行例では、メインスレッドは、自分のスケジューリングポリシーを
 125 優先度 10 の \fBSCHED_FIFO\fP を設定し、スレッド属性オブジェクトを
 126 スケジューリングポリシー属性 \fBSCHED_RR\fP とスケジューリング優先度
 127 属性 20 で初期化する。
 128 次に、このプログラムは (\fBpthread_attr_setinheritsched\fP(3) を使って)
 129 そのスレッド属性オブジェクトの inherit scheduler 属性に
 130 \fBPTHREAD_EXPLICIT_SCHED\fP を設定する。\fBPTHREAD_EXPLICIT_SCHED\fP は、
 131 そのスレッド属性オブジェクトを使って作成されたスレッドはスレッド属性
 132 オブジェクトからスケジューリング属性を取得して使うことを意味する。
 133 それから、このスレッド属性オブジェクトを使ってスレッドを作成し、
 134 作成したスレッドのスケジューリングポリシーと優先度を表示する。
 135 .in +4n
 136 .nf
 137
 138 $ \fBsu\fP      # Need privilege to set real\-time scheduling policies
 139 Password:
 140 # \fB./a.out \-mf10 \-ar20 \-i e\fP
 141 Scheduler settings of main thread
 142     policy=SCHED_FIFO, priority=10
 143
 144 Scheduler settings in \(aqattr\(aq
 145     policy=SCHED_RR, priority=20
 146     inheritsched is EXPLICIT
 147
 148 Scheduler attributes of new thread
 149     policy=SCHED_RR, priority=20
 150 .fi
 151 .in
 152
 153 上記の出力では、スケジューリングポリシーと優先度がスレッド属性
 154 オブジェクトで指定された値から取られていることが分かる。
 155
 156 次の実行例は前のものと同じだが、 inherit scheduler 属性が
 157 \fBPTHREAD_INHERIT_SCHED\fP に設定される点が異なる。
 158 \fBPTHREAD_INHERIT_SCHED\fP は、そのスレッド属性オブジェクトを使って作成
 159 されたスレッドは、スレッド属性オブジェクトからスケジューリング属性を
 160 無視し、代わりに呼び出したスレッドからスケジューリング属性を取得する
 161 ことを意味する。
 162
 163 .in +4n
 164 .nf
 165 # \fB./a.out \-mf10 \-ar20 \-i i\fP
 166 Scheduler settings of main thread
 167     policy=SCHED_FIFO, priority=10
 168
 169 Scheduler settings in \(aqattr\(aq
 170     policy=SCHED_RR, priority=20
 171     inheritsched is INHERIT
 172
 173 Scheduler attributes of new thread
 174     policy=SCHED_FIFO, priority=10
 175 .fi
 176 .in
 177
 178 上記の出力では、スケジューリングポリシーと優先度が、
 179 スレッド属性オブジェクトからではなく、
 180 スレッドを作成したスレッドから取れれていることが分かる。
 181
 182 なお、 \fI\-i\ i\fP を省略した場合でも、
 183 \fBPTHREAD_INHERIT_SCHED\fP が inherit scheduler 属性のデフォルト値なので、
 184 出力は同じになる。
 185 .SS プログラムのソース
 186 \&
 187 .nf
 188 /* pthreads_sched_test.c */
 189
 190 #include <pthread.h>
 191 #include <stdio.h>
 192 #include <stdlib.h>
 193 #include <unistd.h>
 194 #include <errno.h>
 195
 196 #define handle_error_en(en, msg) \e
 197         do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
 198
 199 static void
 200 usage(char *prog_name, char *msg)
 201 {
 202     if (msg != NULL)
 203         fputs(msg, stderr);
 204
 205     fprintf(stderr, "Usage: %s [options]\en", prog_name);
 206     fprintf(stderr, "Options are:\en");
 207 #define fpe(msg) fprintf(stderr, "\et%s", msg);          /* Shorter */
 208     fpe("\-a<policy><prio> Set scheduling policy and priority in\en");
 209     fpe("                 thread attributes object\en");
 210     fpe("                 <policy> can be\en");
 211     fpe("                     f  SCHED_FIFO\en");
 212     fpe("                     r  SCHED_RR\en");
 213     fpe("                     o  SCHED_OTHER\en");
 214     fpe("\-A               Use default thread attributes object\en");
 215     fpe("\-i {e|s}         Set inherit scheduler attribute to\en");
 216     fpe("                 \(aqexplicit\(aq or \(aqinherit\(aq\en");
 217     fpe("\-m<policy><prio> Set scheduling policy and priority on\en");
 218     fpe("                 main thread before pthread_create() call\en");
 219     exit(EXIT_FAILURE);
 220 }
 221
 222 static int
 223 get_policy(char p, int *policy)
 224 {
 225     switch (p) {
 226     case \(aqf\(aq: *policy = SCHED_FIFO;     return 1;
 227     case \(aqr\(aq: *policy = SCHED_RR;       return 1;
 228     case \(aqo\(aq: *policy = SCHED_OTHER;    return 1;
 229     default:  return 0;
 230     }
 231 }
 232
 233 static void
 234 display_sched_attr(int policy, struct sched_param *param)
 235 {
 236     printf("    policy=%s, priority=%d\en",
 237             (policy == SCHED_FIFO)  ? "SCHED_FIFO" :
 238             (policy == SCHED_RR)    ? "SCHED_RR" :
 239             (policy == SCHED_OTHER) ? "SCHED_OTHER" :
 240             "???",
 241             param\->sched_priority);
 242 }
 243
 244 static void
 245 display_thread_sched_attr(char *msg)
 246 {
 247     int policy, s;
 248     struct sched_param param;
 249
 250     s = pthread_getschedparam(pthread_self(), &policy, &param);
 251     if (s != 0)
 252         handle_error_en(s, "pthread_getschedparam");
 253
 254     printf("%s\en", msg);
 255     display_sched_attr(policy, &param);
 256 }
 257
 258 static void *
 259 thread_start(void *arg)
 260 {
 261     display_thread_sched_attr("Scheduler attributes of new thread");
 262
 263     return NULL;
 264 }
 265
 266 int
 267 main(int argc, char *argv[])
 268 {
 269     int s, opt, inheritsched, use_null_attrib, policy;
 270     pthread_t thread;
 271     pthread_attr_t attr;
 272     pthread_attr_t *attrp;
 273     char *attr_sched_str, *main_sched_str, *inheritsched_str;
 274     struct sched_param param;
 275
 276     /* Process command\-line options */
 277
 278     use_null_attrib = 0;
 279     attr_sched_str = NULL;
 280     main_sched_str = NULL;
 281     inheritsched_str = NULL;
 282
 283     while ((opt = getopt(argc, argv, "a:Ai:m:")) != \-1) {
 284         switch (opt) {
 285         case \(aqa\(aq: attr_sched_str = optarg;      break;
 286         case \(aqA\(aq: use_null_attrib = 1;          break;
 287         case \(aqi\(aq: inheritsched_str = optarg;    break;
 288         case \(aqm\(aq: main_sched_str = optarg;      break;
 289         default:  usage(argv[0], "Unrecognized option\en");
 290         }
 291     }
 292
 293     if (use_null_attrib &&
 294             (inheritsched_str != NULL || attr_sched_str != NULL))
 295         usage(argv[0], "Can\(aqt specify \-A with \-i or \-a\en");
 296
 297     /* Optionally set scheduling attributes of main thread,
 298        and display the attributes */
 299
 300     if (main_sched_str != NULL) {
 301         if (!get_policy(main_sched_str[0], &policy))
 302             usage(argv[0], "Bad policy for main thread (\-s)\en");
 303         param.sched_priority = strtol(&main_sched_str[1], NULL, 0);
 304
 305         s = pthread_setschedparam(pthread_self(), policy, &param);
 306         if (s != 0)
 307             handle_error_en(s, "pthread_setschedparam");
 308     }
 309
 310     display_thread_sched_attr("Scheduler settings of main thread");
 311     printf("\en");
 312
 313     /* Initialize thread attributes object according to options */
 314
 315     attrp = NULL;
 316
 317     if (!use_null_attrib) {
 318         s = pthread_attr_init(&attr);
 319         if (s != 0)
 320             handle_error_en(s, "pthread_attr_init");
 321         attrp = &attr;
 322     }
 323
 324     if (inheritsched_str != NULL) {
 325         if (inheritsched_str[0] == \(aqe\(aq)
 326             inheritsched = PTHREAD_EXPLICIT_SCHED;
 327         else if (inheritsched_str[0] == \(aqi\(aq)
 328             inheritsched = PTHREAD_INHERIT_SCHED;
 329         else
 330             usage(argv[0], "Value for \-i must be \(aqe\(aq or \(aqi\(aq\en");
 331
 332         s = pthread_attr_setinheritsched(&attr, inheritsched);
 333         if (s != 0)
 334             handle_error_en(s, "pthread_attr_setinheritsched");
 335     }
 336
 337     if (attr_sched_str != NULL) {
 338         if (!get_policy(attr_sched_str[0], &policy))
 339             usage(argv[0],
 340                     "Bad policy for \(aqattr\(aq (\-a)\en");
 341         param.sched_priority = strtol(&attr_sched_str[1], NULL, 0);
 342
 343         s = pthread_attr_setschedpolicy(&attr, policy);
 344         if (s != 0)
 345             handle_error_en(s, "pthread_attr_setschedpolicy");
 346         s = pthread_attr_setschedparam(&attr, &param);
 347         if (s != 0)
 348             handle_error_en(s, "pthread_attr_setschedparam");
 349     }
 350
 351     /* If we initialized a thread attributes object, display
 352        the scheduling attributes that were set in the object */
 353
 354     if (attrp != NULL) {
 355         s = pthread_attr_getschedparam(&attr, &param);
 356         if (s != 0)
 357             handle_error_en(s, "pthread_attr_getschedparam");
 358         s = pthread_attr_getschedpolicy(&attr, &policy);
 359         if (s != 0)
 360             handle_error_en(s, "pthread_attr_getschedpolicy");
 361
 362         printf("Scheduler settings in \(aqattr\(aq\en");
 363         display_sched_attr(policy, &param);
 364
 365         s = pthread_attr_getinheritsched(&attr, &inheritsched);
 366         printf("    inheritsched is %s\en",
 367                 (inheritsched == PTHREAD_INHERIT_SCHED)  ? "INHERIT" :
 368                 (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" :
 369                 "???");
 370         printf("\en");
 371     }
 372
 373     /* Create a thread that will display its scheduling attributes */
 374
 375     s = pthread_create(&thread, attrp, &thread_start, NULL);
 376     if (s != 0)
 377         handle_error_en(s, "pthread_create");
 378
 379     /* Destroy unneeded thread attributes object */
 380
 381     s = pthread_attr_destroy(&attr);
 382     if (s != 0)
 383         handle_error_en(s, "pthread_attr_destroy");
 384
 385     s = pthread_join(thread, NULL);
 386     if (s != 0)
 387         handle_error_en(s, "pthread_join");
 388
 389     exit(EXIT_SUCCESS);
 390 }
 391 .fi
 392 .SH 関連項目
 393 .ad l
 394 .nh
 395 \fBgetrlimit\fP(2), \fBsched_get_priority_min\fP(2), \fBsched_setscheduler\fP(2),
 396 \fBpthread_attr_init\fP(3), \fBpthread_attr_setinheritsched\fP(3),
 397 \fBpthread_attr_setschedparam\fP(3), \fBpthread_attr_setschedpolicy\fP(3),
 398 \fBpthread_create\fP(3), \fBpthread_self\fP(3), \fBpthread_setschedprio\fP(3),
 399 \fBpthreads\fP(7)
 400 .SH この文書について
 401 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.52 の一部
 402 である。プロジェクトの説明とバグ報告に関する情報は
 403 http://www.kernel.org/doc/man\-pages/ に書かれている。