pthreads(5) pthreads(5) NAME pthreads - introduction to POSIX thread characteristics DESCRIPTION This man page is intended as an overview of the POSIX thread model as implemented in IRIX; it is not an introduction to thread programming or a detailed description of the IRIX implementation. Thread programming is motivated by two concerns: Application Performance + On a multiprocessor multiple threads may run at the same time. + Operations that cause the caller to wait do not prevent other threads (in the same process) from making progress. Programming Model + Complex applications can be structured more elegantly by partitioning with threads. + Threads share many resources implicitly which can simplify co- operative algorithms. In the past a UNIX process has been thought of as having a single thread. The POSIX thread programming model (known as pthreads) introduces the concept of multiple threads within a single process. A POSIX thread is an executable entity that belongs to a process. It contains sufficient state to enable it to run on a processor independently of its fellows. In most other respects threads share state with their host process. The vast majority of interfaces and features work the same way in a multi- threaded process as an unthreaded one. The POSIX threads API provides a set of interfaces and semantics for creating and controlling threads. Because the interfaces are defined by the ISO standards organisation an application using them may enjoy the benefits of parallel programming without sacrificing portability. Applications To create a pthread process an application must be linked with the pthread run-time library. It is also recommended that the thread safe options be enabled at compile time using the feature test macro, _POSIX_C_SOURCE. cc -D_POSIX_C_SOURCE=199506L app.c -llib0 -llib1 ... -lpthread See intro(3), section 3P for further details. Components POSIX threads introduces a number of thread components. Attribute An attribute is a characteristic of something that defines its behaviour. Most of the objects introduced by pthreads have characteristics which are set when it is created; indeed some characteristics may only be set at that time. A set of characteristics may be specified in an attribute object which is passed to the creation interface. An analogy is a mould or template that is used to shape some artifact. Every attribute has a default value and the attribute object itself is optional. Thread A thread executes code. It is created using pthread_create() and either inherits characteristics from its creator or has them specified via creation attributes. The pthread_attr_* interfaces may be used to create a thread attributes object. Many features of the process are shared by its threads, including process and user ids (PID, UID), file descriptors, memory (including text and data) and signal handlers. Each thread has a unique identity which is used by a number of pthread interfaces. Thread ids may be compared using pthread_equal(). Threads terminate with an exit status [see pthread_exit()]. By default the thread identity and exit status persist after the thread has terminated until the status is retrieved using pthread_join(). An application should either retrieve this status or arrange for it to be automatically discarded on thread termination using pthread_detach() or setting the detach thread attribute. Mutex Lock A mutex lock facilitates exclusive access by a thread to a resource. Only one thread may own a mutex at a time and is thus guaranteed exclusive access. Mutex interfaces are described on the pthread_mutex_* man pages. The pthread_mutexattr_* interfaces may be used to create a mutex attributes object. Attributes include error checking, recursion and owner priority. Mutexes are intended to be lightweight and only owned for brief periods of time. Condition Variable A condition variable synchronises threads with an event of interest. Condition variables allow a thread to wait for an event and be woken up when the event occurs; the nature of the event is determined by the application. Condition variable interfaces are described on the pthread_cond_* man pages. The pthread_condattr_* interfaces may be used to create a condition variable attributes object. Read-Write Lock A read-write lock facilitates shared access for read and exclusive access for write by threads to a resource. They are used in conjunction with resources which are frequently read but infrequently changed (written). Read-write lock interfaces are described on the pthread_rwlock_* man pages. The pthread_rwlockattr_* interfaces may be used to create a read-write lock attributes object. Semaphore A semaphore synchronises threads with a counter. Semaphores are not part of pthreads per se and do not have an associated attributes object. However anonymous semaphores provide a pshared flag (for semaphores which are private to the process) which allows pthreads to optimise access [see sem_init(3C)]. Semaphore interfaces are described on the sem_* man pages. Semantics POSIX threads introduces the following special semantics. Cancellation A cancellation request is a request for a thread to terminate. Each thread specifies whether and when to act on cancellation requests using its cancelability state and type. A request is made with pthread_cancel() and the state and type are set with pthread_setcancelstate() and pthread_setcanceltype(). Termination handlers may be established to execute code when a thread terminates for some reason including acting on a cancellation request. Signals In the pthread signal model all threads share the signal disposition [see sigaction(2)] but each thread has its own signal mask of blocked signals. Signals may be sent to individual threads using the pthread_kill() interface. Each thread may change its own mask using pthread_sigmask(). In IRIX, sigprocmask(2) is equivalent to pthread_sigmask() but a portable pthread application should only use the latter. A signal is delivered to at most one thread; it is not broadcast to all threads. + When a signal is directed at a process the first eligible thread is chosen to receive it. An eligible thread is one that does not have the signal blocked in its signal mask or is waiting in sigwait(3). If there are no eligible threads then the signal remains pending on the process until a thread becomes eligible. This is called asynchronous signal delivery; kill(2) causes this type of delivery. + When a signal is directed at a thread then that thread will receive it. If the signal is blocked then it will remain pending on the target thread; it will not be delivered to a different thread. This is called synchronous signal delivery; exceptions and program faults cause this type of delivery. + If the action of the signal is to stop, continue or terminate the recipient then it will act on the process as a whole. It is not possible to stop, continue or terminate a single thread with a signal. Notifications An extension to signal handling for threads is the addition of SIGEV_THREAD which creates a thread instead of sending a signal as a means of handling the occurrence of some event [see mq_notify(3C), aio_read(3) and timer_create(3C)]. Creation of the thread takes place when the event occurs so care should be taken to avoid any errors or else the notification may be lost. Scheduling When a processor executes instructions on behalf of a user it does so according to a set of scheduling attributes which are part of a kernel execution vehicle. Every thread that executes on a processor or waits in the kernel needs such a vehicle. POSIX threads makes a distinction between system scope (kernel) scheduling and process scope (run-time) scheduling. The SGI implementation adds an additional scheduling scope, bound scope. These bound scope threads are scheduled exactly the same as POSIX process scope threads. For the rest of this man page, the discussion of process scope scheduling is applicable for bound scope threads. In both scopes the individual thread scheduling policy and priority values are set using the interfaces pthread_attr_setschedpolicy(), pthread_attr_setschedparam(), and pthread_setschedparam(). Scope is defined when a thread is created using pthread_attr_setscope(): system scope threads are scheduled by the kernel; the scheduling attributes of the thread and the kernel execution vehicle are the same. The kernel includes all system scope threads in its scheduling decisions. These threads run at realtime policy and priority and may only be created by privileged users. process scope threads are scheduled by the pthread run-time; the scheduling attributes of the thread and the kernel execution vehicle may be different. The run-time makes scheduling decisions based only on the process scope threads in the host process. An advantage of system scope is that a thread can get high performance and deterministic response. A disadvantage is that kernel resources must be allocated to each thread. In contrast, process scope threads only require kernel state when they are executing on a processor or waiting in the kernel. The run-time scheduler multiplexes process scope threads onto a smaller number of kernel execution vehicles. This can produce faster scheduling because no kernel state is involved. The number of execution vehicles used for process scope threads depends on application behaviour and system configuration. By default, the run-time adjusts this number dynamically but the pthread_setconcurrency() interface gives a strong hint as to the desired value. The execution vehicles used for process scope threads share a set of kernel scheduling attributes which can be changed using the sched_setscheduler() and sched_setparam() interfaces. These interfaces do not affect system scope thread scheduling. As with system scope threads changing these scheduling attributes is a privileged operation. Low-overhead Locking In order to protect updates to internal pthread data structures, a low-overhead locking mechanism is required. This locking interface is not user-callable and is contained entirely within the pthread library. When pthreads are present, this locking mechanism is also used to ensure that some routines in libc can be safely called from multiple threads. Some examples of this are the stdio(3S) routines and the malloc(3C) routines. By default, these locks spin/sleep for process scope and bound scope threads on multiprocessor systems, and immediately block for system scope threads and on single processor systems. In the spin/sleep lock path, the lock will be tried 1000 times, and then nanosleep(2) will be called. This process will be repeated until the lock can be obtained. This process can be tuned for an individual application with the PT_SPINS environment variable. This determines how many times the lock is tried before sleeping. This environment variable is checked once at program startup time. Different spin values may be used to improve application throughput; however, higher values will probably increase user time while lower values will probably increase system time. In general, applications with more pthreads than processors will probably benefit from setting PT_SPINS to a lower value, while applications with fewer pthreads may benefit from setting the environment variable to a higher value. If the environment variable is set to 0, these locks will all become blocking locks. realtime(5) applications and applications that create only system scope threads may benefit from setting PT_SPINS to 0. This forces the locks to block immediately instead of having the lock routine do a run-time check to determine if the caller is a system scope thread. Thread Data Pthreads share the address space; stacks, text and data are accessible by all threads in the process. This means that access to shared data is simpler than where multiple processes use a shared memory region which each must map. The cost is the potential for accidental corruption. Individual thread data is provided using the notion of a shared set of keys and unique thread values bound to each key. The pthread_key_create() interface creates a new, shared key and pthread_setspecific() allows a thread to bind its own value to a key. Conceptually, the key is an index to an array of values. The same key used by different threads may retrieve a different values because each thread has its own array. Process Management Some basic UNIX interfaces have particular semantics when called from a POSIX threads process. fork(2) creates a new pthread process and follows the usual rules for inherited state. The new process has a single pthread (the one which made the call); all other pthreads active prior to fork() are quietly destroyed and their resources (stacks etc.) reclaimed by the pthread run-time. A number of issues arise because fork() causes data to be copied from the parent to the child with no synchronisation with threads that may be modifying that data. To allow the application to perform its own synchronisation the pthread_atfork() interface can register handlers to be processed when fork() is used. In general operations which are safe to perform after a fork() are the same as those which are safe to perform in a signal handler. exec(2) overlays a new process image on the calling process; all threads from the old image are destroyed. Thread termination handlers and thread data destruction [see pthread_cleanup_push() and pthread_key_create()] are not performed. The new process will only be a pthread process if the new image is of a pthread process. exit(2) performs all the usual process clean up operations and then destroys all threads in the process. Thread termination handlers and thread data destruction [see pthread_cleanup_push() and pthread_key_create()] are not performed. Limitations With POSIX threads there are some limitations and practices to avoid. Not enough pthreads Each pthread process has a resource limit called RLIMIT_PTHREAD on the number of threads it can create. The value is inherited by child processes and may be set using setrlimit(2) or the shell limit and ulimit commands. The default limits can be changed using the systune(1M) command on the rlimit_pthread_cur and rlimit_pthread_max variables. Fatal exceptions When a thread executes code in the pthread run-time scheduler it masks signals so that signal handlers always run in a consistent environment. A side effect of this is that if the thread raises an exception (for example due to memory corruption) the kernel will terminate the process. As an aid to debugging such problems the environment variable PT_CORE should be set prior to starting the application so that a core file will be generated. Stack overrun Unlike the default stack in an unthreaded IRIX process, pthread stacks are limited [see pthread_attr_setstacksize()] and a thread may overrun its stack. By default pthread stacks have a protected region at the end of the stack [see pthread_attr_setguardsize()] that can turn some of these overruns into a protection faults which is generally preferable to overwriting data. Dynamic loading The pthread library can be made available to a running process. The pthread DSO can be dynamically loaded using dlopen(3C) or sgidladd(3C). Any pthread calls made before pthread library is loaded will all return ENOSYS. Using sprocs The sproc(2) model of threading is incompatible with POSIX threads. Attempts by an sproc process to create pthreads and vice-versa will be rejected. Priority Attempts to create a pthread process at a priority outside of the valid range will be rejected [see sched_get_priority_min(2) and sched_get_priority_max(2)]. Specifically, weightless is not a valid pthread priority. MAP_LOCAL memory The POSIX thread memory model requires that memory be available to all threads. The MAP_LOCAL option to mmap(2) is useful only to sproc processes and should not be used with pthreads. Dynamic memory allocation The sbrk(2) call is not thread-safe. It is used by the C run-time memory allocator, malloc(3C), which is always used by the pthread run-time. Safe use of sbrk(2) outside of the run-time (for example by a third party memory allocator) is not therefore possible. Documentation Additional on-line documentation about pthreads is available in: Topics in IRIX Programming: Chapter 13 SpeedShop User's Guide: Chapter 6 SEE ALSO pthread_*(3P) Page 7