NAME
Thread_init, Thread_new, Thread_exit, Thread_join, Thread_self - thread primitives
SYNOPSIS
#include "thread.h"
void Thread_init(void);
int Thread_new(int func(void *), void *args, size_t nbytes, ...); void Thread_exit(int code);
int Thread_join(int tid);
int Thread_self(void);
void Thread_pause(void);
DESCRIPTION
These functions implement a structured multiprogramming facility. A `thread' is a separate locus of control in a program; any number of threads can be executing concurrently, at least conceptually. The functions in this interface manage threads: Thread_init initializes the thread system, Thread_new and Thread_exit create and destroy threads, and Thread_join waits for threads to terminate. Threads can use channels (see chan(3)) and semaphores (see sem(3)) to communicate and synchronize with each other.
Thread_init
initializes the thread systems. When a program begins execution, it usually starts by calling Thread_init; thus the program's main function usually has the form
int main(int argc, char *argv[]) { ...declarations...
Thread_init();
...
Thread_exit(0);
}
As this code template suggests, threads must terminate by calling Thread_exit.
Thread_new
creates a new thread and returns its `thread id,' which is a positive integer. Thread ids are passed to Thread_join and returned by Thread_self. When the thread begins execution, it calls func with a pointer to a copy of the data pointed to by args, which is presumed to point to nbytes of argument data for the new thread. Thread_new copies these data to a buffer that's private to the new thread and calls func with a pointer to this buffer. args is usually the address of a structure and nbytes is the size of that structure.
Thread_new may take additional system-specific arguments. For example, some implementations accept additional arguments that name system-specific parameters followed by system-specific values; an example is
Thread_new(func, args, nbytes, "priority", 2, NULL);
which specifies a thread priority. As this example suggests, the argument list to Thread_new must be terminated with NULL.
The new thread runs independently of the thread that created it. If func returns, the thread is terminated as if it called Thread_exit(func(...)); Thread_exit is described below. Thread creation is synchronous: Thread_new returns after the new thread has been created and has received its argument, but perhaps before the new thread begins execution.
Thread_new returns -1 if it cannot create the new thread. It is a checked runtime error for func to be NULL, for for args to be NULL and nbytes to be negative.
Thread_exit
terminates execution of the calling thread. Threads waiting for the termination of the calling thread (by virtue of Thread_join) are resumed and the value of code is returned as the result of calling Thread_join in each of the resumed threads. When the last thread calls Thread_exit, the entire program terminates by calling exit(code).
Thread_join
causes the calling thread to suspend execution until thread tid terminates by calling Thread_exit. When thread tid terminates, the calling thread is resumed and Thread_join returns the integer that was passed to Thread_exit by the terminated thread. If tid names a non-existent thread, Thread_join returns -1 immmediately. As a special case, the call Thread_join(0) waits for all threads to terminate, including those that might be created by other threads. In this case, Thread_join returns 0. It is a checked runtime error for a non-zero tid to name the calling thread, or for more than one thread to specify a 0 tid.
Thread_self
returns the thread id of the calling thread.
Thread_pause
causes the calling thread to relinquish the processor to another thread that's ready to run, if there is one.
DIAGNOSTICS
Checked runtime errors are implemented with assertions; see assert(3).
BUGS
It is an unchecked runtime error to call any of the thread primitives before calling Thread_init.
Threads that terminate with exit(2) or its variants instead of Thread_exit may kill all threads, or may cause the rest of the threads to spin indefinitely.