cu/thread.h: Multi-Threading (Extensions to pthreads)


typedef pthread_mutex_t cu_mutex_t
void cu_mutex_lock (pthread_mutex_t *m)
cu_bool_t cu_mutex_trylock (pthread_mutex_t *m)
void cu_mutex_unlock (pthread_mutex_t *m)
#define cu_mutex_init(m)   pthread_mutex_init(m, NULL)

Thread Creation and Initialisation

int cu_pthread_create (pthread_t *thread_out, pthread_attr_t const *attrs, void *(*cf)(void *), void *cd)
void cu_thread_init (void)
void cu_assert_thread_init (void)
void cu_register_thread_init (cu_clop0(on_entry, void), cu_clop0(on_exit, void))
void cu_thread_atexit (cu_clop0(cleanup, void))
void cu_pthread_key_create (pthread_key_t *key_out, void(*destructor)(void *))
void cu_pthread_setspecific (pthread_key_t key, void *data)
#define cu_pthread_join   GC_pthread_join
#define cu_pthread_detach   GC_pthread_detach

Per-Pointer Mutices

cu_mutex_t * cu_pmutex_mutex (void *ptr)
void cu_pmutex_lock (void *ptr)
cu_bool_t cu_pmutex_trylock (void *ptr)
void cu_pmutex_unlock (void *ptr)

Detailed Description

These are mostly light wrappers around the pthread functions or from the corresponding GC wrappers. You may as well use the underlying functions if you prefer.

The mutex functions defined here will, when debugging is enabled, check the error codes from the pthread library, and abort on errors which should not occur in a correct program. These are EINVAL, EDEADLK and EPERM, whereas EBUSY is reported *by cu_pthread_trylock as a cu_false return.

Define Documentation

#define cu_pthread_detach   GC_pthread_detach

Alias for the GC wrapper for pthread_detach.

#define cu_pthread_join   GC_pthread_join

Alias for the GC wrapper for pthread_join.

Function Documentation

void cu_assert_thread_init ( void   ) 

Checks to make sure the thread initialisation have been run.

void cu_mutex_lock ( pthread_mutex_t *  m  ) 

Lock m. Aborts on bad usage if debugging is enabled.

cu_bool_t cu_mutex_trylock ( pthread_mutex_t *  m  ) 

Tries to lock m without blocking, and return true iff successful. Aborts on bad usage if debugging is enabled.

void cu_mutex_unlock ( pthread_mutex_t *  m  ) 

Unlock m. Aborts on bad usage if debugging is enabled.

void cu_pmutex_lock ( void *  ptr  ) 

Lock a mutex indexed by a hash mix of (cu_hash_t)ptr. These per-pointer mutices must not be used recursively, since several object pointers may have the same mutex.

cu_bool_t cu_pmutex_trylock ( void *  ptr  ) 

Attempt to lock a mutex indexed by a hash mix of (cu_hash_t)ptr. See also cu_pmutex_lock.

void cu_pmutex_unlock ( void *  ptr  ) 

Unlock a mutex indexed by a hash mix of (cu_hash_t)ptr.

int cu_pthread_create ( pthread_t *  thread_out,
pthread_attr_t const *  attrs,
void *(*)(void *)  cf,
void *  cd 

A wrapper around GC_pthread_create (and thus pthread_create), which also runs thread-specific initialisation code registered with cu_register_thread_init or CU_THREADLOCAL_INIT.

void cu_pthread_key_create ( pthread_key_t *  key_out,
void(*)(void *)  destructor 

An error-checking wrapper for pthread_key_create.

void cu_pthread_setspecific ( pthread_key_t  key,
void *  data 

An error-checking wrapper for pthread_setspecific.

void cu_register_thread_init ( cu_clop0(on_entry, void)  ,
cu_clop0(on_exit, void)   

Calls on_entry and arranges for on_entry to be called in each newly started thread before other code, and on_exit to be called before the thread exits. The on_entry callbacks are called in order of registration, and on_exit are called in reverse order of registration. Either one may be cu_clop_null if it's not needed. These callbacks only take effect in the main thread and threads which are created with cu_pthread_create.

void cu_thread_atexit ( cu_clop0(cleanup, void)   ) 

Register cleanup to be run at exit or cancellation of the current thread, and before previously registered cleanup functions.

void cu_thread_init ( void   ) 

If you don't have the chance to use cu_pthread_create, call this function as a fall-back to perform thread-local initialisation before using functions which rely on it. This function is idempotent, and it will also arrange for the associated cleaup functions to be called before thread exit.

Generated 2009-11-23 for culibs-0.25 using Doxygen. Maintained by Petter Urkedal.