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

Prior to the inclusion of stdio.h, be sure that the compiler variables _POSIX1C and _NO_ANSIMODE are defined. These variables are set by default in most compiles. Read the header file /usr/include/standards.h (which is included by stdio.h) to see the logic of standard namespace definition.

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. (However, you must be sure that the needed version of the library is installed; the -n32 and -64 libraries do not install by default.)

---

Note: The definition of a threaded program or pthread program is: a program that links with libpthread. Do not link with libpthread unless you intend to use the pthread interface, since libpthread replaces many standard library functions.

---

---

Tip: Many names in libpthread override names defined in libc. The linker displays warning messages about these overrides. You can silence the warnings with the -Wl,-woff,85 compile option.

---

The debugging and performance tuning tools distributed with IRIX and the IRIX developer's option can sometimes be used with a threaded program.

(dbx) showthread all
Thread: Start:               State:     Pid:  Location:
0x10000                      COND-WAIT       _SGIPT_sched_block ["xp.c":966]
0x10001 work_thread          RUNNING     1512 FLOCAL_ALIGN ["workfn.c":864]
0x10002 work_thread          RUNNING     1520 FLOCAL_ALIGN ["workfn.c":850]
0x10003 work_thread          RUNNING     1563 FLOCAL_ALIGN ["workfn.c":866]
0x10004>work_thread          RUNNING     1425 thr_tst ["workfn.c":391]

After a thread has terminated, it can be “detached.” Detaching means that the pthreads library deletes its information about the thread, possibly releasing some memory (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 detached by an explicit function call.

Scheduling priorities and policies are described under “Scheduling Pthreads”. You can specify an initial scheduling policy by calling pthread_attr_setschedpolicy(), passing one of the policy constants SCHED_FIFO, SCHED_RR, or SCHED_OTHER.

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().

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 these things 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.

Each pthread has an execution stack area in memory. By default, pthread_create() allocates stack space of the specified size from dynamic memory. When it does so, the stack space is automatically released when the thread is detached.

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

Preallocating Stack Areas

You can instead preallocate stack space from any source of dynamic memory such as malloc(). When you preallocate stack space, you must do the following:

• Specify the address of the space using pthread_attr_setstackaddr().

  This tells pthread_create() not to allocate space.

• Specify the size of the allocated space using pthread_attr_setstacksize().

  This enables pthread_create() to initialize the correct starting stack address.

• Free the stack space when the thread terminates (see “Joining and Detaching”).

There is normally no protection against a thread overrunning the space. If a thread allocates too much automatic data or makes too many nested function calls, it will attempt to modify memory outside the stack space. This might cause a segmentation fault if that memory is not allocated, or it might modify memory used for other purposes.

---

Tip: When you preallocate stack space, you can create “red zones” around the allocated stacks as follows:

---

• Allocate the stack memory in multiples of the system page size aligned on page boundaries (see the getpagesize(2) and memalign(3C) reference pages).

• Allocate an extra page of memory above and below each stack area.

• Use the mprotect() function to set the protection of the extra pages to PROT_NONE (see the mprotect(2) reference page).

This procedure creates untouchable pages at each end of the stack area. If the thread misuses its stack, it will usually terminate at once with a segmentation fault. (It is still possible for a thread to call a function that allocates more than a page of automatic variables, and so skips over the “red zone” to modify memory beyond it.)

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, but only 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?

The answer is to create a variable of type pthread_once_t, statically initialized to the value PTHREAD_ONCE_INIT. In the module code, 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 call. An example is shown in Example 11-2.

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 threads terminate 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 status 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 state of a thread is PTHREAD_CANCEL_ENABLE and 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 find out when another has 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 detaches the terminated thread. If your program does not use pthread_join(), and does continue execution after threads have terminated, 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 continues for a long time creating threads and letting them terminate, but does not arrange for detaching the completed threads, eventually an error will occur because resources have been used up.

A thread specifies which signals it is willing to receive (see “Signal Blocking and Signal Masks” in Chapter 5). In a program that is linked with the pthreads library this must be done 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.

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

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

When a signal is not blocked and is delivered, some action is taken. You specify what that action should be using the sigaction() function. Specify an action for each signal number separately. These actions are set on a process-wide basis, not individually for each thread. Each thread has a private signal mask, but signal actions are specified for all threads in the process. Choose among the following actions for each signal:

When a signal is delivered to a function, you have the option of specifying a function that receives a siginfo_t structure with information about the signal. These and other options are spelled out under “Signal Handling Policies” in Chapter 5.

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 arriving 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.

There are two scheduling policies in this implementation: first-in-first-out (SCHED_FIFO) and round-robin (SCHED_RR). (The default SCHED_OTHER behaves the same as SCHED_RR.) SCHED_FIFO and SCHED_RR are similar. The round-robin scheduler ensures that when a thread has used a certain maximum amount of time without blocking, 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(3) reference page.

The queues of runnable threads are ordered by thread priority numbers, 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. There are at least 32 priority values and the lowest is greater than or equal to 0. You can use these functions to set up a system of relative priorities as suggested by the code in Example 11-4.

#include <sched.h>
int higherP, mediumP, lowerP;
void setRelativePriorities()
{
   int maxP, minP;
   maxP = sched_get_priority_max();
   minP = sched_get_priority_min();
   mediumP = minP + ((maxP-minP)/2);
   higherP = mediumP+1;
   lowerP = mediumP-1;
}

When all threads use one of the three priorities higherP, mediumP, or lowerP, threads that run at higherP will always run in preference to threads at the other two priorities.

---

Note: There are system functions named sched_get_priority_max() and sched_get_priority_min(); they are documented in “Controlling Scheduling With POSIX Functions” in Chapter 10 and the sched_get_priority_max(2) reference page. However, when you link with libpthread, these names are defined in the pthread library and access the pthread priority values.

---

A thread can set another's priority or scheduling policy, or both, using pthread_setschedparam(). A simple function to set a specified priority on the current thread, returning the previous value, is shown in Example 11-5.

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

A mutex is a software object that stands for 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.

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 11-7.

Table 11-7. Functions for Preparing Mutex Objects

Function	Purpose
pthread_mutex_init(3P)	Initialize a mutex object based on a pthread_mutexattr_t.
pthread_mutex_destroy(3P)	Uninitialize a mutex object.
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 in a pthread_mutexattr_t.
pthread_mutexattr_setprotocol(3P)	Set the priority protocol choice in a pthread_mutexattr_t.
pthread_mutexattr_getprioceiling(3P)	Query the minimum priority in a pthread_mutexattr_t.
pthread_mutexattr_setprioceiling(3P)	Set the minimum priority in a pthread_mutexattr_t.

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. Dynamic initialization should be done only once (see “Initializing Static Data”).

Two attributes can be set in a pthread_mutexattr_t. The priority inheritance protocol is the more important. 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.
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.

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.

When round-robin scheduling is used, and a mutex represents a critical section of code, a second problem can arise. If a thread acquires the mutex, enters the critical section, and then is suspended because its time slice is up, other threads can be blocked needlessly 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. This keeps it at the front of the round-robin queue until it exits the critical section and releases the mutex.

---

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

---

A condition variable provides a way in which a thread can temporarily give up ownership of a mutex, wait for a condition to be true, and then reclaim ownership of the mutex, all in a single operation.

#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);
}