tinycthread.h File Reference

#include <time.h>
#include <pthread.h>

Go to the source code of this file.

Macros
#define	TINYCTHREAD_VERSION_MAJOR   1
	TinyCThread version (major number). More...
#define	TINYCTHREAD_VERSION_MINOR   2
	TinyCThread version (minor number). More...
#define	TINYCTHREAD_VERSION   (TINYCTHREAD_VERSION_MAJOR * 100 + TINYCTHREAD_VERSION_MINOR)
	TinyCThread version (full version). More...
#define	_Thread_local
	Thread local storage keyword. More...
#define	thrd_error   0
	The requested operation failed.
#define	thrd_success   1
	The requested operation succeeded.
#define	thrd_timedout   2
	The time specified in the call was reached without acquiring the requested resource.
#define	thrd_busy   3
	The requested operation failed because a tesource requested by a test and return function is already in use.
#define	thrd_nomem   4
	The requested operation failed because it was unable to allocate memory.
#define	call_once(flag, func)   pthread_once(flag,func)
	Invoke a callback exactly once. More...

Typedefs
typedef int(*	thrd_start_t )(void *arg)
	Thread start function. More...
typedef void(*	tss_dtor_t )(void *val)
	Destructor function for a thread-specific storage. More...

Functions
int	mtx_init (mtx_t *mtx, int type)
	Create a mutex object. More...
void	mtx_destroy (mtx_t *mtx)
	Release any resources used by the given mutex. More...
int	mtx_lock (mtx_t *mtx)
	Lock the given mutex. More...
int	mtx_timedlock (mtx_t *mtx, const struct timespec *ts)
	NOT YET IMPLEMENTED.
int	mtx_trylock (mtx_t *mtx)
	Try to lock the given mutex. More...
int	mtx_unlock (mtx_t *mtx)
	Unlock the given mutex. More...
int	cnd_init (cnd_t *cond)
	Create a condition variable object. More...
void	cnd_destroy (cnd_t *cond)
	Release any resources used by the given condition variable. More...
int	cnd_signal (cnd_t *cond)
	Signal a condition variable. More...
int	cnd_broadcast (cnd_t *cond)
	Broadcast a condition variable. More...
int	cnd_wait (cnd_t *cond, mtx_t *mtx)
	Wait for a condition variable to become signaled. More...
int	cnd_timedwait (cnd_t *cond, mtx_t *mtx, const struct timespec *ts)
	Wait for a condition variable to become signaled. More...
int	thrd_create (thrd_t *thr, thrd_start_t func, void *arg)
	Create a new thread. More...
thrd_t	thrd_current (void)
	Identify the calling thread. More...
int	thrd_detach (thrd_t thr)
	Dispose of any resources allocated to the thread when that thread exits. More...
int	thrd_equal (thrd_t thr0, thrd_t thr1)
	Compare two thread identifiers. More...
void	thrd_exit (int res) TTHREAD_NORETURN
	Terminate execution of the calling thread. More...
int	thrd_join (thrd_t thr, int *res)
	Wait for a thread to terminate. More...
int	thrd_sleep (const struct timespec *duration, struct timespec *remaining)
	Put the calling thread to sleep. More...
void	thrd_yield (void)
	Yield execution to another thread. More...
int	tss_create (tss_t *key, tss_dtor_t dtor)
	Create a thread-specific storage. More...
void	tss_delete (tss_t key)
	Delete a thread-specific storage. More...
void *	tss_get (tss_t key)
	Get the value for a thread-specific storage. More...
int	tss_set (tss_t key, void *val)
	Set the value for a thread-specific storage. More...

Macro Definition Documentation

#define _Thread_local

Thread local storage keyword.

A variable that is declared with the _Thread_local keyword makes the value of the variable local to each thread (known as thread-local storage, or TLS). Example usage:

// This variable is local to each thread.
_Thread_local int variable;

Note

The _Thread_local keyword is a macro that maps to the corresponding compiler directive (e.g. __declspec(thread)).

This directive is currently not supported on Mac OS X (it will give a compiler error), since compile-time TLS is not supported in the Mac OS X executable format. Also, some older versions of MinGW (before GCC 4.x) do not support this directive, nor does the Tiny C Compiler.

#define call_once	(		flag,
			func
	)		pthread_once(flag,func)

Invoke a callback exactly once.

Parameters

flag	Flag used to ensure the callback is invoked exactly once.
func	Callback to invoke.

#define TINYCTHREAD_VERSION   (TINYCTHREAD_VERSION_MAJOR * 100 + TINYCTHREAD_VERSION_MINOR)

TinyCThread version (full version).

#define TINYCTHREAD_VERSION_MAJOR   1

TinyCThread version (major number).

#define TINYCTHREAD_VERSION_MINOR   2

TinyCThread version (minor number).

Typedef Documentation

typedef int(* thrd_start_t)(void *arg)

Thread start function.

Any thread that is started with the thrd_create() function must be started through a function of this type.

Parameters

arg	The thread argument (the arg argument of the corresponding thrd_create() call).

Returns

The thread return value, which can be obtained by another thread by using the thrd_join() function.

typedef void(* tss_dtor_t)(void *val)

Destructor function for a thread-specific storage.

Parameters

val	The value of the destructed thread-specific storage.

Function Documentation

int cnd_broadcast

(

cnd_t *

cond

)

Broadcast a condition variable.

Unblocks all of the threads that are blocked on the given condition variable at the time of the call. If no threads are blocked on the condition variable at the time of the call, the function does nothing and return success.

Parameters

cond	A condition variable object.

Returns

thrd_success on success, or thrd_error if the request could not be honored.

void cnd_destroy

(

cnd_t *

cond

)

Release any resources used by the given condition variable.

Parameters

cond	A condition variable object.

int cnd_init

(

cnd_t *

cond

)

Create a condition variable object.

Parameters

cond	A condition variable object.

Returns

thrd_success on success, or thrd_error if the request could not be honored.

int cnd_signal

(

cnd_t *

cond

)

Signal a condition variable.

Unblocks one of the threads that are blocked on the given condition variable at the time of the call. If no threads are blocked on the condition variable at the time of the call, the function does nothing and return success.

Parameters

cond	A condition variable object.

Returns

thrd_success on success, or thrd_error if the request could not be honored.

int cnd_timedwait	(	cnd_t *	cond,
		mtx_t *	mtx,
		const struct timespec *	ts
	)

Wait for a condition variable to become signaled.

The function atomically unlocks the given mutex and endeavors to block until the given condition variable is signaled by a call to cnd_signal or to cnd_broadcast, or until after the specified time. When the calling thread becomes unblocked it locks the mutex before it returns.

Parameters

cond	A condition variable object.
mtx	A mutex object.
xt	A point in time at which the request will time out (absolute time).

Returns

thrd_success upon success, or thrd_timeout if the time specified in the call was reached without acquiring the requested resource, or thrd_error if the request could not be honored.

int cnd_wait	(	cnd_t *	cond,
		mtx_t *	mtx
	)

Wait for a condition variable to become signaled.

The function atomically unlocks the given mutex and endeavors to block until the given condition variable is signaled by a call to cnd_signal or to cnd_broadcast. When the calling thread becomes unblocked it locks the mutex before it returns.

Parameters

cond	A condition variable object.
mtx	A mutex object.

Returns

thrd_success on success, or thrd_error if the request could not be honored.

void mtx_destroy

(

mtx_t *

mtx

)

Release any resources used by the given mutex.

Parameters

mtx	A mutex object.

int mtx_init	(	mtx_t *	mtx,
		int	type
	)

Create a mutex object.

Parameters

mtx

A mutex object.

type

Bit-mask that must have one of the following six values: mtx_plain for a simple non-recursive mutex mtx_timed for a non-recursive mutex that supports timeout mtx_try for a non-recursive mutex that supports test and return mtx_plain | mtx_recursive (same as mtx_plain, but recursive) mtx_timed | mtx_recursive (same as mtx_timed, but recursive) mtx_try | mtx_recursive (same as mtx_try, but recursive)

Returns

thrd_success on success, or thrd_error if the request could not be honored.

int mtx_lock

(

mtx_t *

mtx

)

Lock the given mutex.

Blocks until the given mutex can be locked. If the mutex is non-recursive, and the calling thread already has a lock on the mutex, this call will block forever.

Parameters

mtx	A mutex object.

Returns

thrd_success on success, or thrd_error if the request could not be honored.

int mtx_trylock

(

mtx_t *

mtx

)

Try to lock the given mutex.

The specified mutex shall support either test and return or timeout. If the mutex is already locked, the function returns without blocking.

Parameters

mtx	A mutex object.

Returns

thrd_success on success, or thrd_busy if the resource requested is already in use, or thrd_error if the request could not be honored.

int mtx_unlock

(

mtx_t *

mtx

)

Unlock the given mutex.

Parameters

mtx	A mutex object.

Returns

thrd_success on success, or thrd_error if the request could not be honored.

int thrd_create	(	thrd_t *	thr,
		thrd_start_t	func,
		void *	arg
	)

Create a new thread.

Parameters

thr	Identifier of the newly created thread.
func	A function pointer to the function that will be executed in the new thread.
arg	An argument to the thread function.

Returns

thrd_success on success, or thrd_nomem if no memory could be allocated for the thread requested, or thrd_error if the request could not be honored.

Note

A thread’s identifier may be reused for a different thread once the original thread has exited and either been detached or joined to another thread.

thrd_t thrd_current

(

void

)

Identify the calling thread.

Returns

The identifier of the calling thread.

int thrd_detach

(

thrd_t

thr

)

Dispose of any resources allocated to the thread when that thread exits.

Returns

thrd_success, or thrd_error on error

int thrd_equal	(	thrd_t	thr0,
		thrd_t	thr1
	)

Compare two thread identifiers.

The function determines if two thread identifiers refer to the same thread.

Returns

Zero if the two thread identifiers refer to different threads. Otherwise a nonzero value is returned.

void thrd_exit

(

int

res

)

Terminate execution of the calling thread.

Parameters

res	Result code of the calling thread.

int thrd_join	(	thrd_t	thr,
		int *	res
	)

Wait for a thread to terminate.

The function joins the given thread with the current thread by blocking until the other thread has terminated.

Parameters

thr	The thread to join with.
res	If this pointer is not NULL, the function will store the result code of the given thread in the integer pointed to by res.

Returns

thrd_success on success, or thrd_error if the request could not be honored.

int thrd_sleep	(	const struct timespec *	duration,
		struct timespec *	remaining
	)

Put the calling thread to sleep.

Suspend execution of the calling thread.

Parameters

duration	Interval to sleep for
remaining	If non-NULL, this parameter will hold the remaining time until time_point upon return. This will typically be zero, but if the thread was woken up by a signal that is not ignored before duration was reached remaining will hold a positive time.

Returns

0 (zero) on successful sleep, -1 if an interrupt occurred, or a negative value if the operation fails.

void thrd_yield

(

void

)

Yield execution to another thread.

Permit other threads to run, even if the current thread would ordinarily continue to run.

int tss_create	(	tss_t *	key,
		tss_dtor_t	dtor
	)

Create a thread-specific storage.

Parameters

key	The unique key identifier that will be set if the function is successful.
dtor	Destructor function. This can be NULL.

Returns

thrd_success on success, or thrd_error if the request could not be honored.

Note

On Windows, the dtor will definitely be called when appropriate for threads created with thrd_create. It will be called for other threads in most cases, the possible exception being for DLLs loaded with LoadLibraryEx. In order to be certain, you should use thrd_create whenever possible.

void tss_delete

(

tss_t

key

)

Delete a thread-specific storage.

The function releases any resources used by the given thread-specific storage.

Parameters

key	The key that shall be deleted.

void* tss_get

(

tss_t

key

)

Get the value for a thread-specific storage.

Parameters

key	The thread-specific storage identifier.

Returns

The value for the current thread held in the given thread-specific storage.

int tss_set	(	tss_t	key,
		void *	val
	)

Set the value for a thread-specific storage.

Parameters

key	The thread-specific storage identifier.
val	The value of the thread-specific storage to set for the current thread.

Returns

thrd_success on success, or thrd_error if the request could not be honored.