1.\" $OpenBSD: pthreads.3,v 1.15 2001/11/02 22:50:12 marc Exp $ 2.\" David Leonard <d@openbsd.org>, 1998. Public domain. 3.Dd August 17, 1998 4.Dt PTHREADS 3 5.Os 6.Sh NAME 7.Nm pthreads 8.Nd POSIX 1003.1c thread interface 9.Sh DESCRIPTION 10A thread is a flow of control within a process. 11Each thread represents a minimal amount of state; 12normally just the cpu state and a signal mask. 13All other process state (such as memory, file descriptors) 14is shared among all of the threads in the process. 15.Pp 16In 17.Ox , 18threads are implemented in a user-level library. 19A program using these routines must be linked with the 20.Fl pthread 21option. 22.Pp 23The 24.Dv SIGINFO 25signal can be sent to a threaded process to have the library show the state of 26all of its threads. The information is sent to the process' 27controlling tty and describes each thread's 28ID, 29state (see 30.Sx Thread states ) , 31current priority, 32flags (see 33.Sx Thread flags ) , 34signal mask, and name (as set by 35.Xr pthread_set_name_np 3 ) . 36If the environment variable 37.Ev PTHREAD_DEBUG 38is defined additional information is displayed. 39.Pp 40.Ss Thread states 41Threads can be in one of these states: 42.Bl -tag -offset indent -width Dv -compact 43.It cond_wait 44Executing 45.Xr pthread_cond_wait 3 46or 47.Xr pthread_cond_timedwait 3 . 48.It dead 49Waiting for resource deallocation by the thread garbage collector. 50.It deadlock 51Waiting for a resource held by the thread itself. 52.It fdlr_wait 53File descriptor read lock wait. 54.It fdlw_wait 55File descriptor write lock wait. 56.It fdr_wait 57Executing one of 58.Xr accept 2 , 59.Xr read 2 , 60.Xr readv 2 , 61.Xr recvfrom 2 , 62.Xr recvmsg 2 . 63.It fdw_wait 64Executing one of 65.Xr connect 2 , 66.Xr sendmsg 2 , 67.Xr sendto 2 , 68.Xr write 2 , 69.Xr writev 2 . 70.It file_wait 71Executing 72.Xr flockfile 3 73or similar. 74.It join 75Executing 76.Xr pthread_join 3 . 77.It mutex_wait 78Executing 79.Xr pthread_mutex_lock 3 . 80.It poll_wait 81Executing 82.Xr poll 2 . 83.It running 84Scheduled for, or engaged in, program execution. 85.It select_wait 86Executing 87.Xr select 2 . 88.It sigsuspend 89Executing 90.Xr sigsuspend 2 . 91.It sigwait 92Executing 93.Xr sigwait 3 . 94.It sleep_wait 95Executing 96.Xr sleep 3 97or 98.Xr nanosleep 2 . 99.It spinblock 100Waiting for a machine-level atomic lock. 101.It suspended 102Suspended with 103.Xr pthread_suspend_np 3 . 104.It wait_wait 105Executing 106.Xr wait4 2 107or similar. 108.El 109.Ss Thread flags 110The first three flags are one of: 111.Bl -tag -offset indent -width 3en -compact 112.It "p" 113Private, system thread (e.g., the garbage collector). 114.It "E, C, or c" 115Thread is exiting (E), has a cancellation pending (C) (see 116.Xr pthread_cancel 3 ) , 117or is at a cancellation point (c). 118.It "t" 119Thread is being traced. 120.El 121The next 7 flags refer to thread attributes: 122.Bl -tag -offset indent -width 3en -compact 123.It "C" 124Thread is in the 125.Dv CONDQ . 126.It "R" 127Thread is in the 128.Dv WORKQ . 129.It "W" 130Thread is in the 131.Dv WAITQ . 132.It "P" 133Thread is in the 134.Dv PRIOQ . 135.It "d" 136Thread has been detached (see 137.Xr pthread_detach 3 ) . 138.It "i" 139Thread inherits scheduler properties. 140.It "f" 141Thread will save floating point context. 142.El 143.Ss Scheduling algorithm 144The scheduling algorithm used by the user-level thread library is 145roughly as follows: 146.Bl -enum -compact 147.It 148Threads each have a time slice credit which is debited 149by the actual time the thread spends in running. 150Freshly scheduled threads are given a time slice credit of 100000 usec. 151.It 152Give an incremental priority update to run-enabled threads that 153have not run since the last time that an incremental priority update 154was given to them. 155.It 156Choose the next run-enabled thread with the highest priority, 157that became inactive least recently, and has 158the largest remaining time slice. 159.El 160.Pp 161When all threads are blocked, the process also blocks. 162When there are no threads remaining, 163the process terminates with an exit code of zero. 164.Ss Thread stacks 165Each thread has (or should have) a different stack, whether it be provided by a 166user attribute, or provided automatically by the system. 167If a thread overflows its stack, unpredictable results may occur. 168System-allocated stacks (including that of the initial thread) 169are typically allocated in such a way that a 170.Dv SIGSEGV 171signal is delivered to the process when a stack overflows. 172.Pp 173Signals handlers are normally run on the stack of the currently executing 174thread. 175Hence, if you want to handle the 176.Dv SIGSEGV 177signal, you should make use of 178.Xr sigaltstack 2 179or 180.Xr sigprocmask 2 . 181.Sh ENVIRONMENT 182.Bl -tag -width "PTHREAD_DEBUG" 183.It Ev PTHREAD_DEBUG 184Enables verbose 185.Dv SIGINFO 186signal output. 187.It Ev LIBC_R_DEBUG 188Display thread status every time the garbage collection thread runs, 189approximately once every 10 seconds. The status display verbosity is 190controled by the 191.Ev PTHREAD_DEBUG 192environment variable. 193.El 194.Sh SEE ALSO 195.Xr pthread_cleanup_pop 3 , 196.Xr pthread_cleanup_push 3 , 197.Xr pthread_cond_broadcast 3 , 198.Xr pthread_cond_destroy 3 , 199.Xr pthread_cond_init 3 , 200.Xr pthread_cond_signal 3 , 201.Xr pthread_cond_timedwait 3 , 202.Xr pthread_cond_wait 3 , 203.Xr pthread_create 3 , 204.Xr pthread_detach 3 , 205.Xr pthread_equal 3 , 206.Xr pthread_exit 3 , 207.Xr pthread_getspecific 3 , 208.Xr pthread_join 3 , 209.Xr pthread_key_create 3 , 210.Xr pthread_key_delete 3 , 211.Xr pthread_mutex_destroy 3 , 212.Xr pthread_mutex_init 3 , 213.Xr pthread_mutex_lock 3 , 214.Xr pthread_mutex_trylock 3 , 215.Xr pthread_mutex_unlock 3 , 216.Xr pthread_once 3 , 217.Xr pthread_rwlock_destroy 3 , 218.Xr pthread_rwlock_init 3 , 219.Xr pthread_rwlock_rdlock 3 , 220.Xr pthread_rwlock_unlock 3 , 221.Xr pthread_rwlock_wrlock 3 , 222.Xr pthread_rwlockattr_destroy 3 , 223.Xr pthread_rwlockattr_getpshared 3 , 224.Xr pthread_rwlockattr_init 3 , 225.Xr pthread_rwlockattr_setpshared 3 , 226.Xr pthread_self 3 , 227.Xr pthread_setspecific 3 228.Sh STANDARDS 229The user-level thread library provides functions that 230conform to ISO/IEC 9945-1 ANSI/IEEE 231.Pq Dq Tn POSIX 232Std 1003.1 Second Edition 1996-07-12. 233.Sh AUTHORS 234John Birrell 235.Pa ( jb@freebsd.org ) 236wrote the majority of the user level thread library. 237.\" David Leonard did a fair bit too, but is far too modest. 238.Sh BUGS 239The library contains a scheduler that uses the 240process virtual interval timer to pre-empt running threads. 241This means that using 242.Xr setitimer 2 243to alter the process virtual timer will have undefined effects. The 244.Dv SIGVTALRM 245will never be delivered to threads in a process. 246.Pp 247Some pthread functions fail to work correctly when linked using the 248.Fl g 249option to 250.Xr cc 1 251or 252.Xr gcc 1 . 253The problems do not occur when linked using the 254.Fl ggdb 255option. 256