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