pthreads - POSIX 1003.1c thread interface
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.
In OpenBSD, threads are implemented in a user-level library.
A program
using these routines must be linked with the -pthread option.
The 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' controlling tty and describes each thread's ID,
state (see
Thread states), current priority, flags (see Thread flags),
signal mask,
and name (as set by pthread_set_name_np(3)). If the environment variable
PTHREAD_DEBUG is defined additional information is displayed.
For the purpose of this document, the functions available
are grouped in
the following categories. For further information, see the
individual
man page for each function.
- Attribute Object Routines
- Cancellation Routines
- Condition Variable Routines
- Data Management Routines
- Mutex Routines
- Non Portable Extensions
- Read/Write Lock Routines
- Thread Routines
Attribute Object Routines [Toc] [Back]
The functions available are as follows:
pthread_attr_init() Initialise a threads attribute object.
pthread_attr_destroy() Destroy a threads attribute
object.
pthread_attr_getdetachstate() Get detachstate attribute.
pthread_attr_setdetachstate() Set detachstate attribute.
pthread_attr_getstackaddr() Get stackaddr attribute.
pthread_attr_setstackaddr() Set stackaddr attribute.
pthread_attr_getstacksize() Get stacksize attribute.
pthread_attr_setstacksize() Set stacksize attribute.
Cancellation Routines [Toc] [Back]
The functions available are as follows:
pthread_cancel() Cancel execution of a thread.
pthread_cleanup_pop() Call the first cleanup routine.
pthread_cleanup_push() Add a cleanup function for thread
exit.
pthread_setcancelstate() Set cancelability state.
pthread_setcanceltype() Set cancelability state.
pthread_testcancel() Set cancelability state.
Condition Variable Routines [Toc] [Back]
The functions available are as follows:
pthread_cond_broadcast() Unblock all threads waiting for a
condition
variable.
pthread_cond_destroy() Destroy a condition variable.
pthread_cond_init() Create a condition variable.
pthread_cond_signal() Unblock a thread waiting for a
condition variable.
pthread_cond_timedwait() Wait on a condition variable for a
specific
amount of time.
pthread_cond_wait() Wait on a condition variable.
Data Management Routines [Toc] [Back]
The functions available are as follows:
pthread_getspecific() Get a thread-specific data value.
pthread_setspecific() Set a thread-specific data value.
pthread_key_create() Thread-specific data key creation.
pthread_key_delete() Delete a thread-specific data key.
Mutex Routines [Toc] [Back]
The functions available are as follows:
pthread_mutex_destroy() Free resources allocated
for a mutex.
pthread_mutex_init() Create a mutex.
pthread_mutex_lock() Lock a mutex.
pthread_mutex_trylock() Attempt to lock a mutex
without
blocking.
pthread_mutex_unlock() Unlock a mutex.
pthread_mutexattr_init() Mutex attribute operations.
pthread_mutexattr_destroy() Mutex attribute operations.
pthread_mutexattr_getprioceiling() Mutex attribute operations.
pthread_mutexattr_setprioceiling() Mutex attribute operations.
pthread_mutexattr_getprotocol() Mutex attribute operations.
pthread_mutexattr_setprotocol() Mutex attribute operations.
pthread_mutexattr_gettype() Mutex attribute operations.
pthread_mutexattr_settype() Mutex attribute operations.
Non Portable Extensions [Toc] [Back]
The functions available are as follows:
pthread_main_np() Identify the main thread.
pthread_set_name_np() Set the name of a thread.
pthread_single_np() Switch thread scheduling mode.
pthread_multi_np() Switch thread scheduling mode.
pthread_stackseg_np() Return stack size and location.
pthread_suspend_np() Suspend given thread.
pthread_suspend_all_np() Suspend all threads except current
thread.
pthread_resume_np() Resumes given thread.
pthread_resume_all_np() Resumes all suspended threads.
pthread_yield() Yield control of the current
thread.
Read/Write Lock Routines
The functions available are as follows:
pthread_rwlock_destroy() Destroy a read/write lock.
pthread_rwlock_init() Initialise a read/write
lock.
pthread_rwlock_rdlock() Acquire a read/write lock
for reading.
pthread_rwlock_unlock() Release a read/write lock.
pthread_rwlock_wrlock() Acquire a read/write lock
for writing.
pthread_rwlockattr_destroy() Destroy a read/write lock.
pthread_rwlockattr_getpshared() Get the process shared attribute.
pthread_rwlockattr_init() Initialise a read/write
lock.
pthread_rwlockattr_setpshared() Set the process shared attribute.
Thread Routines [Toc] [Back]
The functions available are as follows:
pthread_create() Create a new thread.
pthread_detach() Detach a thread.
pthread_equal() Compare thread IDs.
pthread_exit() Terminate the calling thread.
pthread_getconcurrency() Get level of concurrency.
pthread_setconcurrency() Set level of concurrency.
pthread_join() Wait for thread termination.
pthread_kill() Send a signal to a specific
thread.
pthread_once() Dynamic package initialisation.
pthread_self() Get the calling thread's ID.
pthread_sigmask() Examine/change a thread's signal
mask.
Thread states [Toc] [Back]
Threads can be in one of these states:
cond_wait Executing pthread_cond_wait(3) or
pthread_cond_timedwait(3).
dead Waiting for resource deallocation by the
thread
garbage collector.
deadlock Waiting for a resource held by the
thread itself.
fdlr_wait File descriptor read lock wait.
fdlw_wait File descriptor write lock wait.
fdr_wait Executing one of accept(2), read(2),
readv(2),
recvfrom(2), recvmsg(2).
fdw_wait Executing one of connect(2), sendmsg(2),
sendto(2),
write(2), writev(2).
file_wait Executing flockfile(3) or similar.
join Executing pthread_join(3).
mutex_wait Executing pthread_mutex_lock(3).
poll_wait Executing poll(2).
running Scheduled for, or engaged in, program
execution.
select_wait Executing select(2).
sigsuspend Executing sigsuspend(2).
sigwait Executing sigwait(3).
sleep_wait Executing sleep(3) or nanosleep(2).
spinblock Waiting for a machine-level atomic lock.
suspended Suspended with pthread_suspend_np(3) or
pthread_suspend_all_np(3).
wait_wait Executing wait4(2) or similar.
Thread flags [Toc] [Back]
The first three flags are one of:
p Private, system thread (e.g., the garbage collector).
E, C, or c
Thread is exiting (E), has a cancellation pending
(C) (see
pthread_cancel(3)), or is at a cancellation point
(c).
t Thread is being traced.
The next 7 flags refer to thread attributes:
C Thread is in the CONDQ.
R Thread is in the WORKQ.
W Thread is in the WAITQ.
P Thread is in the PRIOQ.
d Thread has been detached (see pthread_detach(3)).
i Thread inherits scheduler properties.
f Thread will save floating point context.
Scheduling algorithm [Toc] [Back]
The scheduling algorithm used by the user-level thread library is roughly
as follows:
1. 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.
2. 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.
3. Choose the next run-enabled thread with the highest
priority, that
became inactive least recently, and has the largest remaining time
slice.
When all threads are blocked, the process also blocks. When
there are no
threads remaining, the process terminates with an exit code
of zero.
Thread stacks [Toc] [Back]
Each thread has (or should have) a different stack, whether
it be provided
by a user attribute, or provided automatically by the
system. If a
thread overflows its stack, unpredictable results may occur.
System-allocated
stacks (including that of the initial thread) are
typically allocated
in such a way that a SIGSEGV signal is delivered to
the process
when a stack overflows.
Signals handlers are normally run on the stack of the currently executing
thread. Hence, if you want to handle the SIGSEGV signal,
you should make
use of sigaltstack(2) or sigprocmask(2).
Thread safety [Toc] [Back]
The following functions are not thread safe:
asctime(), basename(), catgets(), crypt(), ctime(),
dbm_clearerr(),
dbm_close(), dbm_delete(), dbm_error(), dbm_fetch(),
dbm_firstkey(),
dbm_nextkey(), dbm_open(), dbm_store(), dirname(), dlerror(), drand48(),
ecvt(), encrypt(), endgrent(), endpwent(), fcvt(), ftw(),
gcvt(),
getc_unlocked(), getchar_unlocked(), getenv(), getgrent(),
getgrgid(),
getgrnam(), gethostbyaddr(), gethostbyname(), gethostent(),
getlogin(),
getnetbyaddr(), getnetbyname(), getnetent(), getopt(), getprotobyname(),
getprotobynumber(), getprotoent(), getpwent(), getpwnam(),
getpwuid(),
getservbyname(), getservbyport(), getservent(), gmtime(),
hcreate(), hdestroy(),
hsearch(), inet_ntoa(), l64a(), lgamma(), lgammaf(), localeconv(),
localtime(), lrand48(), mrand48(), nftw(), nl_langinfo(),
putc_unlocked(), putchar_unlocked(), putenv(), rand(), readdir(),
setenv(), setgrent(), setkey(), setpwent(), strerror(), strtok(), ttyname(),
unsetenv(),
The ctermid() and tmpnam() functions are not thread safe
when passed a
NULL argument.
PTHREAD_DEBUG Enables verbose SIGINFO signal output.
LIBPTHREAD_DEBUG Display thread status every time the
garbage collection
thread runs, approximately once every 10
seconds. The
status display verbosity is controlled by
the
PTHREAD_DEBUG environment variable.
pthread_attr_init(3), pthread_attr_setdetachstate(3),
pthread_attr_setstackaddr(3), pthread_attr_setstacksize(3),
pthread_cancel(3), pthread_cleanup_pop(3),
pthread_cleanup_push(3),
pthread_cond_broadcast(3), pthread_cond_destroy(3),
pthread_cond_init(3),
pthread_cond_signal(3), pthread_cond_timedwait(3),
pthread_cond_wait(3),
pthread_create(3), pthread_detach(3), pthread_equal(3),
pthread_exit(3),
pthread_getspecific(3), pthread_join(3), pthread_key_create(3),
pthread_key_delete(3), pthread_kill(3), pthread_main_np(3),
pthread_mutex_destroy(3), pthread_mutex_init(3), pthread_mutex_lock(3),
pthread_mutex_trylock(3), pthread_mutex_unlock(3),
pthread_mutexattr(3),
pthread_once(3), pthread_resume_all_np(3), pthread_resume_np(3),
pthread_rwlock_destroy(3), pthread_rwlock_init(3),
pthread_rwlock_rdlock(3), pthread_rwlock_unlock(3),
pthread_rwlock_wrlock(3), pthread_rwlockattr_destroy(3),
pthread_rwlockattr_getpshared(3), pthread_rwlockattr_init(3),
pthread_rwlockattr_setpshared(3), pthread_schedparam(3),
pthread_self(3),
pthread_set_name_np(3), pthread_setspecific(3), pthread_sigmask(3),
pthread_single_np(3), pthread_stackseg_np(3), pthread_suspend_all_np(3),
pthread_suspend_np(3), pthread_testcancel(3),
pthread_yield(3)
The user-level thread library provides functions that conform to ISO/IEC
9945-1 ANSI/IEEE (``POSIX'') Std 1003.1 Second Edition
1996-07-12.
John Birrell ([email protected]) wrote the majority of the user
level thread
library.
The library contains a scheduler that uses the process virtual interval
timer to pre-empt running threads. This means that using
setitimer(2) to
alter the process virtual timer will have undefined effects.
The
SIGVTALRM will never be delivered to threads in a process.
Some pthread functions fail to work correctly when linked
using the -g
option to cc(1) or gcc(1). The problems do not occur when
linked using
the -ggdb option.
OpenBSD 3.6 August 17, 1998
[ Back ] |
