draft/man3/pthread_setschedparam.3

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