pthread_attr_initのヘルプ・マニュアル／リナックスコマンド

pthread_attr_initのヘルプ・マニュアル

help
man

pthread_attr_init --help

man pthread_attr_init

PTHREAD_ATTR_INIT(3) PTHREAD_ATTR_INIT(3) 名前 pthread_attr_init, pthread_attr_destroy, pthread_attr_setdetachstate, pthread_attr_getdetachstate, pthread_attr_setschedparam, pthread_attr_getschedparam, pthread_attr_setschedpolicy, pthread_attr_getschedpolicy, pthread_attr_setinheritsched, pthread_attr_getinheritsched, pthread_attr_setscope, pthread_attr_getscope - スレッド生成時の属性書式 #include int pthread_attr_init(pthread_attr_t *attr); int pthread_attr_destroy(pthread_attr_t *attr); int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate); int pthread_attr_getdetachstate(const pthread_attr_t *attr, int *detachstate); int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy); int pthread_attr_getschedpolicy(const pthread_attr_t *attr, int *pol- icy); int pthread_attr_setschedparam(pthread_attr_t *attr, const struct sched_param *param); int pthread_attr_getschedparam(const pthread_attr_t *attr, struct sched_param *param); int pthread_attr_setinheritsched(pthread_attr_t *attr, int inherit); int pthread_attr_getinheritsched(const pthread_attr_t *attr, int *inherit); int pthread_attr_setscope(pthread_attr_t *attr, int scope); int pthread_attr_getscope(const pthread_attr_t *attr, int *scope); 説明スレッドの属性を設定するには、 pthread_attr_t 型のスレッド属性オブジェクト attr に値を格納し、 pthread_create(3) の第 2 引数として渡せばよい。 NULL を渡すことは、すべての属性がデフォルトに設定されたスレッド属性オブジェクトを渡すのと同等である。 pthread_attr_init はスレッド属性オブジェクト attr を初期化して、各属性のデフォルトの値を格納する。 ( 各属性のデフォルト値は下を参照のこと。 ) それぞれの属性 attrname ( 全属性のリストは下を参照のこと ) は、関数 pthread_attr_setattrname で個別に設定したり、 pthread_attr_getattrname で個別に取得したりすることが可能である。 pthread_attr_destroy はスレッド属性オブジェクトを破壊する。破壊したオブジェクトは、再初期化するまでは再び使用してはならない。 pthread_attr_destroy は LinuxThreads の実装では何もしない。属性オブジェクトは新しいスレッドを生成するときにだけ参照される。複数のスレッドの生成に同じ属性オブジェクトを使用することもできる。 pthread_create の呼び出しの後に属性オブジェクトを変更しても、すでに生成されたスレッドの属性は変化しない。次のようなスレッド属性に対応している: detachstate (デタッチ状態) スレッドが合流可能な状態で生成される ( PTHREAD_CREATE_JOINABLE) か、デタッチ状態で生成される ( PTHREAD_CREATE_DETACHED) かを制御する。デフォルト値: PTHREAD_CREATE_JOINABLE 。合流可能な状態の場合、別のスレッドが pthread_join(3) を呼び出すことによって、そのスレッドの終了に同期して終了コードを取得することができる。しかし、スレッドの資源の一部はスレッドが終了した後も確保されたまま残り、別のスレッドがそのスレッドに対して pthread_join(3) を呼び出したときに限って解放される。デタッチ状態の場合、スレッドの資源は終了した時に直ちに解放される。しかし、 pthread_join(3) を使用してスレッドの終了に同期することはできない。合流可能な状態で生成されたスレッドは、 pthread_detach(3) を呼び出してデタッチスレッドに変更することができる。 schedpolicy (スケジューリングポリシー) スレッドのスケジューリングポリシーを選択する。とりうる値は SCHED_OTHER ( 通常の、リアルタイムでないスケジューリング) 、 SCHED_RR (ラウンドロビン方式のリアルタイムスケジューリング) 、 SCHED_FIFO ( 先入れ先出し (FIFO) 方式のリアルタイムスケジューリング) のいずれかである。スケジューリングポリシーに関するさらなる情報については sched_setpolicy(2) を参照のこと。デフォルト値: SCHED_OTHER 。リアルタイムスケジューリングポリシーである SCHED_RR と SCHED_FIFO は、スーパーユーザ権限のプロセスに限って使用できる。スレッドのスケジューリングポリシーは、生成後に pthread_setschedparam(3) を用いて変更することができる。 schedparam (スケジューリングパラメータ) スレッドのスケジューリングパラメータ (特に、スケジューリング優先度) を指定する。スケジューリングパラメータに関するさらなる情報については sched_setparam(2) を参照のこと。デフォルト値: 優先度は 0 。この属性はスケジューリングポリシーが SCHED_OTHER の時には意味を持たず、リアルタイムポリシー SCHED_RR と SCHED_FIFO に対してのみ有効である。スレッドのスケジューリング優先度は、生成後に pthread_setschedparam(3) を用いて変更することができる。 inheritsched (スケジューリングの継承) 新しく生成されるスレッドのスケジューリングポリシーとスケジューリングパラメータが属性 schedpolicy および schedparam の値で決定される ( PTHREAD_EXPLICIT_SCHED) か、親スレッドから継承される ( PTHREAD_INHERIT_SCHED) かを指定する。デフォルト値: PTHREAD_EXPLICIT_SCHED 。 scope (スコープ) 生成されるスレッドのスケジューリング競争スコープを定義する。 Linux- Threads の実装で唯一対応している値は PTHREAD_SCOPE_SYSTEM で、スレッドは同じ計算機で実行中のすべてのプロセスと CPU 時間を取り合う。詳しくいえば、スレッドの優先度は計算機上の他のすべてのプロセスの優先度と同列のものと解釈される。 POSIX 標準で規定されるもう 1 つの値 PTHREAD_SCOPE_PRO- CESS は、スケジューリングの競争は実行中のプロセス中のスレッド間だけで起こることを意味する。すなわち、スレッドの優先度はプロセス中の他のスレッドの優先度と同列のものと解釈され、他のプロセスの優先度とは関わりがない。 LinuxThreads は PTHREAD_SCOPE_PROCESS に対応していない。デフォルト値: PTHREAD_SCOPE_SYSTEM 。返り値すべての関数は成功すると 0 を返し、エラーならば非 0 のエラーコードを返す。成功の場合、関数群 pthread_attr_getattrname は属性 attrname の現在の値を第 2 引数で指し示される領域に格納する。エラー関数 pthread_attr_setdetachstate はエラーの場合、次のようなエラーコードを返す: EINVAL 指定された detachstate が PTHREAD_CREATE_JOINABLE および PTHREAD_CREATE_DETACHED のいずれでもない。関数 pthread_attr_setschedparam はエラーの場合、次のようなエラーコードを返す: EINVAL param で指定された優先度が現在の attr のスケジューリングポリシーに対する許容範囲 ( SCHED_FIFO および SCHED_RR の場合は 1 から 99 まで、 SCHED_OTHER の場合は 0 のみ ) を超えている。関数 pthread_attr_setschedpolicy はエラーの場合次のようなエラーコードを返す: EINVAL 指定された policy が SCHED_OTHER および SCHED_FIFO 、 SCHED_RR のいずれでもない ENOTSUP policy が SCHED_FIFO または SCHED_RR であって、呼び出しプロセスの実効ユーザがスーパーユーザではない。関数 pthread_attr_setinheritsched はエラーの場合次のようなエラーコードを返す: EINVAL 指定された inherit が PTHREAD_INHERIT_SCHED および PTHREAD_EXPLICIT_SCHED のいずれでもない。関数 pthread_attr_setscope はエラーの場合次のようなエラーコードを返す: EINVAL 指定された scope が PTHREAD_SCOPE_SYSTEM および PTHREAD_SCOPE_PROCESS のいずれでもない。 ENOTSUP 指定された scope が PTHREAD_SCOPE_PROCESS (未対応) である。著者 Xavier Leroy 関連項目 pthread_create(3), pthread_join(3), pthread_detach(3), pthread_setschedparam(3). [訳注] glibc-linuxthreads の最新のドキュメントは Texinfo形式で提供されている。以下は glibc-linuxthreads-2.3.1 の Texinfo ファイルからの引用で、「説明」に追記されている。 glibc-linuxthreads-2.1 以降 guardsize および stackaddr 、 stacksize が、 glibc-linuxthreads-2.2 以降 stack が追加された。 int pthread_attr_setstackaddr(pthread_attr_t *attr, void *stackaddr); int pthread_attr_getstackaddr(const pthread_attr_t *attr, void **stack- addr); stackaddr (スタックアドレス) アプリケーション管理スタックのアドレスを指定する。スタックのサイズは PTHREAD_STACK_MIN 以上でなければならない。 int pthread_attr_setstacksize(pthread_attr_t *attr, size_t stack- size");" int pthread_attr_getstacksize(const pthread_attr_t *attr, size_t *stacksize); stacksize (スタックサイズ) スレッドに対して確保されるスタックのサイズを変更する。最小スタックサイズが指定した値に設定される。単位はバイトである。指定した値がシステムの最大スタックサイズを超える場合、または PTHREAD_STACK_MIN よりも小さい場合、 pthread_attr_setstacksize は失敗し、 EINVAL を返す。 int pthread_attr_setstack(pthread_attr_t *attr, void *stackaddr, size_t stacksize); int pthread_attr_getstack(const pthread_attr_t *attr, void **stackaddr, size_t *stacksize); stack (スタック) 生成されるスレッドに用いられるアプリケーション管理スタックのアドレスとサイズの両方を指定する。メモリ領域のベースを stackaddr に、メモリ領域のサイズをバイト単位で stacksize に指定する。 stacksize の値が PTHREAD_STACK_MIN よりも小さいか、システムの最大スタックサイズを超える場合、または stackaddr の値が適切なアライメントでない場合、 pthread_attr_setstack は失敗し、 EINVAL を返す。 int pthread_attr_setguardsize(pthread_attr_t *attr, size_t guardsize); int pthread_attr_getguardsize(const pthread_attr_t *attr, size_t *guardsize); guardsize (保護サイズ) スレッドのスタックの保護領域の最小のサイズをバイト単位で変更する。デフォルトのサイズは 1 ページである。この値が設定された場合、指定した値以上の最も近いページサイズに丸められる。この値が 0 に設定された場合、このスレッドには保護領域は作成されない。保護領域として確保された領域は、スタックオーバーフローを検出するのに用いられる。したがって、大きな構造体の領域をスタック内に確保する場合、スタックオーバーフローを検出するためにはそれよりも大きい保護領域を指定する必要がある。スレッドが独自のスタックを使用している場合( stackaddr 属性が設定されている場合) 、 guardsize 属性は無視される。指定した値が stacksize を超える場合、 pthread_attr_setguardsize は失敗し、 EINVAL を返す。 LinuxThreads PTHREAD_ATTR_INIT(3)

PTHREAD_ATTR_INIT(3) Linux Programmer’s Manual PTHREAD_ATTR_INIT(3) NAME pthread_attr_init, pthread_attr_destroy - initialize and destroy thread attributes object SYNOPSIS #include int pthread_attr_init(pthread_attr_t *attr); int pthread_attr_destroy(pthread_attr_t *attr); Compile and link with -pthread. DESCRIPTION The pthread_attr_init() function initializes the thread attributes object pointed to by attr with default attribute values. After this call, individual attributes of the object can be set using various related functions (listed under SEE ALSO), and then the object can be used in one or more pthread_create(3) calls that create threads. Calling pthread_attr_init() on a thread attributes object that has already been initialized results in undefined behavior. When a thread attributes object is no longer required, it should be destroyed using the pthread_attr_destroy() function. Destroying a thread attributes object has no effect on threads that were created using that object. Once a thread attributes object has been destroyed, it can be reini- tialized using pthread_attr_init(). Any other use of a destroyed thread attributes object has undefined results. RETURN VALUE On success, these functions return 0; on error, they return a non-zero error number. ERRORS POSIX.1-2001 documents an ENOMEM error for pthread_attr_init(); on Linux these functions always succeed (but portable and future-proof applications should nevertheless handle a possible error return). CONFORMING TO POSIX.1-2001. NOTES The pthread_attr_t type should be treated as opaque: any access to the object other than via pthreads functions is non-portable and produces undefined results. EXAMPLE The program below optionally makes use of pthread_attr_init() and vari- ous related functions to initialize a thread attributes object that is used to create a single thread. Once created, the thread uses the pthread_getattr_np() function (a non-standard GNU extension) to retrieve the thread’s attributes, and then displays those attributes. If the program is run with no command-line argument, then it passes NULL as the attr argument of pthread_create(3), so that the thread is created with default attributes. Running the program on Linux/x86-32 with the NPTL threading implementation, we see the following: $ ulimit -s # No stack imit ==> default stack size is 2MB unlimited $ ./a.out Thread attributes: Detach state = PTHREAD_CREATE_JOINABLE Scope = PTHREAD_SCOPE_SYSTEM Inherit scheduler = PTHREAD_INHERIT_SCHED Scheduling policy = SCHED_OTHER Scheduling priority = 0 Guard size = 4096 bytes Stack address = 0x40196000 Stack size = 0x201000 bytes When we supply a stack size as a command-line argument, the program initializes a thread attributes object, sets various attributes in that object, and passes a pointer to the object in the call to pthread_cre- ate(3). Running the program on Linux/x86-32 with the NPTL threading implementation, we see the following: $ ./a.out 0x3000000 posix_memalign() allocated at 0x40197000 Thread attributes: Detach state = PTHREAD_CREATE_DETACHED Scope = PTHREAD_SCOPE_SYSTEM Inherit scheduler = PTHREAD_EXPLICIT_SCHED Scheduling policy = SCHED_OTHER Scheduling priority = 0 Guard size = 0 bytes Stack address = 0x40197000 Stack size = 0x3000000 bytes Program source #define _GNU_SOURCE /* To get pthread_getattr_np() declaration */ #include #include #include #include #include #define handle_error_en(en, msg) \ do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0) static void display_pthread_attr(pthread_attr_t *attr, char *prefix) { int s, i; size_t v; void *stkaddr; struct sched_param sp; s = pthread_attr_getdetachstate(attr, &i); if (s != 0) handle_error_en(s, "pthread_attr_getdetachstate"); printf("%sDetach state = %s\n", prefix, (i == PTHREAD_CREATE_DETACHED) ? "PTHREAD_CREATE_DETACHED" : (i == PTHREAD_CREATE_JOINABLE) ? "PTHREAD_CREATE_JOINABLE" : "???"); s = pthread_attr_getscope(attr, &i); if (s != 0) handle_error_en(s, "pthread_attr_getscope"); printf("%sScope = %s\n", prefix, (i == PTHREAD_SCOPE_SYSTEM) ? "PTHREAD_SCOPE_SYSTEM" : (i == PTHREAD_SCOPE_PROCESS) ? "PTHREAD_SCOPE_PROCESS" : "???"); s = pthread_attr_getinheritsched(attr, &i); if (s != 0) handle_error_en(s, "pthread_attr_getinheritsched"); printf("%sInherit scheduler = %s\n", prefix, (i == PTHREAD_INHERIT_SCHED) ? "PTHREAD_INHERIT_SCHED" : (i == PTHREAD_EXPLICIT_SCHED) ? "PTHREAD_EXPLICIT_SCHED" : "???"); s = pthread_attr_getschedpolicy(attr, &i); if (s != 0) handle_error_en(s, "pthread_attr_getschedpolicy"); printf("%sScheduling policy = %s\n", prefix, (i == SCHED_OTHER) ? "SCHED_OTHER" : (i == SCHED_FIFO) ? "SCHED_FIFO" : (i == SCHED_RR) ? "SCHED_RR" : "???"); s = pthread_attr_getschedparam(attr, &sp); if (s != 0) handle_error_en(s, "pthread_attr_getschedparam"); printf("%sScheduling priority = %d\n", prefix, sp.sched_priority); s = pthread_attr_getguardsize(attr, &v); if (s != 0) handle_error_en(s, "pthread_attr_getguardsize"); printf("%sGuard size = %d bytes\n", prefix, v); s = pthread_attr_getstack(attr, &stkaddr, &v); if (s != 0) handle_error_en(s, "pthread_attr_getstack"); printf("%sStack address = %p\n", prefix, stkaddr); printf("%sStack size = 0x%x bytes\n", prefix, v); } static void * thread_start(void *arg) { int s; pthread_attr_t gattr; /* pthread_getattr_np() is a non-standard GNU extension that retrieves the attributes of the thread specified in its first argument */ s = pthread_getattr_np(pthread_self(), &gattr); if (s != 0) handle_error_en(s, "pthread_getattr_np"); printf("Thread attributes:\n"); display_pthread_attr(&gattr, "\t"); exit(EXIT_SUCCESS); /* Terminate all threads */ } int main(int argc, char *argv[]) { pthread_t thr; pthread_attr_t attr; pthread_attr_t *attrp; /* NULL or &attr */ int s; attrp = NULL; /* If a command-line argument was supplied, use it to set the stack-size attribute and set a few other thread attributes, and set attrp pointing to thread attributes object */ if (argc > 1) { int stack_size; void *sp; attrp = &attr; s = pthread_attr_init(&attr); if (s != 0) handle_error_en(s, "pthread_attr_init"); s = pthread_attr_setdetachstate(&attr, PTHREAD_CREATE_DETACHED); if (s != 0) handle_error_en(s, "pthread_attr_setdetachstate"); s = pthread_attr_setinheritsched(&attr, PTHREAD_EXPLICIT_SCHED); if (s != 0) handle_error_en(s, "pthread_attr_setinheritsched"); stack_size = strtoul(argv[1], NULL, 0); s = posix_memalign(&sp, sysconf(_SC_PAGESIZE), stack_size); if (s != 0) handle_error_en(s, "posix_memalign"); printf("posix_memalign() allocated at %p\n", sp); s = pthread_attr_setstack(&attr, sp, stack_size); if (s != 0) handle_error_en(s, "pthread_attr_setstack"); } s = pthread_create(&thr, attrp, &thread_start, NULL); if (s != 0) handle_error_en(s, "pthread_create"); if (attrp != NULL) { s = pthread_attr_destroy(attrp); if (s != 0) handle_error_en(s, "pthread_attr_destroy"); } pause(); /* Terminates when other thread calls exit() */ } SEE ALSO pthread_attr_setaffinity_np(3), pthread_attr_setdetachstate(3), pthread_attr_setguardsize(3), pthread_attr_setinheritsched(3), pthread_attr_setschedparam(3), pthread_attr_setschedpolicy(3), pthread_attr_setscope(3), pthread_attr_setstack(3), pthread_attr_set- stackaddr(3), pthread_attr_setstacksize(3), pthread_create(3), pthread_getattr_np(3), pthreads(7) COLOPHON This page is part of release 3.22 of the Linux man-pages project. A description of the project, and information about reporting bugs, can be found at http://www.kernel.org/doc/man-pages/. Linux 2008-11-11 PTHREAD_ATTR_INIT(3)

リナックスコマンド