Pthread API list

POSIX pthreads

Note: It is assumed that you have a good understanding of the C programming language. If you do not or need to brush up, please review basic C (including pointers and dynamic memory allocation). Here are some resources.

Now that we have a good foundation of thread concepts, lets talk about a particular thread library, POSIX pthreads. The pthread library can be found on almost any modern OS.

A few preliminary steps you should take before beginning any pthread coding is to:

1. add #include <pthread.h> in your .c or .h header file(s)
2. define the #define _REENTRANT macro somewhere in a common .h or .c file
3. In your Makefile make sure gcc links against -lpthread
4. Optional: add -D_POSIX_PTHREAD_SEMANTICS to your Makefile (gcc flag) for certain function calls like sigwait()

Pthread Basics

Now let's begin our journey into pthreads...

A thread is represented by the type pthread_t. Let's begin by examining most of the pthread creation and initializing functions:

int pthread_create(pthread_t *thread, pthread_attr_t *attr, 
                   void *(*start_routine)(void *), void *arg);

int pthread_attr_init(pthread_attr_t *attr);

int pthread_mutex_init(pthread_mutex_t *mutex, 
                       const pthread_mutexattr_t *mutexattr);

int pthread_cond_init(pthread_cond_t *cond, 
                      pthread_condattr_t *cond_attr);

pthread_create() example:

pthread_create(&pt_worker, &thread_attributes, 
               thread_function, (void *)thread_args);

The above will create a pthread pt_worker with thread attributes defined in thread_attributes (this argument can be NULL if you want default thread attributes). The thread code is contained in the function thread_function and is passed in a arguments stored in thread_args. The thread_function prototype would look like this:

void *thread_function(void *args);

Immediately after the pthread_create call completes, the thread_function will begin executing.

pthread_XXXX_init() functions initialize thread attributes, mutexes, and condition variables. mutexattr and cond_attr can be NULL if you are using defaults. Mutexes and condition variables can be initialized to default values using the INITIALIZER macros as well. For example:

pthread_mutex_t count_lock = PTHREAD_MUTEX_INITIALIZER;
pthread_cond_t count_cond = PTHREAD_COND_INITIALIZER;

Pthread Mutexes

To perform locks and unlocks the following functions are available for you:

int pthread_mutex_lock(pthread_mutex_t *mutex);

int pthread_mutex_trylock(pthread_mutex_t *mutex);

int pthread_mutex_unlock(pthread_mutex_t *mutex);

pthread_mutex_lock() is a blocking call. If the thread cannot gain the lock, then the thread will block the thread from proceeding until it obtains the lock. pthread_mutex_trylock() will return immediately if the mutex cannot be locked. To unlock a mutex, simply call pthread_mutex_unlock(). An example on using Pthread mutexes:

pthread_mutex_lock(&count_lock);
  count++;
pthread_mutex_unlock(&count_lock);

In the above example, we are incrementing the globally shared count variable. The code between the lock and unlock calls is the critical section. Always try to minimize this section!

Pthread Condition Variables

Here are the pthread condition variable function prototypes:

int pthread_cond_wait(pthread_cond_t *cond,
                      pthread_mutex_t *mutex);

int pthread_cond_signal(pthread_cond_t *cond);

int pthread_cond_broadcast(pthread_cond_t *cond);

pthread_cond_wait() puts the current thread to sleep. It requires a mutex of the associated shared resource value it is waiting on. pthread_cond_signal() signals one thread out of the possibly many sleeping threads to wakeup. pthread_cond_broadcast() signals all threads waiting on the cond condition variable to wakeup. Here is an example on using pthread condition variables:

pthread_mutex_lock(&count_lock);
  while (count < MAX_COUNT) {
    pthread_cond_wait(&count_cond, &count_lock);
  }
pthread_mutex_unlock(&count_lock);

We are locking the count_lock mutex so we can read the value of count without entering a potential race condition. Notice how the we use a while loop instead of an if statement. This is because of spurious wakeups problem previously mentioned. Just because a thread has been woken does not mean it was due to a pthread_cond_signal() or pthread_cond_broadcast() call. The pthread_cond_wait() call takes the count mutex and condition variable. Why does pthread_cond_wait() require the mutex as well as the conditon variable? It's because it needs to unlock the mutex when going to sleep or you would potentially enter into a deadlock! pthread_cond_wait() if awoken, automatically tries to reacquire the mutex, and will block if it cannot. Using the signal and broadcast functions is self-explanatory. It is recommended that you release any locks that other threads could be waiting on before you signal or broadcast.

Miscellaneous

Here are some suggestions and issues you should consider when creating using pthreads:

• One thing we have been disregarding in the above discussions is return values. You must check all return values! No exceptions!
• Sometimes it is desirable for a thread not to terminate (as in the case of the worker thread pool). This can be solved by placing the thread code in an infinite loop and using condition variables.
• Many of the pthread types can be "free'd" using the pthread_XXXX_destroy() calls.
• pthread_join() can be used to wait on other threads to finish (if the JOINABLE attribute is set). This is useful in creating barriers or other synchronization windows/points.
• To set thread attributes, use the pthread_attr_setXXXX() functions. scope, schedpolicy, and detachstate are only some of the useful attributes you can set on your threads.
• pthread_kill() can be used to deliver signals to specific threads.
• pthread_self() returns a handle on the calling thread.
• pthread_once() can be used to ensure that an initializing function within a thread is only run once.
• There are many, many more useful functions in the pthread library. Consult your man pages or the Nichols text (Appendix C).