manual/glibc-linuxthreads/release/man3/pthread_key_create.3

   1 .\"   Copyright (C) 1996-1999 Free Software Foundation, Inc.
   2 .\"
   3 .\"   Permission is granted to make and distribute verbatim copies of
   4 .\" this manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\"   Permission is granted to copy and distribute modified versions of
   8 .\" this manual under the conditions for verbatim copying, provided that
   9 .\" the entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\"   Permission is granted to copy and distribute translations of this
  13 .\" manual into another language, under the above conditions for modified
  14 .\" versions, except that this permission notice may be stated in a
  15 .\" translation approved by the Foundation.
  16 .\"
  17 .\" Copyright (C) 1996 Xavier Leroy.
  18 .\"
  19 .\" Japanese Version Copyright (C) 2002-2003 Suzuki Takashi
  20 .\"         all rights reserved.
  21 .\" Translated Tue Dec 31 23:11:09 JST 2002
  22 .\"         by Suzuki Takashi.
  23 .\"
  24 .\"WORD:    thread-specific data    スレッド固有データ
  25 .\"WORD:    thread-specific key スレッド固有キー
  26 .\"WORD:    destructor function デストラクタ関数
  27 .\"
  28 .\"
  29 .TH PTHREAD_SPECIFIC 3 LinuxThreads
  30
  31 .SH "名前"
  32 pthread_key_create, pthread_key_delete, pthread_setspecific, pthread_getspecific \- スレッド固有データの管理
  33
  34 .SH "書式"
  35 .B #include <pthread.h>
  36
  37 .BI "int pthread_key_create(pthread_key_t *" key ", void (*" destr_function ") (void *));"
  38
  39 .BI "int pthread_key_delete(pthread_key_t " key ");"
  40
  41 .BI "int pthread_setspecific(pthread_key_t " key ", const void *" pointer ");"
  42
  43 .BI "void * pthread_getspecific(pthread_key_t " key ");"
  44
  45 .SH "説明"
  46
  47 プログラムではスレッドごとに値の異なる
  48 グローバル変数や静的変数がしばしば必要となる。
  49 複数のスレッドは 1 つのメモリ空間を共有するため、
  50 通常の変数ではこれを実現することができない。
  51 スレッド固有データは、
  52 この必要性への POSIX スレッドの答えである。
  53
  54 それぞれのスレッドはスレッド固有データ (thread-specific data) 領域、
  55 略して TSD 領域という
  56 プライベートなメモリブロックを保有している。
  57 この領域は TSD キーをインデックスとして管理される。
  58 TSD 領域では
  59 .B "void *"
  60 型の値を TSD キーに結び付ける。
  61 TSD キーはすべてのスレッドに共通であるが、
  62 TSD キーに結び付けられる値はスレッドごとに異なるように
  63 することができる。
  64
  65 具体的にいえば、 TSD 領域は
  66 .B "void *"
  67 型のポインタの配列として、
  68 TSD キーはこの配列に対する整数値のインデックスとして、
  69 TSD キーに結び付けられる値は呼び出しスレッドの対応する配列要素として見える。
  70
  71 スレッドが生成されると、TSD 領域はすべてのキーに対する値が
  72 .B "NULL"
  73 になるよう初期化される。
  74
  75 .B "pthread_key_create"
  76 は新しい TSD キーを確保する。
  77 キーは
  78 .I "key"
  79 で指し示される領域に格納される。
  80 ある時点で確保できるキーの数には制限があり、
  81 その最大値は
  82 .B "PTHREAD_KEYS_MAX"
  83 である。
  84 返されたキーに結び付けられる初期値は、
  85 その時点で実行されているスレッドすべてにおいて
  86 .B "NULL"
  87 である。
  88
  89 引数
  90 .I "destr_function"
  91 に
  92 .B "NULL"
  93 以外の値を指定することで、
  94 そのキーに対応するデストラクタ関数を登録することができる。
  95 スレッドが
  96 .B "pthread_exit"
  97 やキャンセルによって終了すると、
  98 そのスレッド中でキーに結び付けられた値を引数として関数
  99 .I "destr_function"
 100 が呼び出される。
 101 値が
 102 .B "NULL"
 103 の場合には関数
 104 .I "destr_function"
 105 は呼び出されない。
 106 スレッド終了時にデストラクタ関数が呼び出される順序は不定である。
 107
 108 デストラクタ関数が呼び出される前に、
 109 現在のスレッドにおいてキーに結び付けられる値は
 110 .B "NULL"
 111 になる。
 112 しかし、デストラクタ関数は
 113 .B "NULL"
 114 以外の値をそのキーやほかのキーに結び付けるかもしれない。
 115 これを処理するため、
 116 すべての非
 117 .B "NULL"
 118 の値に対するデストラクタ関数をすべて呼び出したあとに
 119 デストラクタ関数のある非
 120 .B "NULL"
 121 の値がまだ残っている場合には、
 122 デストラクタ関数の呼び出し処理は繰り返される。
 123 LinuxThreads の実装では、
 124 .B "PTHREAD_DESTRUCTOR_ITERATIONS"
 125 回繰り返すと、たとえデストラクタ関数のある非
 126 .B "NULL"
 127 の値が残っていても、
 128 処理は中止される。LinuxThreads 以外の実装では無限ループに陥るかもしれない。
 129
 130 .B "pthread_key_delete"
 131 は TSD キーを解放する。
 132 その時点で実行中のスレッドでキーに非
 133 .B "NULL"
 134 の値が結び付けられているかどうかをチェックしたり、
 135 キーに対応するデストラクタ関数を呼び出したりはしない。
 136
 137 .B "pthread_setspecific"
 138 は呼び出しスレッドで
 139 .I "key"
 140 に結び付けられる値を、与えられた
 141 .I "pointer"
 142 に変更する。
 143
 144 .B "pthread_getspecific"
 145 は呼び出しスレッドでその時点で
 146 .I "key"
 147 に結び付けられている値を返す。
 148
 149 .SH "返り値"
 150
 151 .B "pthread_key_create"
 152 および
 153 .B "pthread_key_delete"
 154 、
 155 .B "pthread_setspecific"
 156 は成功すると 0 を、失敗すると非 0 のエラーコードを返す。
 157 成功の場合、
 158 .B "pthread_key_create"
 159 は新しく確保されたキーを
 160 引数
 161 .I "key"
 162 で指し示される領域に格納する。
 163
 164 .B "pthread_getspecific"
 165 は、成功するとキー
 166 .I "key"
 167 に結び付けられた値を、
 168 エラーの場合には
 169 .B "NULL"
 170 を返す。
 171
 172 .SH "エラー"
 173 .B "pthread_key_create"
 174 はエラーの場合に次のようなエラーコードを返す:
 175 .RS
 176 .TP
 177 .B "EAGAIN"
 178 .B "PTHREAD_KEYS_MAX"
 179 だけのキーがすでに確保されている。
 180 .RE
 181
 182 .B "pthread_key_delete"
 183 および
 184 .B "pthread_setspecific"
 185 はエラーの場合に次のようなエラーコードを返す:
 186 .RS
 187 .TP
 188 .B "EINVAL"
 189 .I "key"
 190 は有効な、確保された TSD キーではない。
 191 .RE
 192
 193 .B "pthread_getspecific"
 194 は、
 195 .I "key"
 196 が有効な、確保された TSD キーでない場合には
 197 .B "NULL"
 198 を返す。
 199
 200 .SH "著者"
 201 Xavier Leroy <Xavier.Leroy@inria.fr>
 202
 203 .SH "関連項目"
 204 pthread_create(3), pthread_exit(3), pthread_testcancel(3).
 205
 206 .SH "例"
 207
 208 次のコードでは、100 バイトのスレッド固有の配列を確保し、
 209 スレッドの終了とともに自動で解放する:
 210
 211 .RS
 212 .ft 3
 213 .nf
 214 .sp
 215 /* スレッド固有バッファのキー */
 216 static pthread_key_t buffer_key;
 217
 218 /* 1 回限りのキーの初期化 */
 219 static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT;
 220
 221 /* スレッド固有のバッファを確保する */
 222 void buffer_alloc(void)
 223 {
 224   pthread_once(&buffer_key_once, buffer_key_alloc);
 225   pthread_setspecific(buffer_key, malloc(100));
 226 }
 227
 228 /* スレッド固有のバッファを返す */
 229 char * get_buffer(void)
 230 {
 231   return (char *) pthread_getspecific(buffer_key);
 232 }
 233
 234 /* キーを確保する */
 235 static void buffer_key_alloc()
 236 {
 237   pthread_key_create(&buffer_key, buffer_destroy);
 238 }
 239
 240 /* スレッド固有のバッファを解放する */
 241 static void buffer_destroy(void * buf)
 242 {
 243   free(buf);
 244 }
 245 .ft
 246 .LP
 247 .RE
 248 .fi