1.\" $OpenBSD: pthreads.3,v 1.7 2000/01/06 07:10:16 d 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 lpthread 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 descrbes each thread's 28ID, 29state (see 30.Sx Thread states ) , 31current priority, 32flags (see 33.Sx Thread flags ) 34and name (as set by 35.Xr pthread_set_name_np 3 ) . 36.Pp 37.Ss Thread states 38Threads can be in one of these states: 39.Bl -tag -offset indent -width Dv -compact 40.It cond_wait 41Executing 42.Xr pthread_cond_wait 3 43or 44.Xr pthread_cond_timedwait 3 . 45.It dead 46Waiting for resource deallocation by the thread garbage collector. 47.It deadlock 48Waiting for a resource held by the thread itself. 49.It fdlr_wait 50File descriptor read lock wait. 51.It fdlw_wait 52File descriptor write lock wait. 53.It fdr_wait 54Executing one of 55.Xr accept 2 , 56.Xr read 2 , 57.Xr readv 2 , 58.Xr recvfrom 2 , 59.Xr recvmsg 2 . 60.It fdw_wait 61Executing one of 62.Xr connect 2 , 63.Xr sendmsg 2 , 64.Xr sendto 2 , 65.Xr write 2 , 66.Xr writev 2 . 67.It file_wait 68Executing 69.Xr flockfile 3 70or similar. 71.It join 72Executing 73.Xr pthread_join 3 . 74.It mutex_wait 75Executing 76.Xr pthread_mutex_lock 3 . 77.It poll_wait 78Executing 79.Xr poll 2 . 80.It running 81Scheduled for, or engaged in, program execution. 82.It select_wait 83Executing 84.Xr select 2 . 85.It sigsuspend 86Executing 87.Xr sigsuspend 2 . 88.It sigwait 89Executing 90.Xr sigwait 3 . 91.It sleep_wait 92Executing 93.Xr sleep 3 94or 95.Xr nanosleep 2 . 96.It spinblock 97Waiting for a machine-level atomic lock. 98.It suspended 99Suspended with 100.Xr pthread_suspend_np 3 . 101.It wait_wait 102Executing 103.Xr wait4 2 104or similar. 105.El 106.Ss Thread flags 107The meaning of thread flags are as follows: 108.Bl -tag -offset indent -width 3en -compact 109.It p 110Private, system thread (e.g. the garbage collector). 111.It E 112Thread is exiting. 113.It C 114Thread has an cancellation pending (see 115.Xr pthread_cancel 3 ) . 116.It c 117Thread is at a cancellation point. 118.It t 119Thread is being traced. 120.El 121The other flags refer to thread attributes: 122.Bl -tag -offset indent -width 3en -compact 123.It d 124Thread has been detached (see 125.Xr pthread_detach 3 ) . 126.It i 127Thread inherits scheduler properties. 128.It f 129Thread will save floating point context. 130.El 131.Ss Scheduling algorithm 132The scheduling algorithm used by the user-level thread library is 133roughly as follows: 134.Bl -enum -compact 135.It 136Threads each have a time slice credit which is debited 137by the actual time the thread spends in running. 138Freshly scheduled threads are given a time slice credit of 100000 usec. 139.It 140Give an incremental priority update to run-enabled threads that 141have not run since the last time that an incremental priority update 142was given to them. 143.It 144Choose the next run-enabled thread with the highest priority, 145that became inactive least recently, and has 146the largest remaining time slice. 147.El 148.Pp 149When all threads are blocked, the process also blocks. 150When there are no threads remaining, 151the process terminates with an exit code of zero. 152.Ss Thread stacks 153Each thread has (or should have) a different stack, whether it be provided by a 154user attribute, or provided automatically by the system. 155If a thread overflows its stack, unpredictable results may occur. 156System-allocated stacks (including that of the initial thread) 157are typically allocated in such a way that a 158.Dv SIGSEGV 159signal is deliverred to the process when a stack overflows. 160.Pp 161Signals handlers are normally run on the stack of the currently executing 162thread. 163Hence, if you want to handle the 164.Dv SIGSEGV 165signal, you should make use of 166.Xr sigaltstack 3 167or 168.Xr sigprocmask 3 . 169.Sh SEE ALSO 170.Xr pthread_cleanup_pop 3 , 171.Xr pthread_cleanup_push 3 , 172.Xr pthread_cond_broadcast 3 , 173.Xr pthread_cond_destroy 3 , 174.Xr pthread_cond_init 3 , 175.Xr pthread_cond_signal 3 , 176.Xr pthread_cond_timedwait 3 , 177.Xr pthread_cond_wait 3 , 178.Xr pthread_create 3 , 179.Xr pthread_detach 3 , 180.Xr pthread_equal 3 , 181.Xr pthread_exit 3 , 182.Xr pthread_getspecific 3 , 183.Xr pthread_join 3 , 184.Xr pthread_key_create 3 , 185.Xr pthread_key_delete 3 , 186.Xr pthread_mutex_destroy 3 , 187.Xr pthread_mutex_init 3 , 188.Xr pthread_mutex_lock 3 , 189.Xr pthread_mutex_trylock 3 , 190.Xr pthread_mutex_unlock 3 , 191.Xr pthread_once 3 , 192.Xr pthread_rwlock_destroy 3 , 193.Xr pthread_rwlock_init 3 , 194.Xr pthread_rwlock_rdlock 3 , 195.Xr pthread_rwlock_unlock 3 , 196.Xr pthread_rwlock_wrlock 3 , 197.Xr pthread_rwlockattr_destroy 3 , 198.Xr pthread_rwlockattr_getpshared 3 , 199.Xr pthread_rwlockattr_init 3 , 200.Xr pthread_rwlockattr_setpshared 3 , 201.Xr pthread_self 3 , 202.Xr pthread_setspecific 3 203.Sh STANDARDS 204The user-level thread library provides functions that 205conform to ISO/IEC 9945-1 ANSI/IEEE 206.Pq Dq Tn POSIX 207Std 1003.1 Second Edition 1996-07-12. 208.Sh AUTHORS 209John Birrell 210.Pa ( jb@freebsd.org ) 211wrote the majority of the user level thread library. 212.\" David Leonard did a fair bit too, but is far too modest. 213.Sh BUGS 214The library contains of a scheduler that uses the 215process virtual interval timer to pre-empt running threads. 216This means that using 217.Xr setitimer 2 218to alter the process virtual timer will have undefined effects. The 219.Dv SIGVTALRM 220will never be delivered to threads in a process. 221