1.\" $OpenBSD: pthreads.3,v 1.3 1999/03/22 04:21:45 d Exp $ 2.\" David Leonard <d@openbsd.org>, 1998. Public domain. 3.Dd August 17, 1998 4.Dt PTHREADS 3 5.Os BSD 4 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 19.Pa ( libc_r ) 20that replaces the standard C library 21.Pa ( libc ) . 22This replacement is currently achieved by specifying the 23.Fl pthread 24flag to 25.Xr cc 1 26for each compilation unit, and for linking. 27(But see the section on 28.Sx BUGS . ) 29.Pp 30The 31.Dv SIGINFO 32signal can be sent to a threaded process to have the library show the state of 33all of its threads. The information is sent to the process' 34.Pa /dev/tty . 35.Pp 36Threads can be in one of these states: 37.Bl -tag -offset indent -width Dv -compact 38.It cond_wait 39Executing 40.Xr pthread_cond_wait 3 41or 42.Xr pthread_cond_timedwait 3 . 43.It dead 44Waiting for resource deallocation by the thread garbage collector. 45.It fdlr_wait 46File descriptor read lock wait. 47.It fdlw_wait 48File descriptor write lock wait. 49.It fdr_wait 50Executing one of 51.Xr accept 2 , 52.Xr read 2 , 53.Xr readv 2 , 54.Xr recvfrom 2 , 55.Xr recvmsg 2 . 56.It fdw_wait 57Executing one of 58.Xr connect 2 , 59.Xr sendmsg 2 , 60.Xr sendto 2 , 61.Xr write 2 , 62.Xr writev 2 . 63.It file_wait 64Executing 65.Xr flockfile 3 66or similar. 67.It join 68Executing 69.Xr pthread_join 3 . 70.It mutex_wait 71Executing 72.Xr pthread_mutex_lock 3 . 73.It running 74Scheduled for, or engaged in, program execution. 75.It select_wait 76Executing 77.Xr select 2 . 78.It sigsuspend 79Executing 80.Xr sigsuspend 2 . 81.It sigwait 82Executing 83.Xr sigwait 3 . 84.It sleep_wait 85Executing 86.Xr sleep 3 87or 88.Xr nanosleep 2 . 89.It suspended 90Suspended with 91.Xr pthread_suspend_np 3 . 92.It wait_wait 93Executing 94.Xr wait4 2 95or similar. 96.El 97.Ss Scheduling algorithm 98The scheduling algorithm used by the user-level thread library is 99roughly as follows: 100.Bl -enum -compact 101.It 102Threads each have a time slice credit which is debited 103by the actual time the thread spends in running. 104Freshly scheduled threads are given a time slice credit of 100000 usec. 105.It 106Give an incremental priority update to run-enabled threads that 107have not run since the last time that an incremental priority update 108was given to them. 109.It 110Choose the next run-enabled thread with the highest priority, 111that became inactive least recently, and has 112the largest remaining time slice. 113.El 114.Pp 115When all threads are blocked, the process also blocks. 116When there are no threads remaining, 117the process terminates with an exit code of zero. 118.Sh SEE ALSO 119.Xr pthread_cleanup_pop 3 , 120.Xr pthread_cleanup_push 3 , 121.Xr pthread_cond_broadcast 3 , 122.Xr pthread_cond_destroy 3 , 123.Xr pthread_cond_init 3 , 124.Xr pthread_cond_signal 3 , 125.Xr pthread_cond_timedwait 3 , 126.Xr pthread_cond_wait 3 , 127.Xr pthread_create 3 , 128.Xr pthread_detach 3 , 129.Xr pthread_equal 3 , 130.Xr pthread_exit 3 , 131.Xr pthread_getspecific 3 , 132.Xr pthread_join 3 , 133.Xr pthread_key_create 3 , 134.Xr pthread_key_delete 3 , 135.Xr pthread_mutex_destroy 3 , 136.Xr pthread_mutex_init 3 , 137.Xr pthread_mutex_lock 3 , 138.Xr pthread_mutex_trylock 3 , 139.Xr pthread_mutex_unlock 3 , 140.Xr pthread_once 3 , 141.Xr pthread_rwlock_destroy 3 , 142.Xr pthread_rwlock_init 3 , 143.Xr pthread_rwlock_rdlock 3 , 144.Xr pthread_rwlock_unlock 3 , 145.Xr pthread_rwlock_wrlock 3 , 146.Xr pthread_rwlockattr_destroy 3 , 147.Xr pthread_rwlockattr_getpshared 3 , 148.Xr pthread_rwlockattr_init 3 , 149.Xr pthread_rwlockattr_setpshared 3 , 150.Xr pthread_self 3 , 151.Xr pthread_setspecific 3 152.Sh STANDARDS 153The user-level thread library provides functions that 154conform to ISO/IEC 9945-1 ANSI/IEEE 155.Pq Dq Tn POSIX 156Std 1003.1 Second Edition 1996-07-12. 157.Sh AUTHORS 158John Birrell 159.Pa ( jb@freebsd.org ) 160wrote the majority of the user level thread library. 161.\" David Leonard did a fair bit too, but is far too modest. 162.Sh BUGS 163Having to pass the 164.Fl pthread 165flag to 166.Xr cc 1 167for every compilation unit and linking is an awful kludge. 168Future releases will most likely depreceate this flag, 169and instead only use 170.Fl l Ns Pa pthread 171during linking. 172.Pp 173The library contains of a scheduler that uses the 174process virtual interval timer to pre-empt running threads. 175This means that using 176.Xr setitimer 2 177to alter the process virtual timer will have undefined effects. The 178.Dv SIGVTALRM 179will never be delivered to threads in a process. 180.Pp 181Due to the 182type definition of 183.Ft fd_set 184and the internal reliance on 185.Xr select 2 , 186threaded processes may be arbitrarily limited in the number of file descriptors 187that they can collectively have open. 188