NAME
pthreads
—
POSIX 1003.1c thread
interface
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.
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
- Cleanup Routines
- Condition Variable Routines
- Mutex Routines
- Non Portable Extensions
- Per-Thread Context Routines
- Read/Write Lock Routines
- Thread Routines
Attribute Object Routines
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_getstack
()- Get stackaddr and stacksize attributes.
pthread_attr_setstack
()- Set stackaddr and stacksize attributes.
pthread_attr_getstackaddr
()- Get stackaddr attribute.
pthread_attr_setstackaddr
()- Set stackaddr attribute.
pthread_attr_getstacksize
()- Get stacksize attribute.
pthread_attr_setstacksize
()- Set stacksize attribute.
pthread_attr_getguardsize
()- Get guardsize attribute.
pthread_attr_setguardsize
()- Set guardsize attribute.
Cleanup Routines
The functions available are as follows:
pthread_atfork
()- Register fork handlers.
pthread_cleanup_pop
()- Call the first cleanup routine.
pthread_cleanup_push
()- Add a cleanup function for thread exit.
Condition Variable Routines
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.
Mutex Routines
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
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.
Per-Thread Context Routines
The functions available are as follows:
pthread_key_create
()- Thread-specific data key creation.
pthread_key_delete
()- Delete a thread-specific data key.
pthread_getspecific
()- Get a thread-specific data value.
pthread_setspecific
()- Set a thread-specific data value.
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.
- Get the process shared attribute.
pthread_rwlockattr_init
()- Initialise a read/write lock.
- Set the process shared attribute.
Thread Routines
The functions available are as follows:
pthread_create
()- Create a new thread.
pthread_cancel
()- Cancel execution of a 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_setcancelstate
()- Set cancelability state.
pthread_setcanceltype
()- Set cancelability state.
pthread_testcancel
()- Set cancelability state.
pthread_sigmask
()- Examine/change a thread's signal mask.
Thread states
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
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
The scheduling algorithm used by the user-level thread library is roughly as follows:
- 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.
- 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.
- 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
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
The following functions are not thread safe:
The
ctermid
()
and
tmpnam
()
functions are not thread safe when passed a NULL
argument.
ENVIRONMENT
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.
SEE ALSO
pthread_atfork(3), pthread_attr_init(3), pthread_attr_setdetachstate(3), pthread_attr_setguardsize(3), pthread_attr_setstack(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)
STANDARDS
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.
AUTHORS
John Birrell (jb@freebsd.org) wrote the majority of the user level thread library.
BUGS
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.