C THREADS Eric C. Cooper Richard P. Draves Department of Computer Science Carnegie Mellon University Pittsburgh, Pennsylvania 15213 Draft of 11 September 1990 ABSTRACTThe C Threads package allows parallel programming in C under the MACH operatingsystem. The package provides multiple threads of control for parallelism,shared variables, mutual exclusion for critical sections, and conditionvariables for synchronization of threads.This research was sponsored by the Defense Advanced Research Projects Agency(DoD), ARPA order 4864, monitored by the Space and Naval Warfare SystemsCommand under contract N00039-84-C-0467.The views and conclusions contained in this document are those of the authorsand should not be interpreted as representing official policies, eitherexpressed or implied, of the Defense Advanced Research Projects Agency or ofthe U.S. Government.1. IntroductionMACH provides a set of low-level, language-independent primitives formanipulating threads of control [3]. The C Threads package is a run-timelibrary that provides a C language interface to these facilities [1]. Theconstructs provided are similar to those found in Mesa [4] and Modula-2+ [5]:forking and joining of threads, protection of critical regions with mutexvariables, and synchronization by means of condition variables.2. Naming ConventionsAn attempt has been made to use a consistent style of naming for theabstractions implemented by the C Threads package. All types, macros, andfunctions implementing a given abstract data type are prefixed with the typename and an underscore. The name of the type itself is suffixed with _t and isdefined via a C typedef. Documentation of the form typedef struct mutex {...} *mutex_t;indicates that the mutex_t type is defined as a pointer to a referent typestruct mutex which may itself be useful to the programmer. (In cases where thereferent type should be considered opaque, documentation such as typedef ... cthread_t;is used instead.)Continuing the example of the mutex_t type, the functions mutex_alloc() andmutex_free() provide dynamic storage allocation and deallocation. Thefunctions mutex_init() and mutex_clear() provide initialization andfinalization of the referent type. These functions are useful if theprogrammer wishes to include the referent type itself (rather than a pointer)in a larger structure, for more efficient storage allocation. They should notbe called on objects that are dynamically allocated via mutex_alloc().Type-specific functions such as mutex_lock() and mutex_unlock() are alsodefined, of course.3. Initializing the C Threads Package3.1. cthreads.h #include <cthreads.h>The header file cthreads.h defines the C threads interface. All programs usingC threads must include this file.3.2. cthread_init void cthread_init()The cthread_init() procedure initializes the C threads implementation. Aprogram using C threads must explicitly call cthread_init() (typically frommain()) before using any of the other functions described below. Multiplecalls to cthread_init() are harmless.4. Threads of Control4.1. CreationWhen a C program starts, it contains a single thread of control, the oneexecuting main(). The thread of control is an active entity, moving fromstatement to statement, calling and returning from procedures. New threads arecreated by fork operations.Forking a new thread of control is similar to calling a procedure, except thatthe caller does not wait for the procedure to return. Instead, the callercontinues to execute in parallel with the execution of the procedure in thenewly forked thread. At some later time, the caller may rendez-vous with thethread and retrieve its result (if any) by means of a join operation, or thecaller may detach the newly created thread to assert that no thread will everbe interested in joining it.4.2. TerminationA thread t terminates when it returns from the top-level procedure it wasexecuting.[Currently, this is not true of the initial thread executing main().Instead, an implicit call to exit() occurs when main() returns, terminating theentire program. If the programmer wishes detached threads to continueexecuting, the final statement of main() should be a call to cthread_exit().]If t has not been detached, it remains in limbo until another thread eitherjoins it or detaches it; if t has been detached, no rendez-vous is necessary.4.3. cthread_fork typedef ... any_t; typedef ... cthread_t;The any_t type represents a pointer to any C type. The cthread_t type is aninteger-size ``handle'' that uniquely identifies a thread of control. Valuesof type cthread_t will be referred to as thread identifiers. cthread_t cthread_fork(func, arg) any_t (*func)(); any_t arg;The cthread_fork() procedure creates a new thread of control in which func(arg)is executed concurrently with the caller's thread. This is the sole means ofcreating new threads. Arguments larger than a pointer must be passed byreference. Similarly, multiple arguments must be simulated by passing apointer to a structure containing several components. The call tocthread_fork() returns a thread identifier that can be passed to cthread_join()or cthread_detach() (see below). Every thread must be either joined ordetached exactly once.4.4. cthread_exit void cthread_exit(result) any_t result;This procedure causes termination of the calling thread. An implicitcthread_exit() occurs when the top-level function of a thread returns, but itmay also be called explicitly. The result will be passed to the thread thatjoins the caller, or discarded if the caller is detached.4.5. cthread_join any_t cthread_join(t) cthread_t t;This function suspends the caller until the specified thread t terminates viacthread_exit(). (It follows that attempting to join one's own thread willresult in deadlock.) The caller receives either the result of t's top-levelfunction or the argument with which t explicitly called