diff options
Diffstat (limited to 'lib/libc_r/man/pthreads.3')
| -rw-r--r-- | lib/libc_r/man/pthreads.3 | 225 |
1 files changed, 145 insertions, 80 deletions
diff --git a/lib/libc_r/man/pthreads.3 b/lib/libc_r/man/pthreads.3 index 055033a8dd9..b42a627c6e6 100644 --- a/lib/libc_r/man/pthreads.3 +++ b/lib/libc_r/man/pthreads.3 @@ -1,86 +1,120 @@ +.\" $OpenBSD: pthreads.3,v 1.3 1999/03/22 04:21:45 d Exp $ +.\" David Leonard <d@openbsd.org>, 1998. Public domain. .Dd August 17, 1998 .Dt PTHREADS 3 .Os BSD 4 .Sh NAME .Nm pthreads .Nd POSIX 1003.1c thread interface -.Sh SYNOPSIS -.Fd #include <pthread.h> -.Ft int -.Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg" -.Ft void -.Fn pthread_cleanup_pop "int execute" -.Ft void -.Fn pthread_cleanup_push "void (*cleanup_routine)(void *)" "void *arg" -.Ft int -.Fn pthread_cond_broadcast "pthread_cond_t *cond" -.Ft int -.Fn pthread_cond_destroy "pthread_cond_t *cond" -.Ft int -.Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr" -.Ft int -.Fn pthread_cond_signal "pthread_cond_t *cond" -.Ft int -.Fn pthread_cond_timedwait "pthread_cond_t *cond" "pthread_mutex_t *mutex" "const struct timespec *abstime" -.Ft int -.Fn pthread_cond_wait "pthread_cond_t *cond" "pthread_mutex_t *mutex" -.Ft int -.Fn pthread_create "pthread_t *thread" "const pthread_attr_t *attr" "void *(*start_routine)(void *)" "void *arg" -.Fn pthread_exit -.Ft int -.Fn pthread_detach "pthread_t thread" -.Ft int -.Fn pthread_equal "pthread_t t1" "pthread_t t2" -.Ft void -.Fn pthread_exit "void *value_ptr" -.Ft void * -.Fn pthread_getspecific "pthread_key_t key" -.Ft int -.Fn pthread_join "pthread_t thread" "void **value_ptr" -.Ft int -.Fn pthread_key_create "pthread_key_t *key" "void (*destructor)(void *)" -.Ft int -.Fn pthread_key_delete "pthread_key_t key" -.Ft int -.Fn pthread_mutex_destroy "pthread_mutex_t *mutex" -.Ft int -.Fn pthread_mutex_init "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr" -.Ft int -.Fn pthread_mutex_lock "pthread_mutex_t *mutex" -.Ft int -.Fn pthread_mutex_trylock "pthread_mutex_t *mutex" -.Ft int -.Fn pthread_mutex_unlock "pthread_mutex_t *mutex" -.Ft int -.Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)" -.Ft int -.Fn pthread_rwlock_destroy "pthread_rwlock_t *lock" -.Ft int -.Fn pthread_rwlock_init "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr" -.Ft int -.Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock" -.Ft int -.Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock" -.Ft int -.Fn pthread_rwlock_unlock "pthread_rwlock_t *lock" -.Ft int -.Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock" -.Ft int -.Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock" -.Ft int -.Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr" -.Ft int -.Fn pthread_rwlockattr_getpshared "pthread_rwlockattr_t *attr" "int *pshared" -.Ft int -.Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr" -.Ft int -.Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int *pshared" -.Ft pthread_t -.Fn pthread_self "void" -.Ft int -.Fn pthread_setspecific "pthread_key_t key" "const void *value" .Sh DESCRIPTION -Steal something from the posix specs to describe what a thread is. +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 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 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 , @@ -106,7 +140,7 @@ Steal something from the posix specs to describe what a thread is. .Xr pthread_once 3 , .Xr pthread_rwlock_destroy 3 , .Xr pthread_rwlock_init 3 , -.Xr pthread_rwlock_rdlock.3 +.Xr pthread_rwlock_rdlock 3 , .Xr pthread_rwlock_unlock 3 , .Xr pthread_rwlock_wrlock 3 , .Xr pthread_rwlockattr_destroy 3 , @@ -114,9 +148,40 @@ Steal something from the posix specs to describe what a thread is. .Xr pthread_rwlockattr_init 3 , .Xr pthread_rwlockattr_setpshared 3 , .Xr pthread_self 3 , -.Xr pthread_setspecific 3 +.Xr pthread_setspecific 3 .Sh STANDARDS -.Fn pthread_create -conforms to ISO/IEC 9945-1 ANSI/IEEE +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. |