C Threads Functions

The C Threads package is a run-time library that provides a 
C language interface to the low-level, language-independent 
primitives for manipulating threads of control.  If you intend 
to do multi-threaded applications, you should use the C 
threads routines rather than the Mach system calls.



condition_alloc(), mutex_alloc()

SUMMARY	
Allocate a condition variable or mutex
SYNOPSIS
#include <cthreads.h>

condition_t condition_alloc()
mutex_t mutex_alloc()

DESCRIPTION
The functions condition_alloc() and mutex_alloc() provide 
dynamic allocation of mutex and condition objects.



condition_broadcast()

SUMMARY	
Broadcast a condition
SYNOPSIS
#include <cthreads.h>

void condition_broadcast(condition_t€c)

DESCRIPTION
The function condition_broadcast() is similar to 
condition_signal(), except that it awakens all threads waiting 
for the condition, not just one of them.



condition_clear(), mutex_clear()

SUMMARY	
Clear a condition variable or mutex
SYNOPSIS
#include <cthreads.h>

void condition_clear(struct condition€*c)
void mutex_clear(struct mutex€*m)

DESCRIPTION
The functions condition_clear() and mutex_clear() let you 
finalize an object of the struct condition or struct mutex 
referent type.  For example, the mutex_free() function could 
be written in terms of mutex_clear() as follows:

void mutex_free(m) 
	mutex_t m; 
{
	mutex_clear(m); 
	free((char *) m);
}



condition_free(), mutex_free()

SUMMARY	
Deallocate a condition variable or mutex
SYNOPSIS
#include <cthreads.h>

void condition_free(condition_t€c)
void mutex_free(mutex_t€m)

DESCRIPTION
The functions condition_free() and mutex_free() let you 
deallocate condition and mutex objects that were allocated 
dynamically.  Before deallocating such an object, you must 
guarantee that no other thread will reference it.  In particular, 
a thread blocked in mutex_lock() or condition_wait() 
should be viewed as referencing the object continually, so 
freeing the object ªout from underº such a thread is 
erroneous, and can result in bugs that are extremely difficult 
to track down.



condition_init(), mutex_init()

SUMMARY	
Initialize a condition variable or mutex
SYNOPSIS
#include <cthreads.h>

void condition_init(struct condition€*c)
void mutex_init(struct mutex€*m)

DESCRIPTION
The functions condition_init() and mutex_init() initialize an 
object of the struct condition or struct mutex referent type, 
so that its address can be used wherever an object of type 
condition_t or mutex_t is expected.  For example, the 
mutex_alloc() function could be written in terms of 
mutex_init() as follows:

mutex_t 
mutex_alloc() 
{
	register mutex_t m;

	m = (mutex_t) 
malloc(sizeof(struct mutex)); 
	mutex_init(m); 
	return m; 
}

Initialization of the referent type is most often used when you 
have included the referent type itself (rather than a pointer) in 
a larger structure, for more efficient storage allocation.

For instance, a data structure might contain a component of 
type struct mutex to allow each instance of that structure to 
be locked independently.  During initialization of the 
instance, you would call mutex_init() on the struct mutex 
component.  The alternative of using a mutex_t component 
and initializing it using mutex_alloc() would be less 
efficient.



condition_name(), condition_set_name(), 
mutex_name(), mutex_set_name()

SUMMARY	
Associate a name with a condition variable or mutex
SYNOPSIS
#include <cthreads.h>

void condition_set_name(condition_t€c, string_t€name)
string_t condition_name(condition_t€c)
string_t mutex_name(mutex_t€m)
void mutex_set_name(mutex_t€m, string_t€name)

DESCRIPTION
These functions let you associate a name with a condition or 
a mutex.  The name is used when trace information is 
displayed.  The name may also be used for application-
specific RETURN.



condition_set_name() ® See condition_name()



condition_signal()

SUMMARY	
Signal a condition
SYNOPSIS
#include <cthreads.h>

void condition_signal(condition_t€c)

DESCRIPTION
The function condition_signal() should be called when one 
thread needs to indicate that the condition represented by the 
condition variable is now true.  If any other threads are 
waiting (via condition_wait()), at least one of them will be 
awakened.  If no threads are waiting, nothing happens.



condition_wait()

SUMMARY	
Wait on a condition
SYNOPSIS
#include <cthreads.h>

void condition_wait(condition_t€c, mutex_t€m)

DESCRIPTION
The function condition_wait() unlocks the mutex it takes as 
a parameter, suspends the calling thread until the specified 
condition is likely to be true, and locks the mutex again when 
the thread resumes.  There's no guarantee that the condition 
will be true when the thread resumes, so this function should 
always be used as follows:

mutex_t m; 
condition_t c;

mutex_lock(m); 
...
while	(/* condition isn't true */) 
		condition_wait(c, m); 
...
mutex_unlock(m);



cthread_data(), cthread_set_data()

SUMMARY	
Associate data with a thread
SYNOPSIS
#include <cthreads.h>

any_t cthread_data(cthread_t€t)
void cthread_set_data(cthread_t€t, any_t€data)

DESCRIPTION
The functions cthread_data() and cthread_set_data() let 
you associate arbitrary data with a thread, providing a simple 
form of thread-specific ªglobalº variable.  More elaborate 
mechanisms, such as per-thread property lists or hash tables, 
can then be built with these functions.



cthread_detach()

SUMMARY	
Detach a thread
SYNOPSIS
#include <cthreads.h>

void cthread_detach(cthread_t€t)

DESCRIPTION
The function cthread_detach() is used to indicate that the 
given thread will never be joined.  This is usually known at 
the time the thread is forked, so the most efficient usage is 
the following:

	cthread_detach(cthread_fork(function, 
argument));

A thread may, however, be detached at any time after it's 
forked, as long as no other attempt is made to join it or 
detach it.



cthread_exit()

SUMMARY	
Exit a thread
SYNOPSIS
#include <cthreads.h>

void cthread_exit(any_t€result)

DESCRIPTION
The function cthread_exit() terminates the calling thread.  
The result is passed to the thread that joins the caller, or is 
discarded if the caller is detached.

An implicit cthread_exit() occurs when the top-level 
function of a thread returns, but it may also be called 
explicitly.

EXAMPLE
cthread_exit(0);



cthread_fork()

SUMMARY	
Fork a thread
SYNOPSIS
#include <cthreads.h>

cthread_t cthread_fork(any_t€(*function)(), any_t€arg)

DESCRIPTION
The function cthread_fork() takes two parameters:  a 
function for the new thread to execute, and a parameter to 
this function.  cthread_fork creates a new thread of control 
in which the specified function is executed concurrently with 
the caller's thread.  This is the sole means of creating new 
threads.

The any_t type represents a pointer to any C type.  The 
cthread_t type is an integer-size handle that uniquely 
identifies a thread of control.  Values of type cthread_t will 
be referred to as thread identifiers.  Arguments larger than a 
pointer must be passed by reference.  Similarly, multiple 
arguments must be simulated by passing a pointer to a 
structure containing several components.  The call to 
cthread_fork() returns a thread identifier that can be passed 
to cthread_join() or cthread_detach() (see below).  Every 
thread must be either joined or detached exactly once.

EXAMPLE
cthread_detach(cthread_fork(slave, random() 
% 1000));



cthread_join()

SUMMARY	
Join threads
SYNOPSIS
#include <cthreads.h>

any_t cthread_join(cthread_t€t)

DESCRIPTION
The function cthread_join() suspends the caller until the 
specified thread t terminates via cthread_exit().  The caller 
receives either the result of t's top-level function or the 
argument with which t explicitly called cthread_exit().

Attempting to join one's own thread results in deadlock.



cthread_name(), cthread_set_name()

SUMMARY	
Associate a name with a thread
SYNOPSIS
#include <cthreads.h>

string_t cthread_name(cthread_t€t)
void cthread_set_name(cthread_t€t, string_t€name)

DESCRIPTION
The functions cthread_name() and cthread_set_name() let 
you associate an arbitrary name with a thread.  The name is 
used when trace information is displayed.  The name may 
also be used for application-specific diagnostics.



cthread_self()

SUMMARY	
Return the caller's thread identifier
SYNOPSIS
#include <cthreads.h>

cthread_t cthread_self()

DESCRIPTION
The function cthread_self() returns the caller's own thread 
identifier, which is the same value that was returned by 
cthread_fork() to the creator of the thread.  The thread 
identifier uniquely identifies the thread, and hence may be 
used as a key in data structures that associate user data with 
individual threads.  Since thread identifiers may be reused by 
the underlying implementation, you should be careful to 
clean up such associations when threads exit.



cthread_set_data() ® See cthread_data()

cthread_set_name() ® See cthread_name()



cthread_thread()

SUMMARY	
Return the caller's thread identifier
SYNOPSIS
#include <cthreads.h>

thread_t cthread_thread(cthread_t€t)

DESCRIPTION
The function cthread_thread() returns the Mach thread that 
corresponds to the specified thread t.



cthread_yield()

SUMMARY	
Yield the processor to other threads
SYNOPSIS
#include <cthreads.h>

void cthread_yield()

DESCRIPTION
The function cthread_yield() is a hint to the scheduler, 
suggesting that this would be a convenient point to schedule 
another thread to run on the current processor.

EXAMPLE
int i, n;

/* n is set previously */ 
for (i = 0; i < n; i += 1) 
	cthread_yield();



mutex_alloc() ® See condition_alloc()

mutex_clear() ® See condition_clear()

mutex_free() ® See condition_free()

mutex_init() ® See condition_init()



mutex_lock()

SUMMARY	
Lock a mutex variable
SYNOPSIS
#include <cthreads.h>

void mutex_lock(mutex_t€m)

DESCRIPTION
The function mutex_lock() attempts to lock the mutex m and 
blocks until it succeeds.  If several threads attempt to lock the 
same mutex concurrently, one will succeed, and the others 
will block until m is unlocked.  A deadlock occurs if a thread 
attempts to lock a mutex it has already locked.



mutex_name() ® See condition_name()

mutex_set_name() ® See condition_name()



mutex_try_lock()

SUMMARY	
Try to lock a mutex variable
SYNOPSIS
#include <cthreads.h>

int mutex_try_lock(mutex_t€m)

DESCRIPTION
The function mutex_try_lock() attempts to lock the mutex 
m, like mutex_lock(), and returns true if it succeeds.  If m is 
already locked, however, mutex_try_lock() immediately 
returns false rather than blocking.  For example, a busy-
waiting version of the mutex_lock() function could be 
written using mutex_try_lock():

void 
mutex_lock(mutex_t m) 
{
	for (;;) 
		if (mutex_try_lock(m)) 
			return; 
}



mutex_unlock()

SUMMARY	
Unlock a mutex variable
SYNOPSIS
#include <cthreads.h>

void mutex_unlock(mutex_t€m)

DESCRIPTION
The function mutex_unlock() unlocks m, giving other 
threads a chance to lock it.