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

Mutices
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_INITIALISER   PTHREAD_MUTEX_INITIALIZER
#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.