Multi-platform threads

nxs_thread.h More...


Data Structures
struct	nxs_thread
	Structure holding thread information. More...
Defines
#define	NXS_THREAD_HAS_TLS
	If defined, indicates that thread-local storage is available on the current platform.
#define	nxs_thread_semaphore(_type)
	Returns a semaphore structure type managing a variable of the type _type.
#define	NXS_THREAD_USABLE
	If defined, indicates that threading support is available on the current platform.
Typedefs
typedef int	nxs_thread_mutex
	Type representing a mutex handle.
typedef int	nxs_thread_tls
	Type representing a thread-specific identifier for locating data.
Functions
bool	nxs_thread_create (nxs_thread thread, void(entry)(void ), void data)
	Detaches a new thread to function entry with argument data, returning `true` on success.
void	nxs_thread_exit (void)
	Terminates the calling thread.
bool	nxs_thread_kill (nxs_thread *thread)
	Forces the execution of thread to finish, returning `true` on successful thread termination.
bool	nxs_thread_mutex_alloc (nxs_thread_mutex *mutex)
	Allocates a mutex, returning `true` on success.
bool	nxs_thread_mutex_free (nxs_thread_mutex mutex)
	Frees mutex, returning `true` on success.
bool	nxs_thread_mutex_lock (nxs_thread_mutex mutex)
	Locks mutex, returning `true` on success.
bool	nxs_thread_mutex_tryLock (nxs_thread_mutex mutex)
	Locks mutex if it is available, returning `true` on success.
bool	nxs_thread_mutex_unlock (nxs_thread_mutex mutex)
	Unlocks mutex.
static bool	nxs_thread_sem_init (void *semaphore)
	Initializes semaphore, returning `true` on success.
static bool	nxs_thread_sem_lock (void *semaphore)
	Locks semaphore, returning `true` on success.
static bool	nxs_thread_sem_release (void *semaphore)
	Releases semaphore, returning `true` on success.
static bool	nxs_thread_sem_tryLock (void *semaphore)
	Locks semaphore if it is available, returning `true` on success.
static bool	nxs_thread_sem_unlock (void *semaphore)
	Unlocks semaphore.
void	nxs_thread_sleep (unsigned long ms)
	Sleeps the calling thread until ms milliseconds have elapsed.
bool	nxs_thread_tls_alloc (nxs_thread_tls *tls)
	Allocates a thread-local storage identifier, returning `true` on success.
bool	nxs_thread_tls_free (nxs_thread_tls tls)
	Frees thread-local storage identifier tls, returning `true` on success.
void *	nxs_thread_tls_get (nxs_thread_tls tls)
	Returns the thread-local storage associated with identifier tls.
bool	nxs_thread_tls_set (nxs_thread_tls tls, const void *data)
	Associates data with thread-local storage identifier tls, returning `true` on success.
bool	nxs_thread_wait (nxs_thread *thread)
	Blocks, waiting for the execution of thread to finish, returning `true` on successful thread termination.

Detailed Description

nxs_thread.h

Note:: This module is only available on certain platforms. See NXS_THREAD_USABLE.

Define Documentation

#define NXS_THREAD_HAS_TLS

If defined, indicates that thread-local storage is available on the current platform.

If support is not available, all thread-local storage functions will still exist, but will always fail.

Note:

Support is currently provided for:

Windows (32-bit)
Any platform implementing POSIX.1c (which, at the moment, is just about every personal *nix system, including Mac OS X)

See also:: nxs_thread_tls_alloc nxs_thread_tls_free nxs_thread_tls_get nxs_thread_tls_set

#define nxs_thread_semaphore ( _type )

Returns a semaphore structure type managing a variable of the type _type.

 // define a semaphore 'sem' with type int
 nxs_thread_semaphore(int) sem;

 // initialize 'sem'
 nxs_thread_sem_init(&sem);

 ...

 // change the value of 'sem'
 nxs_thread_sem_lock(&sem);
 sem.value = 5;
 nxs_thread_sem_unlock(&sem);

 ...

 // release 'sem'
 nxs_thread_sem_release(&sem);

#define NXS_THREAD_USABLE

If defined, indicates that threading support is available on the current platform.

If support is not available, all thread functions will still exist, but will always fail.

Note:

Support is currently provided for:

Windows (32-bit)
Any platform implementing POSIX.1c (which, at the moment, is just about every personal *nix system, including Mac OS X)

See also:: NXS_THREAD_HAS_TLS

Typedef Documentation

typedef int nxs_thread_mutex

Type representing a mutex handle.

Warning:: This appears defined as an int only because of a Doxygen workaround. Do not depend on this representation; the type need not even be scalar.

typedef int nxs_thread_tls

Type representing a thread-specific identifier for locating data.

Warning:: This appears defined as an int only because of a Doxygen workaround. Do not depend on this representation; the type need not even be scalar.

Function Documentation

bool nxs_thread_create	(	nxs_thread *	thread,
		void()(void )	entry,
		void *	data
	)

Detaches a new thread to function entry with argument data, returning true on success.

Stores thread information in thread.

void nxs_thread_exit ( void )

Terminates the calling thread.

bool nxs_thread_kill ( nxs_thread * thread )

Forces the execution of thread to finish, returning true on successful thread termination.

bool nxs_thread_mutex_alloc ( nxs_thread_mutex * mutex )

Allocates a mutex, returning true on success.

If false is returned, the value pointed to by mutex is indeterminate.

See also:: nxs_thread_mutex_free

bool nxs_thread_mutex_free ( nxs_thread_mutex mutex )

Frees mutex, returning true on success.

If mutex is locked by another thread, this operation will fail.

bool nxs_thread_mutex_lock ( nxs_thread_mutex mutex )

Locks mutex, returning true on success.

If mutex is already locked by another thread, the calling thread will block until mutex is available.

See also:: nxs_thread_mutex_tryLock

bool nxs_thread_mutex_tryLock ( nxs_thread_mutex mutex )

Locks mutex if it is available, returning true on success.

If mutex is already locked by another thread, false is returned.

See also:: nxs_thread_mutex_lock

bool nxs_thread_mutex_unlock ( nxs_thread_mutex mutex )

Unlocks mutex.

Warning:: If mutex was not locked by the calling thread, the behavior is undefined.

static bool nxs_thread_sem_init ( void * semaphore ) [inline, static]

Initializes semaphore, returning true on success.

If false is returned, the value pointed to by semaphore is indeterminate.

See also:: nxs_thread_sem_release

static bool nxs_thread_sem_lock ( void * semaphore ) [inline, static]

Locks semaphore, returning true on success.

If semaphore is already locked by another thread, the calling thread will block until semaphore is available.

See also:: nxs_thread_semaphore nxs_thread_sem_tryLock

static bool nxs_thread_sem_release ( void * semaphore ) [inline, static]

Releases semaphore, returning true on success.

If semaphore is locked by another thread, this operation will fail.

static bool nxs_thread_sem_tryLock ( void * semaphore ) [inline, static]

Locks semaphore if it is available, returning true on success.

If semaphore is already locked by another thread, false is returned.

See also:: nxs_thread_semaphore nxs_thread_sem_lock

static bool nxs_thread_sem_unlock ( void * semaphore ) [inline, static]

Unlocks semaphore.

Warning:: If semaphore was not locked by the calling thread, the behavior is undefined.

See also:: nxs_thread_semaphore

void nxs_thread_sleep ( unsigned long ms )

Sleeps the calling thread until ms milliseconds have elapsed.

bool nxs_thread_tls_alloc ( nxs_thread_tls * tls )

Allocates a thread-local storage identifier, returning true on success.

If false is returned, the value pointed to by tls is indeterminate. Any thread can use this identifier to store and retrieve values that are local to the thread, because each thread receives its own slot for the identifier.

See also:: NXS_THREAD_HAS_TLS
nxs_thread_tls_free

bool nxs_thread_tls_free ( nxs_thread_tls tls )

Frees thread-local storage identifier tls, returning true on success.

Note:: This does not release any custom thread-local data set with nxs_thread_tls_set().

void* nxs_thread_tls_get ( nxs_thread_tls tls )

Returns the thread-local storage associated with identifier tls.

This action will always succeed if tls is valid. If tls has no storage associated with it, NULL is returned.

Warning:: If tls is invalid, the behavior is undefined.

bool nxs_thread_tls_set	(	nxs_thread_tls	tls,
		const void *	data
	)

Associates data with thread-local storage identifier tls, returning true on success.

bool nxs_thread_wait ( nxs_thread * thread )

Blocks, waiting for the execution of thread to finish, returning true on successful thread termination.

Generated on Thu Dec 20 13:42:47 2007 for NXS Toolkit by

1.5.4

Multi-platform threads

Data Structures

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation