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