[ae68ff0] | 1 | @c |
---|
[0660b4f8] | 2 | @c COPYRIGHT (c) 1988-1999. |
---|
[7479042] | 3 | @c On-Line Applications Research Corporation (OAR). |
---|
| 4 | @c All rights reserved. |
---|
[ae68ff0] | 5 | @c |
---|
[7479042] | 6 | @c $Id$ |
---|
[139b2e4a] | 7 | @c |
---|
[ae68ff0] | 8 | |
---|
| 9 | @chapter Thread Manager |
---|
[c4dddee] | 10 | |
---|
[ae68ff0] | 11 | @section Introduction |
---|
| 12 | |
---|
[d48ea69] | 13 | The thread manager implements the functionality required of the thread |
---|
[7479042] | 14 | manager as defined by POSIX 1003.1b-1996. This standard requires that |
---|
[d48ea69] | 15 | a compliant operating system provide the facilties to manage multiple |
---|
| 16 | threads of control and defines the API that must be provided. |
---|
[ae68ff0] | 17 | |
---|
[1b67be71] | 18 | The services provided by the thread manager are: |
---|
[ae68ff0] | 19 | |
---|
| 20 | @itemize @bullet |
---|
[d48ea69] | 21 | @item @code{pthread_attr_init} - Initialize a Thread Attribute Set |
---|
| 22 | @item @code{pthread_attr_destroy} - Destroy a Thread Attribute Set |
---|
| 23 | @item @code{pthread_attr_setdetachstate} - Set Detach State |
---|
| 24 | @item @code{pthread_attr_getdetachstate} - Get Detach State |
---|
| 25 | @item @code{pthread_attr_setstacksize} - Set Thread Stack Size |
---|
| 26 | @item @code{pthread_attr_getstacksize} - Get Thread Stack Size |
---|
| 27 | @item @code{pthread_attr_setstackaddr} - Set Thread Stack Address |
---|
| 28 | @item @code{pthread_attr_getstackaddr} - Get Thread Stack Address |
---|
| 29 | @item @code{pthread_attr_setscope} - Set Thread Scheduling Scope |
---|
| 30 | @item @code{pthread_attr_getscope} - Get Thread Scheduling Scope |
---|
| 31 | @item @code{pthread_attr_setinheritsched} - Set Inherit Scheduler Flag |
---|
| 32 | @item @code{pthread_attr_getinheritsched} - Get Inherit Scheduler Flag |
---|
| 33 | @item @code{pthread_attr_setschedpolicy} - Set Scheduling Policy |
---|
| 34 | @item @code{pthread_attr_getschedpolicy} - Get Scheduling Policy |
---|
| 35 | @item @code{pthread_attr_setschedparam} - Set Scheduling Parameters |
---|
| 36 | @item @code{pthread_attr_getschedparam} - Get Scheduling Parameters |
---|
| 37 | @item @code{pthread_create} - Create a Thread |
---|
| 38 | @item @code{pthread_exit} - Terminate the Current Thread |
---|
| 39 | @item @code{pthread_detach} - Detach a Thread |
---|
| 40 | @item @code{pthread_join} - Wait for Thread Termination |
---|
| 41 | @item @code{pthread_self} - Get Thread ID |
---|
| 42 | @item @code{pthread_equal} - Compare Thread IDs |
---|
| 43 | @item @code{pthread_once} - Dynamic Package Initialization |
---|
| 44 | @item @code{pthread_setschedparam} - Set Thread Scheduling Parameters |
---|
| 45 | @item @code{pthread_getschedparam} - Get Thread Scheduling Parameters |
---|
[ae68ff0] | 46 | @end itemize |
---|
| 47 | |
---|
| 48 | @section Background |
---|
[c4dddee] | 49 | |
---|
[ae68ff0] | 50 | @subsection Thread Attributes |
---|
| 51 | |
---|
[7479042] | 52 | Thread attributes are utilized only at thread creation time. A thread |
---|
[d48ea69] | 53 | attribute structure may be initialized and passed as an argument to |
---|
| 54 | the @code{pthread_create} routine. |
---|
[ae68ff0] | 55 | |
---|
| 56 | @table @b |
---|
| 57 | @item stack address |
---|
| 58 | is the address of the optionally user specified stack area for this thread. |
---|
[7479042] | 59 | If this value is NULL, then RTEMS allocates the memory for the thread stack |
---|
| 60 | from the RTEMS Workspace Area. Otherwise, this is the user specified |
---|
| 61 | address for the memory to be used for the thread's stack. Each thread must |
---|
| 62 | have a distinct stack area. Each processor family has different alignment |
---|
[ae68ff0] | 63 | rules which should be followed. |
---|
| 64 | |
---|
| 65 | @item stack size |
---|
| 66 | is the minimum desired size for this thread's stack area. |
---|
[7479042] | 67 | If the size of this area as specified by the stack size attribute |
---|
| 68 | is smaller than the minimum for this processor family and the stack |
---|
| 69 | is not user specified, then RTEMS will automatically allocate a |
---|
[ae68ff0] | 70 | stack of the minimum size for this processor family. |
---|
| 71 | |
---|
| 72 | @item contention scope |
---|
[7479042] | 73 | specifies the scheduling contention scope. RTEMS only supports the |
---|
[ae68ff0] | 74 | PTHREAD_SCOPE_PROCESS scheduling contention scope. |
---|
| 75 | |
---|
| 76 | @item scheduling inheritance |
---|
[7479042] | 77 | specifies whether a user specified or the scheduling policy and |
---|
| 78 | parameters of the currently executing thread are to be used. When |
---|
| 79 | this is PTHREAD_INHERIT_SCHED, then the scheduling policy and |
---|
| 80 | parameters of the currently executing thread are inherited by |
---|
[ae68ff0] | 81 | the newly created thread. |
---|
| 82 | |
---|
| 83 | @item scheduling policy and parameters |
---|
| 84 | specify the manner in which the thread will contend for the processor. |
---|
| 85 | The scheduling parameters are interpreted based on the specified policy. |
---|
| 86 | All policies utilize the thread priority parameter. |
---|
| 87 | |
---|
| 88 | @end table |
---|
| 89 | |
---|
| 90 | @section Operations |
---|
| 91 | |
---|
[c4dddee] | 92 | There is currently no text in this section. |
---|
| 93 | |
---|
[1b67be71] | 94 | @section Services |
---|
[ae68ff0] | 95 | |
---|
[1b67be71] | 96 | This section details the thread manager's services. |
---|
| 97 | A subsection is dedicated to each of this manager's services |
---|
[ae68ff0] | 98 | and describes the calling sequence, related constants, usage, |
---|
| 99 | and status codes. |
---|
| 100 | |
---|
[7479042] | 101 | @c |
---|
| 102 | @c |
---|
| 103 | @c |
---|
[ae68ff0] | 104 | @page |
---|
[d48ea69] | 105 | @subsection pthread_attr_init - Initialize a Thread Attribute Set |
---|
[ae68ff0] | 106 | |
---|
[7479042] | 107 | @findex pthread_attr_init |
---|
| 108 | @cindex initialize a thread attribute set |
---|
| 109 | |
---|
[ae68ff0] | 110 | @subheading CALLING SEQUENCE: |
---|
| 111 | |
---|
| 112 | |
---|
| 113 | @example |
---|
| 114 | #include <pthread.h> |
---|
| 115 | |
---|
| 116 | int pthread_attr_init( |
---|
[7479042] | 117 | pthread_attr_t *attr |
---|
[ae68ff0] | 118 | ); |
---|
| 119 | @end example |
---|
| 120 | |
---|
| 121 | @subheading STATUS CODES: |
---|
| 122 | |
---|
| 123 | @table @b |
---|
| 124 | @item EINVAL |
---|
| 125 | The attribute pointer argument is invalid. |
---|
| 126 | |
---|
| 127 | @end table |
---|
| 128 | |
---|
| 129 | @subheading DESCRIPTION: |
---|
| 130 | |
---|
[d48ea69] | 131 | The @code{pthread_attr_init} routine initializes the thread attributes |
---|
| 132 | object specified by @code{attr} with the default value for all of the |
---|
| 133 | individual attributes. |
---|
| 134 | |
---|
[ae68ff0] | 135 | @subheading NOTES: |
---|
| 136 | |
---|
[7479042] | 137 | The settings in the default attributes are implementation defined. For |
---|
[d48ea69] | 138 | RTEMS, the default attributes are as follows: |
---|
| 139 | |
---|
| 140 | @itemize @bullet |
---|
| 141 | |
---|
| 142 | @item stackadr |
---|
| 143 | is not set to indicate that RTEMS is to allocate the stack memory. |
---|
| 144 | |
---|
| 145 | @item stacksize |
---|
| 146 | is set to @code{PTHREAD_MINIMUM_STACK_SIZE}. |
---|
| 147 | |
---|
| 148 | @item contentionscope |
---|
| 149 | is set to @code{PTHREAD_SCOPE_PROCESS}. |
---|
| 150 | |
---|
| 151 | @item inheritsched |
---|
| 152 | is set to @code{PTHREAD_INHERIT_SCHED} to indicate that the created |
---|
| 153 | thread inherits its scheduling attributes from its parent. |
---|
| 154 | |
---|
| 155 | @item detachstate |
---|
| 156 | is set to @code{PTHREAD_CREATE_JOINABLE}. |
---|
| 157 | |
---|
| 158 | @end itemize |
---|
| 159 | |
---|
| 160 | |
---|
[7479042] | 161 | @c |
---|
| 162 | @c |
---|
| 163 | @c |
---|
[ae68ff0] | 164 | @page |
---|
[d48ea69] | 165 | @subsection pthread_attr_destroy - Destroy a Thread Attribute Set |
---|
[ae68ff0] | 166 | |
---|
[7479042] | 167 | @findex pthread_attr_destroy |
---|
| 168 | @cindex destroy a thread attribute set |
---|
| 169 | |
---|
[ae68ff0] | 170 | @subheading CALLING SEQUENCE: |
---|
| 171 | |
---|
| 172 | @example |
---|
| 173 | #include <pthread.h> |
---|
[7479042] | 174 | |
---|
[ae68ff0] | 175 | int pthread_attr_destroy( |
---|
[7479042] | 176 | pthread_attr_t *attr |
---|
[ae68ff0] | 177 | ); |
---|
| 178 | @end example |
---|
| 179 | |
---|
| 180 | @subheading STATUS CODES: |
---|
[7479042] | 181 | |
---|
[ae68ff0] | 182 | @table @b |
---|
| 183 | @item EINVAL |
---|
| 184 | The attribute pointer argument is invalid. |
---|
| 185 | |
---|
| 186 | @item EINVAL |
---|
| 187 | The attribute set is not initialized. |
---|
[7479042] | 188 | |
---|
[ae68ff0] | 189 | @end table |
---|
[7479042] | 190 | |
---|
[ae68ff0] | 191 | @subheading DESCRIPTION: |
---|
| 192 | |
---|
[d48ea69] | 193 | The @code{pthread_attr_destroy} routine is used to destroy a thread |
---|
[7479042] | 194 | attributes object. The behavior of using an attributes object after |
---|
[d48ea69] | 195 | it is destroyed is implementation dependent. |
---|
| 196 | |
---|
[ae68ff0] | 197 | @subheading NOTES: |
---|
| 198 | |
---|
[d48ea69] | 199 | NONE |
---|
| 200 | |
---|
[7479042] | 201 | @c |
---|
| 202 | @c |
---|
| 203 | @c |
---|
[ae68ff0] | 204 | @page |
---|
[d48ea69] | 205 | @subsection pthread_attr_setdetachstate - Set Detach State |
---|
[ae68ff0] | 206 | |
---|
[7479042] | 207 | @findex pthread_attr_setdetachstate |
---|
| 208 | @cindex set detach state |
---|
| 209 | |
---|
[ae68ff0] | 210 | @subheading CALLING SEQUENCE: |
---|
| 211 | |
---|
| 212 | @example |
---|
| 213 | #include <pthread.h> |
---|
[7479042] | 214 | |
---|
[ae68ff0] | 215 | int pthread_attr_setdetachstate( |
---|
[7479042] | 216 | pthread_attr_t *attr, |
---|
| 217 | int detachstate |
---|
[ae68ff0] | 218 | ); |
---|
| 219 | @end example |
---|
| 220 | |
---|
| 221 | @subheading STATUS CODES: |
---|
[7479042] | 222 | |
---|
[ae68ff0] | 223 | @table @b |
---|
| 224 | @item EINVAL |
---|
| 225 | The attribute pointer argument is invalid. |
---|
| 226 | |
---|
| 227 | @item EINVAL |
---|
| 228 | The attribute set is not initialized. |
---|
[7479042] | 229 | |
---|
[ae68ff0] | 230 | @item EINVAL |
---|
| 231 | The detachstate argument is invalid. |
---|
[7479042] | 232 | |
---|
[ae68ff0] | 233 | @end table |
---|
| 234 | |
---|
| 235 | @subheading DESCRIPTION: |
---|
| 236 | |
---|
[7479042] | 237 | The @code{pthread_attr_setdetachstate} routine is used to value of the |
---|
| 238 | @code{detachstate} attribute. This attribute controls whether the |
---|
| 239 | thread is created in a detached state. |
---|
[d48ea69] | 240 | |
---|
| 241 | The @code{detachstate} can be either @code{PTHREAD_CREATE_DETACHED} or |
---|
[7479042] | 242 | @code{PTHREAD_CREATE_JOINABLE}. The default value for all threads is |
---|
[d48ea69] | 243 | @code{PTHREAD_CREATE_JOINABLE}. |
---|
| 244 | |
---|
[ae68ff0] | 245 | @subheading NOTES: |
---|
| 246 | |
---|
[d48ea69] | 247 | If a thread is in a detached state, |
---|
| 248 | then the use of the ID with the @code{pthread_detach} or |
---|
| 249 | @code{pthread_join} routines is an error. |
---|
| 250 | |
---|
[7479042] | 251 | @c |
---|
| 252 | @c |
---|
| 253 | @c |
---|
[ae68ff0] | 254 | @page |
---|
[d48ea69] | 255 | @subsection pthread_attr_getdetachstate - Get Detach State |
---|
[ae68ff0] | 256 | |
---|
[7479042] | 257 | @findex pthread_attr_getdetachstate |
---|
| 258 | @cindex get detach state |
---|
| 259 | |
---|
[ae68ff0] | 260 | @subheading CALLING SEQUENCE: |
---|
| 261 | |
---|
| 262 | @example |
---|
| 263 | #include <pthread.h> |
---|
[7479042] | 264 | |
---|
[ae68ff0] | 265 | int pthread_attr_getdetachstate( |
---|
[7479042] | 266 | const pthread_attr_t *attr, |
---|
| 267 | int *detachstate |
---|
[ae68ff0] | 268 | ); |
---|
| 269 | @end example |
---|
| 270 | |
---|
| 271 | @subheading STATUS CODES: |
---|
[7479042] | 272 | |
---|
[ae68ff0] | 273 | @table @b |
---|
| 274 | @item EINVAL |
---|
| 275 | The attribute pointer argument is invalid. |
---|
| 276 | |
---|
| 277 | @item EINVAL |
---|
| 278 | The attribute set is not initialized. |
---|
[7479042] | 279 | |
---|
[ae68ff0] | 280 | @item EINVAL |
---|
| 281 | The detatchstate pointer argument is invalid. |
---|
| 282 | |
---|
| 283 | @end table |
---|
[7479042] | 284 | |
---|
[ae68ff0] | 285 | @subheading DESCRIPTION: |
---|
| 286 | |
---|
[d48ea69] | 287 | The @code{pthread_attr_getdetachstate} routine is used to obtain the |
---|
| 288 | current value of the @code{detachstate} attribute as specified |
---|
| 289 | by the @code{attr} thread attribute object. |
---|
| 290 | |
---|
[ae68ff0] | 291 | @subheading NOTES: |
---|
| 292 | |
---|
[d48ea69] | 293 | NONE |
---|
| 294 | |
---|
[7479042] | 295 | @c |
---|
| 296 | @c |
---|
| 297 | @c |
---|
[ae68ff0] | 298 | @page |
---|
[d48ea69] | 299 | @subsection pthread_attr_setstacksize - Set Thread Stack Size |
---|
[ae68ff0] | 300 | |
---|
[7479042] | 301 | @findex pthread_attr_setstacksize |
---|
| 302 | @cindex set thread stack size |
---|
| 303 | |
---|
[ae68ff0] | 304 | @subheading CALLING SEQUENCE: |
---|
| 305 | |
---|
| 306 | @example |
---|
| 307 | #include <pthread.h> |
---|
[7479042] | 308 | |
---|
[ae68ff0] | 309 | int pthread_attr_setstacksize( |
---|
[7479042] | 310 | pthread_attr_t *attr, |
---|
| 311 | size_t stacksize |
---|
[ae68ff0] | 312 | ); |
---|
| 313 | @end example |
---|
| 314 | |
---|
| 315 | @subheading STATUS CODES: |
---|
[7479042] | 316 | |
---|
[ae68ff0] | 317 | @table @b |
---|
| 318 | @item EINVAL |
---|
| 319 | The attribute pointer argument is invalid. |
---|
| 320 | |
---|
| 321 | @item EINVAL |
---|
| 322 | The attribute set is not initialized. |
---|
[7479042] | 323 | |
---|
[ae68ff0] | 324 | @end table |
---|
[7479042] | 325 | |
---|
[ae68ff0] | 326 | @subheading DESCRIPTION: |
---|
| 327 | |
---|
[d48ea69] | 328 | The @code{pthread_attr_setstacksize} routine is used to set the |
---|
| 329 | @code{stacksize} attribute in the @code{attr} thread attribute |
---|
| 330 | object. |
---|
| 331 | |
---|
[ae68ff0] | 332 | @subheading NOTES: |
---|
| 333 | |
---|
[d48ea69] | 334 | As required by POSIX, RTEMS defines the feature symbol |
---|
| 335 | @code{_POSIX_THREAD_ATTR_STACKSIZE} to indicate that this |
---|
| 336 | routine is supported. |
---|
| 337 | |
---|
| 338 | If the specified stacksize is below the minimum required for this CPU |
---|
| 339 | (@code{PTHREAD_STACK_MIN}, then the stacksize will be set to the minimum |
---|
| 340 | for this CPU. |
---|
[ae68ff0] | 341 | |
---|
[7479042] | 342 | @c |
---|
| 343 | @c |
---|
| 344 | @c |
---|
[ae68ff0] | 345 | @page |
---|
[d48ea69] | 346 | @subsection pthread_attr_getstacksize - Get Thread Stack Size |
---|
[ae68ff0] | 347 | |
---|
[7479042] | 348 | @findex pthread_attr_getstacksize |
---|
| 349 | @cindex get thread stack size |
---|
| 350 | |
---|
[ae68ff0] | 351 | @subheading CALLING SEQUENCE: |
---|
| 352 | |
---|
| 353 | @example |
---|
| 354 | #include <pthread.h> |
---|
| 355 | |
---|
| 356 | int pthread_attr_getstacksize( |
---|
[7479042] | 357 | const pthread_attr_t *attr, |
---|
| 358 | size_t *stacksize |
---|
[ae68ff0] | 359 | ); |
---|
| 360 | @end example |
---|
| 361 | |
---|
| 362 | @subheading STATUS CODES: |
---|
[7479042] | 363 | |
---|
[ae68ff0] | 364 | @table @b |
---|
| 365 | @item EINVAL |
---|
| 366 | The attribute pointer argument is invalid. |
---|
| 367 | |
---|
| 368 | @item EINVAL |
---|
| 369 | The attribute set is not initialized. |
---|
[7479042] | 370 | |
---|
[ae68ff0] | 371 | @item EINVAL |
---|
| 372 | The stacksize pointer argument is invalid. |
---|
| 373 | |
---|
| 374 | @end table |
---|
[7479042] | 375 | |
---|
[ae68ff0] | 376 | @subheading DESCRIPTION: |
---|
| 377 | |
---|
[d48ea69] | 378 | The @code{pthread_attr_getstacksize} routine is used to obtain the |
---|
| 379 | @code{stacksize} attribute in the @code{attr} thread attribute |
---|
| 380 | object. |
---|
| 381 | |
---|
[ae68ff0] | 382 | @subheading NOTES: |
---|
| 383 | |
---|
[d48ea69] | 384 | As required by POSIX, RTEMS defines the feature symbol |
---|
| 385 | @code{_POSIX_THREAD_ATTR_STACKSIZE} to indicate that this |
---|
| 386 | routine is supported. |
---|
| 387 | |
---|
[7479042] | 388 | @c |
---|
| 389 | @c |
---|
| 390 | @c |
---|
[ae68ff0] | 391 | @page |
---|
[d48ea69] | 392 | @subsection pthread_attr_setstackaddr - Set Thread Stack Address |
---|
[ae68ff0] | 393 | |
---|
[7479042] | 394 | @findex pthread_attr_setstackaddr |
---|
| 395 | @cindex set thread stack address |
---|
| 396 | |
---|
[ae68ff0] | 397 | @subheading CALLING SEQUENCE: |
---|
| 398 | |
---|
| 399 | @example |
---|
| 400 | #include <pthread.h> |
---|
[7479042] | 401 | |
---|
[ae68ff0] | 402 | int pthread_attr_setstackaddr( |
---|
[7479042] | 403 | pthread_attr_t *attr, |
---|
| 404 | void *stackaddr |
---|
[ae68ff0] | 405 | ); |
---|
| 406 | @end example |
---|
| 407 | |
---|
| 408 | @subheading STATUS CODES: |
---|
[7479042] | 409 | |
---|
[ae68ff0] | 410 | @table @b |
---|
| 411 | @item EINVAL |
---|
| 412 | The attribute pointer argument is invalid. |
---|
| 413 | |
---|
| 414 | @item EINVAL |
---|
| 415 | The attribute set is not initialized. |
---|
| 416 | |
---|
| 417 | @end table |
---|
[7479042] | 418 | |
---|
[ae68ff0] | 419 | @subheading DESCRIPTION: |
---|
| 420 | |
---|
[d48ea69] | 421 | The @code{pthread_attr_setstackaddr} routine is used to set the |
---|
| 422 | @code{stackaddr} attribute in the @code{attr} thread attribute |
---|
| 423 | object. |
---|
| 424 | |
---|
[ae68ff0] | 425 | @subheading NOTES: |
---|
| 426 | |
---|
[d48ea69] | 427 | As required by POSIX, RTEMS defines the feature symbol |
---|
| 428 | @code{_POSIX_THREAD_ATTR_STACKADDR} to indicate that this |
---|
| 429 | routine is supported. |
---|
| 430 | |
---|
[7479042] | 431 | It is imperative to the proper operation of the system that |
---|
[d48ea69] | 432 | each thread have sufficient stack space. |
---|
| 433 | |
---|
[7479042] | 434 | @c |
---|
| 435 | @c |
---|
| 436 | @c |
---|
[ae68ff0] | 437 | @page |
---|
[d48ea69] | 438 | @subsection pthread_attr_getstackaddr - Get Thread Stack Address |
---|
[ae68ff0] | 439 | |
---|
[7479042] | 440 | @findex pthread_attr_getstackaddr |
---|
| 441 | @cindex get thread stack address |
---|
| 442 | |
---|
[ae68ff0] | 443 | @subheading CALLING SEQUENCE: |
---|
| 444 | |
---|
| 445 | @example |
---|
| 446 | #include <pthread.h> |
---|
| 447 | |
---|
| 448 | int pthread_attr_getstackaddr( |
---|
[7479042] | 449 | const pthread_attr_t *attr, |
---|
| 450 | void **stackaddr |
---|
[ae68ff0] | 451 | ); |
---|
| 452 | @end example |
---|
| 453 | |
---|
| 454 | @subheading STATUS CODES: |
---|
[7479042] | 455 | |
---|
[ae68ff0] | 456 | @table @b |
---|
| 457 | @item EINVAL |
---|
| 458 | The attribute pointer argument is invalid. |
---|
| 459 | |
---|
| 460 | @item EINVAL |
---|
| 461 | The attribute set is not initialized. |
---|
[7479042] | 462 | |
---|
[ae68ff0] | 463 | @item EINVAL |
---|
| 464 | The stackaddr pointer argument is invalid. |
---|
| 465 | |
---|
| 466 | @end table |
---|
[7479042] | 467 | |
---|
[ae68ff0] | 468 | @subheading DESCRIPTION: |
---|
| 469 | |
---|
[d48ea69] | 470 | The @code{pthread_attr_getstackaddr} routine is used to obtain the |
---|
| 471 | @code{stackaddr} attribute in the @code{attr} thread attribute |
---|
| 472 | object. |
---|
| 473 | |
---|
[ae68ff0] | 474 | @subheading NOTES: |
---|
| 475 | |
---|
[d48ea69] | 476 | As required by POSIX, RTEMS defines the feature symbol |
---|
| 477 | @code{_POSIX_THREAD_ATTR_STACKADDR} to indicate that this |
---|
| 478 | routine is supported. |
---|
| 479 | |
---|
[7479042] | 480 | @c |
---|
| 481 | @c |
---|
| 482 | @c |
---|
[ae68ff0] | 483 | @page |
---|
[d48ea69] | 484 | @subsection pthread_attr_setscope - Set Thread Scheduling Scope |
---|
[ae68ff0] | 485 | |
---|
[7479042] | 486 | @findex pthread_attr_setscope |
---|
| 487 | @cindex set thread scheduling scope |
---|
| 488 | |
---|
[ae68ff0] | 489 | @subheading CALLING SEQUENCE: |
---|
| 490 | |
---|
| 491 | @example |
---|
| 492 | #include <pthread.h> |
---|
| 493 | |
---|
| 494 | int pthread_attr_setscope( |
---|
[7479042] | 495 | pthread_attr_t *attr, |
---|
| 496 | int contentionscope |
---|
[ae68ff0] | 497 | ); |
---|
| 498 | @end example |
---|
| 499 | |
---|
| 500 | @subheading STATUS CODES: |
---|
| 501 | |
---|
| 502 | @table @b |
---|
| 503 | @item EINVAL |
---|
| 504 | The attribute pointer argument is invalid. |
---|
| 505 | |
---|
| 506 | @item EINVAL |
---|
| 507 | The attribute set is not initialized. |
---|
| 508 | |
---|
| 509 | @item EINVAL |
---|
| 510 | The contention scope specified is not valid. |
---|
| 511 | |
---|
| 512 | @item ENOTSUP |
---|
| 513 | The contention scope specified (PTHREAD_SCOPE_SYSTEM) is not supported. |
---|
| 514 | |
---|
| 515 | @end table |
---|
| 516 | |
---|
| 517 | @subheading DESCRIPTION: |
---|
| 518 | |
---|
[d48ea69] | 519 | The @code{pthread_attr_setscope} routine is used to set the contention |
---|
| 520 | scope field in the thread attribute object @code{attr} to the value |
---|
| 521 | specified by @code{contentionscope}. |
---|
| 522 | |
---|
| 523 | The @code{contentionscope} must be either @code{PTHREAD_SCOPE_SYSTEM} |
---|
| 524 | to indicate that the thread is to be within system scheduling contention |
---|
| 525 | or @code{PTHREAD_SCOPE_PROCESS} indicating that the thread is to be |
---|
| 526 | within the process scheduling contention scope. |
---|
| 527 | |
---|
[ae68ff0] | 528 | @subheading NOTES: |
---|
| 529 | |
---|
[d48ea69] | 530 | As required by POSIX, RTEMS defines the feature symbol |
---|
| 531 | @code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the |
---|
| 532 | family of routines to which this routine belongs is supported. |
---|
| 533 | |
---|
[7479042] | 534 | @c |
---|
| 535 | @c |
---|
| 536 | @c |
---|
[ae68ff0] | 537 | @page |
---|
[d48ea69] | 538 | @subsection pthread_attr_getscope - Get Thread Scheduling Scope |
---|
[ae68ff0] | 539 | |
---|
[7479042] | 540 | @findex pthread_attr_getscope |
---|
| 541 | @cindex get thread scheduling scope |
---|
| 542 | |
---|
[ae68ff0] | 543 | @subheading CALLING SEQUENCE: |
---|
| 544 | |
---|
| 545 | @example |
---|
| 546 | #include <pthread.h> |
---|
| 547 | |
---|
| 548 | int pthread_attr_getscope( |
---|
[7479042] | 549 | const pthread_attr_t *attr, |
---|
| 550 | int *contentionscope |
---|
[ae68ff0] | 551 | ); |
---|
| 552 | @end example |
---|
| 553 | |
---|
| 554 | @subheading STATUS CODES: |
---|
| 555 | |
---|
| 556 | @table @b |
---|
| 557 | @item EINVAL |
---|
| 558 | The attribute pointer argument is invalid. |
---|
| 559 | |
---|
| 560 | @item EINVAL |
---|
| 561 | The attribute set is not initialized. |
---|
| 562 | |
---|
| 563 | @item EINVAL |
---|
| 564 | The contentionscope pointer argument is invalid. |
---|
| 565 | |
---|
| 566 | @end table |
---|
| 567 | |
---|
| 568 | @subheading DESCRIPTION: |
---|
| 569 | |
---|
[d48ea69] | 570 | The @code{pthread_attr_getscope} routine is used to obtain the |
---|
| 571 | value of the contention scope field in the thread attributes |
---|
[7479042] | 572 | object @code{attr}. The current value is returned in |
---|
[d48ea69] | 573 | @code{contentionscope}. |
---|
| 574 | |
---|
[ae68ff0] | 575 | @subheading NOTES: |
---|
| 576 | |
---|
[d48ea69] | 577 | As required by POSIX, RTEMS defines the feature symbol |
---|
| 578 | @code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the |
---|
| 579 | family of routines to which this routine belongs is supported. |
---|
[7479042] | 580 | @c |
---|
| 581 | @c |
---|
| 582 | @c |
---|
[ae68ff0] | 583 | @page |
---|
[d48ea69] | 584 | @subsection pthread_attr_setinheritsched - Set Inherit Scheduler Flag |
---|
[ae68ff0] | 585 | |
---|
[7479042] | 586 | @findex pthread_attr_setinheritsched |
---|
| 587 | @cindex set inherit scheduler flag |
---|
| 588 | |
---|
[ae68ff0] | 589 | @subheading CALLING SEQUENCE: |
---|
| 590 | |
---|
| 591 | @example |
---|
| 592 | #include <pthread.h> |
---|
| 593 | |
---|
| 594 | int pthread_attr_setinheritsched( |
---|
[7479042] | 595 | pthread_attr_t *attr, |
---|
| 596 | int inheritsched |
---|
[ae68ff0] | 597 | ); |
---|
| 598 | @end example |
---|
| 599 | |
---|
| 600 | @subheading STATUS CODES: |
---|
| 601 | |
---|
| 602 | @table @b |
---|
| 603 | @item EINVAL |
---|
| 604 | The attribute pointer argument is invalid. |
---|
| 605 | |
---|
| 606 | @item EINVAL |
---|
| 607 | The attribute set is not initialized. |
---|
| 608 | |
---|
| 609 | @item EINVAL |
---|
| 610 | The specified scheduler inheritance argument is invalid. |
---|
| 611 | |
---|
| 612 | @end table |
---|
| 613 | |
---|
| 614 | @subheading DESCRIPTION: |
---|
| 615 | |
---|
[d48ea69] | 616 | The @code{pthread_attr_setinheritsched} routine is used to set the |
---|
| 617 | inherit scheduler field in the thread attribute object @code{attr} to |
---|
[7479042] | 618 | the value specified by @code{inheritsched}. |
---|
[d48ea69] | 619 | |
---|
| 620 | The @code{contentionscope} must be either @code{PTHREAD_INHERIT_SCHED} |
---|
| 621 | to indicate that the thread is to inherit the scheduling policy |
---|
| 622 | and parameters fromthe creating thread, or @code{PTHREAD_EXPLICIT_SCHED} |
---|
| 623 | to indicate that the scheduling policy and parameters for this thread |
---|
| 624 | are to be set from the corresponding values in the attributes object. |
---|
| 625 | If @code{contentionscope} is @code{PTHREAD_INHERIT_SCHED}, then the |
---|
| 626 | scheduling attributes in the @code{attr} structure will be ignored |
---|
| 627 | at thread creation time. |
---|
| 628 | |
---|
[ae68ff0] | 629 | @subheading NOTES: |
---|
| 630 | |
---|
[d48ea69] | 631 | As required by POSIX, RTEMS defines the feature symbol |
---|
| 632 | @code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the |
---|
| 633 | family of routines to which this routine belongs is supported. |
---|
| 634 | |
---|
[7479042] | 635 | @c |
---|
| 636 | @c |
---|
| 637 | @c |
---|
[ae68ff0] | 638 | @page |
---|
[d48ea69] | 639 | @subsection pthread_attr_getinheritsched - Get Inherit Scheduler Flag |
---|
[ae68ff0] | 640 | |
---|
[7479042] | 641 | @findex pthread_attr_getinheritsched |
---|
| 642 | @cindex get inherit scheduler flag |
---|
| 643 | |
---|
[ae68ff0] | 644 | @subheading CALLING SEQUENCE: |
---|
| 645 | |
---|
| 646 | @example |
---|
| 647 | #include <pthread.h> |
---|
| 648 | |
---|
| 649 | int pthread_attr_getinheritsched( |
---|
[7479042] | 650 | const pthread_attr_t *attr, |
---|
| 651 | int *inheritsched |
---|
[ae68ff0] | 652 | ); |
---|
| 653 | @end example |
---|
| 654 | |
---|
| 655 | @subheading STATUS CODES: |
---|
| 656 | @table @b |
---|
| 657 | @item EINVAL |
---|
| 658 | The attribute pointer argument is invalid. |
---|
| 659 | |
---|
| 660 | @item EINVAL |
---|
| 661 | The attribute set is not initialized. |
---|
| 662 | |
---|
| 663 | @item EINVAL |
---|
| 664 | The inheritsched pointer argument is invalid. |
---|
| 665 | |
---|
| 666 | @end table |
---|
| 667 | |
---|
| 668 | @subheading DESCRIPTION: |
---|
| 669 | |
---|
[d48ea69] | 670 | The @code{pthread_attr_getinheritsched} routine is used to |
---|
| 671 | object the current value of the inherit scheduler field in |
---|
| 672 | the thread attribute object @code{attr}. |
---|
| 673 | |
---|
[ae68ff0] | 674 | @subheading NOTES: |
---|
| 675 | |
---|
[d48ea69] | 676 | As required by POSIX, RTEMS defines the feature symbol |
---|
| 677 | @code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the |
---|
| 678 | family of routines to which this routine belongs is supported. |
---|
| 679 | |
---|
[7479042] | 680 | @c |
---|
| 681 | @c |
---|
| 682 | @c |
---|
[ae68ff0] | 683 | @page |
---|
[d48ea69] | 684 | @subsection pthread_attr_setschedpolicy - Set Scheduling Policy |
---|
[ae68ff0] | 685 | |
---|
[7479042] | 686 | @findex pthread_attr_setschedpolicy |
---|
| 687 | @cindex set scheduling policy |
---|
| 688 | |
---|
[ae68ff0] | 689 | @subheading CALLING SEQUENCE: |
---|
| 690 | |
---|
| 691 | @example |
---|
| 692 | #include <pthread.h> |
---|
| 693 | |
---|
| 694 | int pthread_attr_setschedpolicy( |
---|
[7479042] | 695 | pthread_attr_t *attr, |
---|
| 696 | int policy |
---|
[ae68ff0] | 697 | ); |
---|
| 698 | @end example |
---|
| 699 | |
---|
| 700 | @subheading STATUS CODES: |
---|
| 701 | @table @b |
---|
| 702 | @item EINVAL |
---|
| 703 | The attribute pointer argument is invalid. |
---|
| 704 | |
---|
| 705 | @item EINVAL |
---|
| 706 | The attribute set is not initialized. |
---|
[7479042] | 707 | |
---|
[ae68ff0] | 708 | @item ENOTSUP |
---|
| 709 | The specified scheduler policy argument is invalid. |
---|
| 710 | |
---|
| 711 | @end table |
---|
| 712 | |
---|
| 713 | @subheading DESCRIPTION: |
---|
| 714 | |
---|
[d48ea69] | 715 | The @code{pthread_attr_setschedpolicy} routine is used to set the |
---|
| 716 | scheduler policy field in the thread attribute object @code{attr} to |
---|
| 717 | the value specified by @code{policy}. |
---|
| 718 | |
---|
| 719 | Scheduling policies may be one of the following: |
---|
| 720 | |
---|
| 721 | @itemize @bullet |
---|
| 722 | |
---|
| 723 | @item @code{SCHED_DEFAULT} |
---|
| 724 | @item @code{SCHED_FIFO} |
---|
| 725 | @item @code{SCHED_RR} |
---|
| 726 | @item @code{SCHED_SPORADIC} |
---|
| 727 | @item @code{SCHED_OTHER} |
---|
| 728 | |
---|
| 729 | @end itemize |
---|
| 730 | |
---|
| 731 | The precise meaning of each of these is discussed elsewhere in this |
---|
| 732 | manual. |
---|
| 733 | |
---|
[ae68ff0] | 734 | @subheading NOTES: |
---|
| 735 | |
---|
[d48ea69] | 736 | As required by POSIX, RTEMS defines the feature symbol |
---|
| 737 | @code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the |
---|
| 738 | family of routines to which this routine belongs is supported. |
---|
| 739 | |
---|
[7479042] | 740 | @c |
---|
| 741 | @c |
---|
| 742 | @c |
---|
[ae68ff0] | 743 | @page |
---|
[d48ea69] | 744 | @subsection pthread_attr_getschedpolicy - Get Scheduling Policy |
---|
[ae68ff0] | 745 | |
---|
[7479042] | 746 | @findex pthread_attr_getschedpolicy |
---|
| 747 | @cindex get scheduling policy |
---|
| 748 | |
---|
[ae68ff0] | 749 | @subheading CALLING SEQUENCE: |
---|
| 750 | |
---|
| 751 | @example |
---|
| 752 | #include <pthread.h> |
---|
| 753 | |
---|
| 754 | int pthread_attr_getschedpolicy( |
---|
[7479042] | 755 | const pthread_attr_t *attr, |
---|
| 756 | int *policy |
---|
[ae68ff0] | 757 | ); |
---|
| 758 | @end example |
---|
| 759 | |
---|
| 760 | @subheading STATUS CODES: |
---|
| 761 | @table @b |
---|
| 762 | @item EINVAL |
---|
| 763 | The attribute pointer argument is invalid. |
---|
| 764 | |
---|
| 765 | @item EINVAL |
---|
| 766 | The attribute set is not initialized. |
---|
| 767 | |
---|
| 768 | @item EINVAL |
---|
| 769 | The specified scheduler policy argument pointer is invalid. |
---|
| 770 | |
---|
| 771 | @end table |
---|
| 772 | |
---|
| 773 | @subheading DESCRIPTION: |
---|
| 774 | |
---|
[d48ea69] | 775 | The @code{pthread_attr_getschedpolicy} routine is used to obtain the |
---|
| 776 | scheduler policy field from the thread attribute object @code{attr}. |
---|
| 777 | The value of this field is returned in @code{policy}. |
---|
| 778 | |
---|
[ae68ff0] | 779 | @subheading NOTES: |
---|
| 780 | |
---|
[d48ea69] | 781 | As required by POSIX, RTEMS defines the feature symbol |
---|
| 782 | @code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the |
---|
| 783 | family of routines to which this routine belongs is supported. |
---|
| 784 | |
---|
[7479042] | 785 | @c |
---|
| 786 | @c |
---|
| 787 | @c |
---|
[ae68ff0] | 788 | @page |
---|
[d48ea69] | 789 | @subsection pthread_attr_setschedparam - Set Scheduling Parameters |
---|
[ae68ff0] | 790 | |
---|
[7479042] | 791 | @findex pthread_attr_setschedparam |
---|
| 792 | @cindex set scheduling parameters |
---|
| 793 | |
---|
[ae68ff0] | 794 | @subheading CALLING SEQUENCE: |
---|
| 795 | |
---|
| 796 | @example |
---|
| 797 | #include <pthread.h> |
---|
| 798 | |
---|
| 799 | int pthread_attr_setschedparam( |
---|
[7479042] | 800 | pthread_attr_t *attr, |
---|
| 801 | const struct sched_param param |
---|
[ae68ff0] | 802 | ); |
---|
| 803 | @end example |
---|
| 804 | |
---|
| 805 | @subheading STATUS CODES: |
---|
| 806 | @table @b |
---|
| 807 | @item EINVAL |
---|
| 808 | The attribute pointer argument is invalid. |
---|
| 809 | |
---|
| 810 | @item EINVAL |
---|
| 811 | The attribute set is not initialized. |
---|
[7479042] | 812 | |
---|
[ae68ff0] | 813 | @item EINVAL |
---|
| 814 | The specified scheduler parameter argument is invalid. |
---|
| 815 | |
---|
| 816 | @end table |
---|
| 817 | |
---|
| 818 | @subheading DESCRIPTION: |
---|
| 819 | |
---|
[d48ea69] | 820 | The @code{pthread_attr_setschedparam} routine is used to set the |
---|
| 821 | scheduler parameters field in the thread attribute object @code{attr} to |
---|
| 822 | the value specified by @code{param}. |
---|
| 823 | |
---|
[ae68ff0] | 824 | @subheading NOTES: |
---|
| 825 | |
---|
[d48ea69] | 826 | As required by POSIX, RTEMS defines the feature symbol |
---|
| 827 | @code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the |
---|
| 828 | family of routines to which this routine belongs is supported. |
---|
| 829 | |
---|
[7479042] | 830 | @c |
---|
| 831 | @c |
---|
| 832 | @c |
---|
[ae68ff0] | 833 | @page |
---|
[d48ea69] | 834 | @subsection pthread_attr_getschedparam - Get Scheduling Parameters |
---|
[ae68ff0] | 835 | |
---|
[7479042] | 836 | @findex pthread_attr_getschedparam |
---|
| 837 | @cindex get scheduling parameters |
---|
| 838 | |
---|
[ae68ff0] | 839 | @subheading CALLING SEQUENCE: |
---|
| 840 | |
---|
| 841 | @example |
---|
| 842 | #include <pthread.h> |
---|
| 843 | |
---|
| 844 | int pthread_attr_getschedparam( |
---|
[7479042] | 845 | const pthread_attr_t *attr, |
---|
| 846 | struct sched_param *param |
---|
[ae68ff0] | 847 | ); |
---|
| 848 | @end example |
---|
| 849 | |
---|
| 850 | @subheading STATUS CODES: |
---|
| 851 | @table @b |
---|
| 852 | @item EINVAL |
---|
| 853 | The attribute pointer argument is invalid. |
---|
| 854 | |
---|
| 855 | @item EINVAL |
---|
| 856 | The attribute set is not initialized. |
---|
| 857 | |
---|
| 858 | @item EINVAL |
---|
| 859 | The specified scheduler parameter argument pointer is invalid. |
---|
| 860 | |
---|
| 861 | @end table |
---|
| 862 | |
---|
| 863 | @subheading DESCRIPTION: |
---|
| 864 | |
---|
[d48ea69] | 865 | The @code{pthread_attr_getschedparam} routine is used to obtain the |
---|
| 866 | scheduler parameters field from the thread attribute object @code{attr}. |
---|
| 867 | The value of this field is returned in @code{param}. |
---|
| 868 | |
---|
[ae68ff0] | 869 | @subheading NOTES: |
---|
| 870 | |
---|
[d48ea69] | 871 | As required by POSIX, RTEMS defines the feature symbol |
---|
| 872 | @code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the |
---|
| 873 | family of routines to which this routine belongs is supported. |
---|
| 874 | |
---|
[7479042] | 875 | @c |
---|
| 876 | @c |
---|
| 877 | @c |
---|
[ae68ff0] | 878 | @page |
---|
[d48ea69] | 879 | @subsection pthread_create - Create a Thread |
---|
[ae68ff0] | 880 | |
---|
[7479042] | 881 | @findex pthread_create |
---|
| 882 | @cindex create a thread |
---|
| 883 | |
---|
[ae68ff0] | 884 | @subheading CALLING SEQUENCE: |
---|
| 885 | |
---|
| 886 | @example |
---|
| 887 | #include <pthread.h> |
---|
| 888 | |
---|
| 889 | int pthread_create( |
---|
[ee0702ef] | 890 | pthread_t *thread, |
---|
| 891 | const pthread_attr_t *attr, |
---|
| 892 | void (*start_routine)( void *), |
---|
| 893 | void *arg |
---|
[ae68ff0] | 894 | ); |
---|
| 895 | @end example |
---|
| 896 | |
---|
| 897 | @subheading STATUS CODES: |
---|
| 898 | |
---|
| 899 | @table @b |
---|
| 900 | |
---|
| 901 | @item EINVAL |
---|
| 902 | The attribute set is not initialized. |
---|
| 903 | |
---|
| 904 | @item EINVAL |
---|
[7479042] | 905 | The user specified a stack address and the size of the area was not |
---|
[ae68ff0] | 906 | large enough to meet this processor's minimum stack requirements. |
---|
| 907 | |
---|
| 908 | @item EINVAL |
---|
| 909 | The specified scheduler inheritance policy was invalid. |
---|
| 910 | |
---|
| 911 | @item ENOTSUP |
---|
| 912 | The specified contention scope was PTHREAD_SCOPE_PROCESS. |
---|
| 913 | |
---|
| 914 | @item EINVAL |
---|
| 915 | The specified thread priority was invalid. |
---|
| 916 | |
---|
| 917 | @item EINVAL |
---|
| 918 | The specified scheduling policy was invalid. |
---|
| 919 | |
---|
| 920 | @item EINVAL |
---|
| 921 | The scheduling policy was SCHED_SPORADIC and the specified replenishment |
---|
| 922 | period is less than the initial budget. |
---|
| 923 | |
---|
| 924 | @item EINVAL |
---|
| 925 | The scheduling policy was SCHED_SPORADIC and the specified low priority |
---|
| 926 | is invalid. |
---|
| 927 | |
---|
| 928 | @item EAGAIN |
---|
| 929 | The system lacked the necessary resources to create another thread, or the |
---|
| 930 | self imposed limit on the total number of threads in a process |
---|
| 931 | PTHREAD_THREAD_MAX would be exceeded. |
---|
[7479042] | 932 | |
---|
[ae68ff0] | 933 | @item EINVAL |
---|
| 934 | Invalid argument passed. |
---|
| 935 | |
---|
| 936 | @end table |
---|
[7479042] | 937 | |
---|
[ae68ff0] | 938 | @subheading DESCRIPTION: |
---|
| 939 | |
---|
[7479042] | 940 | The @code{pthread_create} routine is used to create a new thread with |
---|
| 941 | the attributes specified by @code{attr}. If the @code{attr} argument |
---|
| 942 | is @code{NULL}, then the default attribute set will be used. Modification |
---|
[d48ea69] | 943 | of the contents of @code{attr} after this thread is created does not |
---|
[7479042] | 944 | have an impact on this thread. |
---|
[d48ea69] | 945 | |
---|
| 946 | The thread begins execution at the address specified by @code{start_routine} |
---|
[7479042] | 947 | with @code{arg} as its only argument. If @code{start_routine} returns, |
---|
[d48ea69] | 948 | then it is functionally equivalent to the thread executing the |
---|
| 949 | @code{pthread_exit} service. |
---|
| 950 | |
---|
| 951 | Upon successful completion, the ID of the created thread is returned in the |
---|
| 952 | @code{thread} argument. |
---|
| 953 | |
---|
[ae68ff0] | 954 | @subheading NOTES: |
---|
| 955 | |
---|
[7479042] | 956 | There is no concept of a single main thread in RTEMS as there is in |
---|
| 957 | a tradition UNIX system. POSIX requires that the implicit return of |
---|
[d48ea69] | 958 | the main thread results in the same effects as if there were a call |
---|
[7479042] | 959 | to @code{exit}. This does not occur in RTEMS. |
---|
[d48ea69] | 960 | |
---|
| 961 | The signal mask of the newly created thread is inherited from its |
---|
| 962 | creator and the set of pending signals for this thread is empty. |
---|
| 963 | |
---|
[7479042] | 964 | @c |
---|
| 965 | @c |
---|
| 966 | @c |
---|
[ae68ff0] | 967 | @page |
---|
[d48ea69] | 968 | @subsection pthread_exit - Terminate the Current Thread |
---|
[ae68ff0] | 969 | |
---|
[7479042] | 970 | @findex pthread_exit |
---|
| 971 | @cindex terminate the current thread |
---|
| 972 | |
---|
[ae68ff0] | 973 | @subheading CALLING SEQUENCE: |
---|
| 974 | |
---|
| 975 | @example |
---|
| 976 | #include <pthread.h> |
---|
| 977 | |
---|
| 978 | void pthread_exit( |
---|
[7479042] | 979 | void *status |
---|
[ae68ff0] | 980 | ); |
---|
| 981 | @end example |
---|
| 982 | |
---|
| 983 | @subheading STATUS CODES: |
---|
| 984 | @table @b |
---|
| 985 | @item NONE |
---|
[7479042] | 986 | |
---|
[ae68ff0] | 987 | @end table |
---|
| 988 | |
---|
| 989 | @subheading DESCRIPTION: |
---|
| 990 | |
---|
[d48ea69] | 991 | The @code{pthread_exit} routine is used to temrinate the calling thread. |
---|
| 992 | The @code{status} is made available to any successful join with the |
---|
| 993 | terminating thread. |
---|
| 994 | |
---|
[7479042] | 995 | When a thread returns from its start routine, it results in an |
---|
[d48ea69] | 996 | implicit call to the @code{pthread_exit} routine with the return |
---|
| 997 | value of the function serving as the argument to @code{pthread_exit}. |
---|
| 998 | |
---|
[ae68ff0] | 999 | @subheading NOTES: |
---|
| 1000 | |
---|
[7479042] | 1001 | Any cancellation cleanup handlers that hace been pushed and not yet popped |
---|
| 1002 | shall be popped in reverse of the order that they were pushed. After |
---|
[d48ea69] | 1003 | all cancellation cleanup handlers have been executed, if the |
---|
| 1004 | thread has any thread-specific data, destructors for that data will |
---|
| 1005 | be invoked. |
---|
| 1006 | |
---|
| 1007 | Thread termination does not release or free any application visible |
---|
| 1008 | resources including byt not limited to mutexes, file descriptors, allocated |
---|
[7479042] | 1009 | memory, etc.. Similarly, exitting a thread does not result in any |
---|
[d48ea69] | 1010 | process-oriented cleanup activity. |
---|
| 1011 | |
---|
[7479042] | 1012 | There is no concept of a single main thread in RTEMS as there is in |
---|
| 1013 | a tradition UNIX system. POSIX requires that the implicit return of |
---|
[d48ea69] | 1014 | the main thread results in the same effects as if there were a call |
---|
[7479042] | 1015 | to @code{exit}. This does not occur in RTEMS. |
---|
[d48ea69] | 1016 | |
---|
| 1017 | All access to any automatic variables allocated by the threads is lost |
---|
[7479042] | 1018 | when the thread exits. Thus references (i.e. pointers) to local variables |
---|
| 1019 | of a thread should not be used in a global manner without care. As |
---|
[d48ea69] | 1020 | a specific example, a pointer to a local variable should NOT be used |
---|
| 1021 | as the return value. |
---|
| 1022 | |
---|
| 1023 | |
---|
[7479042] | 1024 | @c |
---|
| 1025 | @c |
---|
| 1026 | @c |
---|
[ae68ff0] | 1027 | @page |
---|
[d48ea69] | 1028 | @subsection pthread_detach - Detach a Thread |
---|
[ae68ff0] | 1029 | |
---|
[7479042] | 1030 | @findex pthread_detach |
---|
| 1031 | @cindex detach a thread |
---|
| 1032 | |
---|
[ae68ff0] | 1033 | @subheading CALLING SEQUENCE: |
---|
| 1034 | |
---|
| 1035 | @example |
---|
| 1036 | #include <pthread.h> |
---|
| 1037 | |
---|
| 1038 | int pthread_detach( |
---|
[7479042] | 1039 | pthread_t thread |
---|
[ae68ff0] | 1040 | ); |
---|
| 1041 | @end example |
---|
| 1042 | |
---|
| 1043 | @subheading STATUS CODES: |
---|
| 1044 | @table @b |
---|
| 1045 | @item ESRCH |
---|
| 1046 | The thread specified is invalid. |
---|
[7479042] | 1047 | |
---|
[ae68ff0] | 1048 | @item EINVAL |
---|
| 1049 | The thread specified is not a joinable thread. |
---|
[7479042] | 1050 | |
---|
[ae68ff0] | 1051 | @end table |
---|
| 1052 | |
---|
| 1053 | @subheading DESCRIPTION: |
---|
| 1054 | |
---|
[d48ea69] | 1055 | The @code{pthread_detach} routine is used to to indicate that storage |
---|
| 1056 | for @code{thread} can be reclaimed when the thread terminates without |
---|
| 1057 | another thread joinging with it. |
---|
| 1058 | |
---|
[ae68ff0] | 1059 | @subheading NOTES: |
---|
| 1060 | |
---|
| 1061 | If any threads have previously joined with the specified thread, then they |
---|
[7479042] | 1062 | will remain joined with that thread. Any subsequent calls to |
---|
[d48ea69] | 1063 | @code{pthread_join} on the specified thread will fail. |
---|
[ae68ff0] | 1064 | |
---|
[7479042] | 1065 | @c |
---|
| 1066 | @c |
---|
| 1067 | @c |
---|
[ae68ff0] | 1068 | @page |
---|
[d48ea69] | 1069 | @subsection pthread_join - Wait for Thread Termination |
---|
[ae68ff0] | 1070 | |
---|
[7479042] | 1071 | @findex pthread_join |
---|
| 1072 | @cindex wait for thread termination |
---|
| 1073 | |
---|
[ae68ff0] | 1074 | @subheading CALLING SEQUENCE: |
---|
| 1075 | |
---|
| 1076 | @example |
---|
| 1077 | #include <pthread.h> |
---|
| 1078 | |
---|
| 1079 | int pthread_join( |
---|
[7479042] | 1080 | pthread_t thread, |
---|
| 1081 | void **value_ptr |
---|
[ae68ff0] | 1082 | ); |
---|
| 1083 | @end example |
---|
| 1084 | |
---|
| 1085 | @subheading STATUS CODES: |
---|
| 1086 | @table @b |
---|
| 1087 | @item ESRCH |
---|
| 1088 | The thread specified is invalid. |
---|
[7479042] | 1089 | |
---|
[ae68ff0] | 1090 | @item EINVAL |
---|
| 1091 | The thread specified is not a joinable thread. |
---|
[7479042] | 1092 | |
---|
[ae68ff0] | 1093 | @item EDEADLK |
---|
| 1094 | A deadlock was detected or thread is the calling thread. |
---|
[7479042] | 1095 | |
---|
[ae68ff0] | 1096 | @end table |
---|
| 1097 | |
---|
| 1098 | @subheading DESCRIPTION: |
---|
| 1099 | |
---|
[d48ea69] | 1100 | The @code{pthread_join} routine suspends execution of the calling thread |
---|
[7479042] | 1101 | until @code{thread} terminates. If @code{thread} has already terminated, |
---|
| 1102 | then this routine returns immediately. The value returned by @code{thread} |
---|
[d48ea69] | 1103 | (i.e. passed to @code{pthread_exit} is returned in @code{value_ptr}. |
---|
| 1104 | |
---|
[7479042] | 1105 | When this routine returns, then @code{thread} has been temrinated. |
---|
[d48ea69] | 1106 | |
---|
[ae68ff0] | 1107 | @subheading NOTES: |
---|
| 1108 | |
---|
[d48ea69] | 1109 | The results of multiple simultaneous joins on the same thread is undefined. |
---|
| 1110 | |
---|
[ae68ff0] | 1111 | If any threads have previously joined with the specified thread, then they |
---|
[7479042] | 1112 | will remain joined with that thread. Any subsequent calls to |
---|
[d48ea69] | 1113 | @code{pthread_join} on the specified thread will fail. |
---|
[ae68ff0] | 1114 | |
---|
| 1115 | If value_ptr is NULL, then no value is returned. |
---|
| 1116 | |
---|
[7479042] | 1117 | @c |
---|
| 1118 | @c |
---|
| 1119 | @c |
---|
[ae68ff0] | 1120 | @page |
---|
[d48ea69] | 1121 | @subsection pthread_self - Get Thread ID |
---|
[ae68ff0] | 1122 | |
---|
[7479042] | 1123 | @findex pthread_self |
---|
| 1124 | @cindex get thread id |
---|
| 1125 | |
---|
[ae68ff0] | 1126 | @subheading CALLING SEQUENCE: |
---|
| 1127 | |
---|
| 1128 | @example |
---|
| 1129 | #include <pthread.h> |
---|
| 1130 | |
---|
| 1131 | pthread_t pthread_self( void ); |
---|
| 1132 | @end example |
---|
| 1133 | |
---|
| 1134 | @subheading STATUS CODES: |
---|
| 1135 | |
---|
[d48ea69] | 1136 | The value returned is the ID of the calling thread. |
---|
[ae68ff0] | 1137 | |
---|
| 1138 | @subheading DESCRIPTION: |
---|
| 1139 | |
---|
[d48ea69] | 1140 | This routine returns the ID of the calling thread. |
---|
| 1141 | |
---|
[ae68ff0] | 1142 | @subheading NOTES: |
---|
| 1143 | |
---|
[d48ea69] | 1144 | NONE |
---|
| 1145 | |
---|
[7479042] | 1146 | @c |
---|
| 1147 | @c |
---|
| 1148 | @c |
---|
[ae68ff0] | 1149 | @page |
---|
[d48ea69] | 1150 | @subsection pthread_equal - Compare Thread IDs |
---|
[ae68ff0] | 1151 | |
---|
[7479042] | 1152 | @findex pthread_equal |
---|
| 1153 | @cindex compare thread ids |
---|
| 1154 | |
---|
[ae68ff0] | 1155 | @subheading CALLING SEQUENCE: |
---|
| 1156 | |
---|
| 1157 | @example |
---|
| 1158 | #include <pthread.h> |
---|
| 1159 | |
---|
| 1160 | int pthread_equal( |
---|
[7479042] | 1161 | pthread_t t1, |
---|
| 1162 | pthread_t t2 |
---|
[ae68ff0] | 1163 | ); |
---|
| 1164 | @end example |
---|
| 1165 | |
---|
| 1166 | @subheading STATUS CODES: |
---|
| 1167 | |
---|
| 1168 | @table @b |
---|
| 1169 | @item zero |
---|
| 1170 | The thread ids are not equal. |
---|
[7479042] | 1171 | |
---|
[ae68ff0] | 1172 | @item non-zero |
---|
| 1173 | The thread ids are equal. |
---|
[7479042] | 1174 | |
---|
[ae68ff0] | 1175 | @end table |
---|
| 1176 | |
---|
| 1177 | @subheading DESCRIPTION: |
---|
| 1178 | |
---|
[d48ea69] | 1179 | The @code{pthread_equal} routine is used to compare two thread |
---|
| 1180 | IDs and determine if they are equal. |
---|
| 1181 | |
---|
[ae68ff0] | 1182 | @subheading NOTES: |
---|
| 1183 | |
---|
| 1184 | The behavior is undefined if the thread IDs are not valid. |
---|
| 1185 | |
---|
[7479042] | 1186 | @c |
---|
| 1187 | @c |
---|
| 1188 | @c |
---|
[ae68ff0] | 1189 | @page |
---|
[d48ea69] | 1190 | @subsection pthread_once - Dynamic Package Initialization |
---|
[ae68ff0] | 1191 | |
---|
[7479042] | 1192 | @findex pthread_once |
---|
| 1193 | @cindex dynamic package initialization |
---|
| 1194 | |
---|
[ae68ff0] | 1195 | @subheading CALLING SEQUENCE: |
---|
| 1196 | |
---|
| 1197 | @example |
---|
| 1198 | #include <pthread.h> |
---|
| 1199 | |
---|
| 1200 | pthread_once_t once_control = PTHREAD_ONCE_INIT; |
---|
| 1201 | |
---|
| 1202 | int pthread_once( |
---|
[7479042] | 1203 | pthread_once_t *once_control, |
---|
| 1204 | void (*init_routine)(void) |
---|
[ae68ff0] | 1205 | ); |
---|
| 1206 | @end example |
---|
| 1207 | |
---|
| 1208 | @subheading STATUS CODES: |
---|
| 1209 | |
---|
| 1210 | NONE |
---|
| 1211 | |
---|
| 1212 | @subheading DESCRIPTION: |
---|
| 1213 | |
---|
[d48ea69] | 1214 | The @code{pthread_once} routine is used to provide controlled initialization |
---|
[7479042] | 1215 | of variables. The first call to @code{pthread_once} by any thread with the |
---|
[d48ea69] | 1216 | same @code{once_control} will result in the @code{init_routine} being |
---|
[7479042] | 1217 | invoked with no arguments. Subsequent calls to @code{pthread_once} with |
---|
| 1218 | the same @code{once_control} will have no effect. |
---|
[d48ea69] | 1219 | |
---|
| 1220 | The @code{init_routine} is guaranteed to have run to completion when |
---|
| 1221 | this routine returns to the caller. |
---|
| 1222 | |
---|
[ae68ff0] | 1223 | @subheading NOTES: |
---|
| 1224 | |
---|
[d48ea69] | 1225 | The behavior of @code{pthread_once} is undefined if @code{once_control} |
---|
| 1226 | is automatic storage (i.e. on a task stack) or is not initialized using |
---|
| 1227 | @code{PTHREAD_ONCE_INIT}. |
---|
| 1228 | |
---|
[7479042] | 1229 | @c |
---|
| 1230 | @c |
---|
| 1231 | @c |
---|
[ae68ff0] | 1232 | @page |
---|
[d48ea69] | 1233 | @subsection pthread_setschedparam - Set Thread Scheduling Parameters |
---|
[ae68ff0] | 1234 | |
---|
[7479042] | 1235 | @findex pthread_setschedparam |
---|
| 1236 | @cindex set thread scheduling parameters |
---|
| 1237 | |
---|
[ae68ff0] | 1238 | @subheading CALLING SEQUENCE: |
---|
| 1239 | |
---|
| 1240 | @example |
---|
| 1241 | #include <pthread.h> |
---|
| 1242 | |
---|
| 1243 | int pthread_setschedparam( |
---|
[7479042] | 1244 | pthread_t thread, |
---|
| 1245 | int policy, |
---|
| 1246 | struct sched_param *param |
---|
[ae68ff0] | 1247 | ); |
---|
| 1248 | @end example |
---|
| 1249 | |
---|
| 1250 | @subheading STATUS CODES: |
---|
| 1251 | |
---|
| 1252 | @table @b |
---|
| 1253 | @item EINVAL |
---|
| 1254 | The scheduling parameters indicated by the parameter param is invalid. |
---|
| 1255 | |
---|
| 1256 | @item EINVAL |
---|
| 1257 | The value specified by policy is invalid. |
---|
| 1258 | |
---|
| 1259 | @item EINVAL |
---|
| 1260 | The scheduling policy was SCHED_SPORADIC and the specified replenishment |
---|
| 1261 | period is less than the initial budget. |
---|
| 1262 | |
---|
| 1263 | @item EINVAL |
---|
| 1264 | The scheduling policy was SCHED_SPORADIC and the specified low priority |
---|
| 1265 | is invalid. |
---|
| 1266 | |
---|
| 1267 | @item ESRCH |
---|
| 1268 | The thread indicated was invalid. |
---|
| 1269 | |
---|
| 1270 | @end table |
---|
| 1271 | |
---|
| 1272 | @subheading DESCRIPTION: |
---|
| 1273 | |
---|
[d48ea69] | 1274 | The @code{pthread_setschedparam} routine is used to set the |
---|
| 1275 | scheduler parameters currently associated with the thread specified |
---|
[7479042] | 1276 | by @code{thread} to the policy specified by @code{policy}. The |
---|
[d48ea69] | 1277 | contents of @code{param} are interpreted based upon the @code{policy} |
---|
| 1278 | argument. |
---|
| 1279 | |
---|
[ae68ff0] | 1280 | @subheading NOTES: |
---|
| 1281 | |
---|
[d48ea69] | 1282 | As required by POSIX, RTEMS defines the feature symbol |
---|
| 1283 | @code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the |
---|
| 1284 | family of routines to which this routine belongs is supported. |
---|
| 1285 | |
---|
[7479042] | 1286 | @c |
---|
| 1287 | @c |
---|
| 1288 | @c |
---|
[ae68ff0] | 1289 | @page |
---|
[d48ea69] | 1290 | @subsection pthread_getschedparam - Get Thread Scheduling Parameters |
---|
[ae68ff0] | 1291 | |
---|
[7479042] | 1292 | @findex pthread_getschedparam |
---|
| 1293 | @cindex get thread scheduling parameters |
---|
| 1294 | |
---|
[ae68ff0] | 1295 | @subheading CALLING SEQUENCE: |
---|
| 1296 | |
---|
| 1297 | @example |
---|
| 1298 | #include <pthread.h> |
---|
| 1299 | |
---|
| 1300 | int pthread_getschedparam( |
---|
[7479042] | 1301 | pthread_t thread, |
---|
| 1302 | int *policy, |
---|
| 1303 | struct sched_param *param |
---|
[ae68ff0] | 1304 | ); |
---|
| 1305 | @end example |
---|
| 1306 | |
---|
| 1307 | @subheading STATUS CODES: |
---|
[7479042] | 1308 | |
---|
[ae68ff0] | 1309 | @table @b |
---|
| 1310 | @item EINVAL |
---|
| 1311 | The policy pointer argument is invalid. |
---|
| 1312 | |
---|
| 1313 | @item EINVAL |
---|
| 1314 | The scheduling parameters pointer argument is invalid. |
---|
| 1315 | |
---|
| 1316 | @item ESRCH |
---|
| 1317 | The thread indicated by the parameter thread is invalid. |
---|
[7479042] | 1318 | |
---|
[ae68ff0] | 1319 | @end table |
---|
| 1320 | |
---|
| 1321 | @subheading DESCRIPTION: |
---|
| 1322 | |
---|
[d48ea69] | 1323 | The @code{pthread_getschedparam} routine is used to obtain the |
---|
| 1324 | scheduler policy and parameters associated with @code{thread}. |
---|
| 1325 | The current policy and associated parameters values returned in |
---|
| 1326 | @code{policy} and @code{param}, respectively. |
---|
| 1327 | |
---|
[ae68ff0] | 1328 | @subheading NOTES: |
---|
| 1329 | |
---|
[d48ea69] | 1330 | As required by POSIX, RTEMS defines the feature symbol |
---|
| 1331 | @code{_POSIX_THREAD_PRIORITY_SCHEDULING} to indicate that the |
---|
| 1332 | family of routines to which this routine belongs is supported. |
---|