The header files related to pthreads functions are summarized in Table 13-2.

It is recommended that the thread-safe options be enabled at compile time using the feature test macro, _POSIX_C_SOURCE (see intro(3) for details). For example, to compile these options, use this command:

cc -D_POSIX_C_SOURCE=199506L app.c -llib0 -llib1 ... -lpthread

You can use pthreads with a program compiled to any of the supported execution models: -32 for compatibility with older systems, -n32 for 64-bit data and 32-bit addressing, or -64 for 64-bit addressing.

The pthreads functions are defined in the library libpthread.so. Link with this library using the -lpthread compiler option, which should be the last library on the command line. The compiler chooses the correct library based on the execution model: /usr/lib/libpthread.so, /usr/lib32/libpthread.so, and /usr/lib64/libpthread.so.

---

Note: A pthread program is a program that links with libpthread. Do not link with libpthread unless you intend to use the pthread interface, because libpthread replaces many standard library functions.

---

The dbx debugger and Workshop Debugger have been extended for use with threaded programs. See the dbx(1M) reference page and the documentation for Workshop Debugger for more details.

Detaching means that the pthreads library frees up resources held by the thread after it terminates (see “Joining and Detaching”). There are three ways to detach a thread:

You can use pthread_attr_setdetachstate() to specify that a thread should be detached automatically when it terminates. Do this when you know that the thread will not be joined or detached by an explicit function call.

You can specify an initial thread scheduling scope by calling pthread_attr_setscope() and passing one of the scope constants (PTHREAD_SCOPE_SYSTEM or PTHREAD_SCOPE_PROCESS) in the pthread_attr_t object. By default, process scope is selected and scheduling is performed by the thread runtime, but thread scheduling by the kernel is provided with the system scope attribute. System scope threads run at real-time policy and priority and may be created only by privileged users.

You can specify an initial thread priority in a struct sched_param object in memory (the structure is declared in sched.h). Set the desired priority in the sched_priority field. Pass the structure to pthread_attr_setschedparam().

You can specify an initial scheduling policy by calling pthread_attr_setschedpolicy(), passing one of the policy constants SCHED_FIFO or SCHED_RR.

The pthread_attr_setinheritsched() function is used to specify, in the attribute object, whether a new thread's scheduling policy and priority should be taken from the attribute object, or whether they should be inherited from the thread that creates the new thread. When you set an attribute object for inheritance, the scheduling policy and priority in the attribute object are ignored.

Scheduling scope, priorities, and policies are described in “Scheduling Pthreads”.

Each pthread has an execution stack area in memory. By default, pthread_create() allocates stack space from dynamic memory, and automatically releases it when the thread terminates.

You use pthread_attr_setstacksize() to specify the size of this stack area. You cannot specify a stack size less than a minimum. A pthread process can find the minimum by calling sysconf() with _SC_THREAD_STACK_MIN (see the sysconf(3C) reference page).

Threads may overrun their stack area. By default, a thread's stack is created with guard protection, and extra memory is allocated at the overflow end of the stack as a buffer. If an application overflows into this buffer, an exception results (a SIGSEGV signal is delivered to the thread).

The guardsize attribute controls the size of the guard area for the created thread's stack and protects against overflow of the stack pointer. The guardsize attribute is set using pthread_attr_setguardsize().

---

Note: Because thread stack space is taken from dynamic memory, the allocation is charged against the process virtual memory limit, not the process stack size limit as you might expect.

---

Call pthread_self() to get the thread ID of the calling thread. A thread can use this thread ID when changing its own scheduling priority, for example (see “Scheduling Pthreads”).

Your program may use static data that should be initialized exactly once. The code can be entered by multiple threads, and might be entered concurrently. How can you ensure that only one thread will perform the initialization?

One answer is to create a variable of type pthread_once_t, statically initialized to the value PTHREAD_ONCE_INIT. Call pthread_once(), passing the addresses of the variable and of an initialization function. The pthreads library ensures that the initialization function is called only once, and that any other threads calling pthread_once() for this variable wait until the first thread completes the initialization function. See Example 13-1.

pthread_once_t first_time_flag = PTHREAD_ONCE_INIT;
elaborate_struct_t uninitialized; /* thing to initialize */
void elaborate_initializer(void); /* function to do it */
int subroutine(...)
{
   ...
   pthread_once(&first_time_flag, elaborate_initializer);
   ...
}

A thread can establish functions that are called when it terminates and when the process forks.

Call pthread_cleanup_push() to register a function that is to be called in the event that the current thread terminates, either by exiting or by cancellation. Call pthread_cleanup_pop() to retract this registration and, optionally, to call the handler. These functions are often used in library code, with the push operation done on entry to the library and the pop done upon exit from the library. The push and pop operations are in fact implemented partly as macro code. For this reason, calls to them must be strictly balanced—a pop for each push—and each push/pop pair must appear in a single C lexical scope. A nonstructured jump such as a longjmp (see the setjmp(3) reference page) or goto can cause unexpected results.

Call pthread_atfork() to register three handlers related to a UNIX fork() call. The first handler executes just before the fork() takes place; the second executes just after the fork() in the parent process; the third executes just after the fork() in the child process.

The fork() operation creates a new process with a copy of the calling process's address space, including any locked mutexes or semaphores. Typically, the new process immediately calls exec() to replace the address space with a new program. When this is the case, there is no need for pthread_atfork() (see the exec(2) and fork(2) reference pages). However, if the new process continues to execute with the inherited address space, including perhaps calls to library code that uses pthreads, it may be necessary for the library code to reinitialize data in the address space of the child process. You can do this in the fork event handlers.

A thread begins execution in the function that is named in the pthread_create() call. When it returns from that function, the thread terminates. A thread can terminate earlier by calling pthread_exit(). In either case, the thread returns a value of type void*.

One thread can request early termination of another by calling pthread_cancel(), passing the thread ID of the target thread. A thread can protect itself against cancellation using two built-in switches:

When you prevent cancellation by setting PTHREAD_CANCEL_DISABLE, a cancellation request is blocked but remains pending until the thread terminates or changes its cancellation state.

The initial cancellation state of a thread is PTHREAD_CANCEL_ENABLE and the type is PTHREAD_CANCEL_DEFERRED. In this state, a cancellation request is blocked until the thread calls a function that is a defined cancellation point. The functions that are cancellation points are listed in the pthread_setcanceltype(3P) reference page. A thread can explicitly permit cancellation by calling pthread_testcancel().

Sometimes you do not care when threads terminate—your program starts a set of threads, and they continue until the entire program terminates.

In other cases, threads are created and terminated as the program runs. One thread can wait for another to terminated by calling pthread_join(), specifying the thread ID. The function does not return until the specified thread terminates. The value the specified thread passed to pthread_exit() is returned. At this time, your program can release any resources that you associate with the thread, for example, stack space (see “Thread Stack Allocation”).

The pthread_join() function also detaches the terminated thread. If your program does not use pthread_join(), you must arrange for terminated threads to be detached in some other way. One way is by specifying automatic detachment when the threads are created (see “Initial Detach State”). Another is to call pthread_detach() at any time after creating the thread, including after it has terminated.

If your program creates threads and lets them terminate, but does not detach them, resources will be used up and eventually an error will occur when trying to create a thread.

Each thread has a signal mask that specifies the signals it is willing to receive (see “Signal Blocking and Signal Masks”). In a program that is linked with the pthreads library, this should be changed using pthread_sigmask(). Each thread inherits the signal mask of the thread that calls pthread_create(). Typically you set an initial mask in the first thread, so that it can be inherited by all other threads.

---

Note: In IRIX, you can use sigprocmask() instead of pthread_sigmask(), but it may not be portable to other systems.

---

When a signal is directed to a specific thread that is blocking the signal, the signal remains pending on the thread until that thread unblocks it. When a signal is directed to a process, it is delivered to the first thread that is not blocking that signal. If all threads block that signal, the signal remains pending on the process until some thread unblocks it or the process terminates.

A thread can find out which signals are pending by calling sigpending(). This function returns a mask showing the set of signals pending on the process as a whole or for the calling thread; that is, the signals that could be delivered to the calling thread if they were not blocked.

When a signal is delivered, some action is taken. You specify what that action should be using the sigaction() function. These actions are set on a process-wide basis, not individually for each thread. Although each thread has a private signal mask, signal actions are shared with all threads in the process. See “Signal Handling Policies” for details.

You can design a program to receive signals in a synchronous manner instead of asynchronously. To do this, set a mask that blocks all the signals that are to be received synchronously. Then call one of the following three functions:

Using these functions you can write a thread that treats signals as a stream of events to be processed. This is generally the safest program model, much easier to work with than the asynchronous model of signal delivery.

The scheduling contention scope of a pthread (see pthread_attr_setscope(3P)) determines the set of threads that it competes against for resources.

System scope threads compete with all other threads on the system and can be created only by privileged users. These threads are used in programs when some form of guaranteed (that is, real-time) response is required. Their scheduling parameters directly affect how the system treats them. In addition to the usual scheduling attributes, they can select a CPU on which to run using the pthread_setrunon_np() call.

Process scope threads compete within the process and their scheduling attributes are used by the pthread library to select which threads to run on a pool of kernel entities. The size of the pool is determined dynamically, but may be influenced using the pthread_setconcurrency() call.

Process scope threads generally require fewer resources than system scope threads because they can share kernel resources. The kernel entities themselves share a common set of scheduling attributes which privileged users can change using the process scheduling interfaces (see sched_setscheduler(2) and sched_setparam(2)). For further details, see the pthreads(5) reference page.

The functions used in scheduling are summarized in Table 13-6 and described in the following sections:

There are two scheduling policies in this implementation: first-in-first-out (SCHED_FIFO) and the default round-robin (SCHED_RR). SCHED_FIFO and SCHED_RR are similar. The round-robin scheduler ensures that after a thread has used a certain maximum amount of time, it is moved to the end of the queue of threads of the same priority, and can be preempted by other threads.

The details of scheduling are discussed in the pthread_attr_setschedpolicy(3P) reference page.

Threads are ordered by priority values, with a small number representing a low priority, and a larger number representing a higher priority. Threads with higher priorities are chosen to execute before threads with lower priorities.

The sched_get_priority_max() and sched_get_priority_min() functions return the highest and lowest priority numbers for a given policy. There are at least 32 priority values and the lowest is greater than or equal to 0.

A thread can set another's priority and scheduling policy, using pthread_setschedparam(). A simple function to set a specified priority on the current thread is shown in Example 13-2.

#include <sched.h> /* struct sched_param */
void setMyPriority(int newP)
{
   pthread_t myTid = pthread_self();
   int policy;
   struct sched_param sp;
   (void) pthread_getschedparam(myTID,&policy,&sp);
   sp.sched_priority = newP;
   (void) pthread_setschedparam(myTID,policy,&sp);
}  

A mutex is a software object that arbitrates the right to modify some shared variable, or the right to execute a critical section of code. A mutex can be owned by only one thread at a time; other threads trying to acquire it wait. Mutexes are intended to be lightweight and owned only for a short time.

Preparing Mutex Objects

When a thread wants to modify a variable that it shares with other threads, or execute a critical section, the thread claims the associated mutex. This can cause the thread to wait until it can acquire the mutex. When the thread has finished using the shared variable or critical code, it releases the mutex. If two or more threads claim the mutex at once, one acquires the mutex and continues, while the others are blocked until the mutex is released.

A mutex has attributes that control its behavior. The pthreads library contains several functions used to prepare a mutex for use. These functions are summarized in Table 13-7.

Table 13-7. Functions for Preparing Mutex Objects

Function	Purpose
pthread_mutexattr_init(3P)	Initialize a pthread_mutexattr_t with default attributes.
pthread_mutexattr_destroy(3P)	Uninitialize a pthread_mutexattr_t.
pthread_mutexattr_getprotocol(3P)	Query the priority protocol.
pthread_mutexattr_setprotocol(3P)	Set the priority protocol choice.
pthread_mutexattr_getprioceiling(3P)	Query the minimum priority.
pthread_mutexattr_setprioceiling(3P)	Set the minimum priority.
pthread_mutexattr_getpshared(3P)	Query the process-shared attribute.
pthread_mutexattr_setpshared(3P)	Set the process-shared attribute.
pthread_mutexattr_gettype(3P)	Get the mutex type.
pthread_mutexattr_settype(3P)	Set the mutex type.
pthread_mutex_init(3P)	Initialize a mutex object.
pthread_mutex_destroy(3P)	Uninitialize a mutex object.

A mutex must be initialized before use. You can do this in one of three ways:

• Static assignment of the constant PTHREAD_MUTEX_INITIALIZER.

• Calling pthread_mutex_init() passing NULL instead of the address of a mutex attribute object.

• Calling pthread_mutex_init() passing a pthread_mutexattr_t object that you have set up with attribute values.

The first two methods initialize the mutex to default attributes.

Four attributes can be set in a pthread_mutexattr_t. You can set the priority inheritance protocol using pthread_mutexattr_setprotocol() to one of three values:

PTHREAD_PRIO_NONE	The mutex has no effect on the thread that acquires it. This is the default.
PTHREAD_PRIO_PROTECT	The thread holding the mutex runs at a priority at least as high as the highest priority of any mutex that it currently holds.
PTHREAD_PRIO_INHERIT	The thread holding the mutex runs at a priority at least as high as the highest priority of any thread blocked on that mutex.

If a thread acquires a mutex and then is suspended (for example, because its time slice is up), other threads can be blocked waiting for the mutex. The PTHREAD_PRIO_PROTECT protocol prevents this. Using pthread_mutexattr_setprioceiling(), you set a priority higher than normal for the mutex. A thread that acquires the mutex runs at this higher priority while it holds the mutex.

Another problem is that when a low-priority thread has acquired a mutex, and a thread with higher priority claims the mutex and is blocked, a “priority inversion” takes place—a higher-priority thread is forced to wait for one of lower priority. The PTHREAD_PRIO_INHERIT protocol prevents this—when a thread of higher priority blocks, the thread holding the mutex has its priority boosted during the time it holds the mutex.

---

Tip: PTHREAD_PRIO_NONE uses a faster code path than the other two priority options for mutexes.

---

By default, only threads within a process share a mutex. Using pthread_mutexattr_setpshared(), you can allow any thread (from any process) with access to the mutex memory location to use the mutex. Enable mutex sharing by changing the default PTHREAD_PROCESS_PRIVATE attribute to PTHREAD_PROCESS_SHARED.

---

Note: The PTHREAD_PRIO_INHERIT attribute is not available with pthread_mutexattr_setpshared().

---

By default, no error checking is performed on threads that attempt to use a mutex. For example, a thread that attempts to lock a mutex that it already owns deadlocks. Using pthread_mutexattr_settype() with PTHREAD_MUTEX_ERRORCHECK allows you to have the lock call return an error instead. If recursive mutexes are required, PTHREAD_MUTEX_RECURSIVE enables recursive mutexes.

A condition variable provides a way in which a thread can wait for an event (or condition) defined by the program, to be satisfied. Condition variables use mutexes to synchronize the wait and wakeup operations.

#include <assert.h>
#include <pthread.h>
typedef int listKey_t;
typedef struct element_s { /* list element */
   listKey_t key;
   struct element_s *next;
   int busyFlag;
   pthread_cond_t notBusy; /* event of no-longer-in-use */
} element_t;
typedef struct listHead_s { /* list head and mutex */
   pthread_mutex_t mutList; /* right to modify the list */
   element_t *head;
} listHead_t;
/*
|| Internal function to find an element in a list, returning NULL
|| if the key is not in the list.
|| A returned element could be in use by another thread (busy).
|| The caller is assumed to hold the list mutex, otherwise
|| the returned value could be made invalid at any time.
*/
static element_t *scanList(listHead_t* lp, listKey_t key)
{
   element_t *ep;
   for (ep=lp->head; (ep) ; ep=ep->next)
   {
      if (ep->key == key) break;
   }
   return ep;
}
/*
|| Public function to find a key in a list, wait until the element
|| is no longer busy, mark it busy, and return it.
*/
element_t *getFromList(listHead_t* lp, listKey_t key)
{
   element_t *ep;
   pthread_mutex_lock(&lp->mutList); /* lock list against changes */
   while ((ep=scanList(lp,key)) && (ep->busyFlag))
   {
      pthread_cond_wait(&ep->notBusy, &lp->mutList); /* (A) */
   }
   if (ep) ep->busyFlag = 1;
   pthread_mutex_unlock(&lp->mutList);
   return ep;
}
/*
|| Public function to release an element returned by getFromList().
*/
void freeInList(listHead_t* lp, element_t *ep)
{
   assert(ep->busyFlag);
   pthread_mutex_lock(&lp->mutList); /* lock list to prevent races */
   ep->busyFlag = 0;
   pthread_cond_signal(&ep->notBusy);
   pthread_mutex_unlock(&lp->mutList);
}
/*
|| Public function to delete a list element returned by getFromList().
*/
void deleteInList(listHead_t* lp, element_t *ep)
{
   element_t **epp;
   assert(ep->busyFlag);
   pthread_mutex_lock(&lp->mutList);
   for (epp = &lp->head; ep != *epp; epp = &((*epp)->next))
   { /* finding anchor of *ep in list */ }
   *epp = ep->next; /* remove *ep from list */
   ep->busyFlag = 0;
   pthread_cond_broadcast(&ep->notBusy);
   pthread_mutex_unlock(&lp->mutList);
   pthread_cond_destroy(&ep->notBusy);
   free(ep);
}

A read-write lock is a software object that gives one thread the right to modify some data, or multiple threads the right to read that data. A read-write lock can be owned for write or for read. If acquired for write, only one thread can own it and other threads must wait. If acquired for read, other threads wishing to acquire it for write must wait, but multiple readers can own the lock at the same time.