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.
Created by Justin Spahr-Summers on 2007-12-08. Copyright 2007. All rights reserved.

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  doxygen 1.5.4