PTHREADS(3)               OpenBSD Programmer's Manual              PTHREADS(3)

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 (libc_r) that
     replaces the standard C library (libc). This replacement is currently
     achieved by specifying the -pthread flag to cc(1) for each compilation
     unit, and for linking.  (But see the section on BUGS.)

     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 pro-
     cess' /dev/tty.

     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).
           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).
           wait_wait     Executing wait4(2) or similar.

   Scheduling algorithm
     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.

SEE ALSO
     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_mutex_destroy(3),  pthread_mutex_init(3),
      pthread_mutex_lock(3),  pthread_mutex_trylock(3),
     pthread_mutex_unlock(3),  pthread_once(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_self(3),  pthread_setspecific(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
     Having to pass the -pthread flag to cc(1) for every compilation unit and
     linking is an awful kludge.  Future releases will most likely depreceate
     this flag, and instead only use -lpthread during linking.

     The library contains of a scheduler that uses the process virtual inter-
     val timer to pre-empt running threads.  This means that using
     setitimer(2) to alter the process virtual timer will have undefined ef-
     fects. The SIGVTALRM will never be delivered to threads in a process.

     Due to the type definition of fd_set and the internal reliance on
     select(2),  threaded processes may be arbitrarily limited in the number
     of file descriptors that they can collectively have open.

OpenBSD 2.6                     August 17, 1998                              2