kzs_thread.hpp File Reference

Threading support. More...

Typedefs

typedef kzUint KzsThreadLocalStorageKey
 Key type to use when storing thread specific global data. More...
 
typedef void * KzsThreadId
 Thread identifier. More...
 
typedef kzsError(* KzsThreadRunner) (void *userData)
 Thread execution function type. More...
 

Functions

KANZI_API kzsError kzsThreadCreate (KzsThreadRunner threadRunner, void *userData, kzBool deleteAutomatically, struct KzsThread **out_thread)
 Creates a thread using the given runner function and arbitrary user data. More...
 
KANZI_API kzsError kzsThreadDelete (struct KzsThread *thread)
 Deletes a thread. More...
 
KANZI_API kzsError kzsThreadJoin (struct KzsThread *thread)
 Waits until the given thread is terminated. More...
 
KANZI_API kzsError kzsThreadGetExitResult (const struct KzsThread *thread)
 Returns the error result of the thread. More...
 
KANZI_API KzsThreadId kzsThreadGetCurrent (void)
 Gets the current thread id. More...
 
KANZI_API kzBool kzsThreadIsCurrent (const struct KzsThread *thread)
 Checks if the given thread is the thread that is executing this function. More...
 
KANZI_API kzsError kzsThreadSleep (kzUint milliseconds)
 Sleeps the thread that is executing this function by given amount of milliseconds. More...
 
KANZI_API kzsError kzsThreadLockCreate (struct KzsThreadLock **out_threadLock)
 Creates a thread synchronization lock object. More...
 
KANZI_API kzsError kzsThreadLockDelete (struct KzsThreadLock *threadLock)
 Deletes a thread synchronization lock object. More...
 
KANZI_API kzsError kzsThreadLockAcquire (struct KzsThreadLock *threadLock)
 Starts a synchronized code section by acquiring a thread lock. More...
 
KANZI_API kzsError kzsThreadLockRelease (struct KzsThreadLock *threadLock)
 Ends a synchronized code section by releasing a thread lock. More...
 
KANZI_API kzsError kzsThreadLockWait (struct KzsThreadLock *threadLock, kzBool autoLock)
 Waits for a given thread lock to become true. More...
 
KANZI_API kzsError kzsThreadLockWaitAndReset (struct KzsThreadLock *threadLock, kzBool autoLock)
 Waits for a given thread lock to become true. More...
 
KANZI_API kzsError kzsThreadLockSet (struct KzsThreadLock *threadLock, kzBool value, kzBool autoLock)
 Sets the value of the given thread lock to true or false. More...
 
KANZI_API kzsError kzsThreadLockIsSet (struct KzsThreadLock *threadLock, kzBool autoLock, kzBool *out_isSet)
 Returns the value of the given thread lock (true or false). More...
 
KANZI_API kzsException kzsThreadGetProcessorCount (kzUint *out_processorCount)
 Gets number of processor cores in system. More...
 
KANZI_API kzsError kzsThreadLocalStorageKeyInitialize (KzsThreadLocalStorageKey *key)
 Initializes thread local storage key. More...
 
KANZI_API kzsError kzsThreadLocalStorageKeyUninitialize (KzsThreadLocalStorageKey *key)
 Uninitializes thread local storage key. More...
 
KANZI_API kzsError kzsThreadLocalStoragePutData (const KzsThreadLocalStorageKey *key, void *data)
 Sets thread specific global data using the given key. More...
 
KANZI_API kzsError kzsThreadLocalStorageGetData (const KzsThreadLocalStorageKey *key, void **out_data)
 Gets thread specific global data using the given key. More...
 

Detailed Description

Threading support.

Copyright 2008-2017 by Rightware. All rights reserved.

Typedef Documentation

Key type to use when storing thread specific global data.

typedef void* KzsThreadId

Thread identifier.

typedef kzsError(* KzsThreadRunner) (void *userData)

Thread execution function type.

Function Documentation

KANZI_API kzsError kzsThreadCreate ( KzsThreadRunner  threadRunner,
void *  userData,
kzBool  deleteAutomatically,
struct KzsThread **  out_thread 
)

Creates a thread using the given runner function and arbitrary user data.

This function also starts the thread. If deleteAutomatically is KZ_TRUE, the thread object is deleted when the thread finishes execution.

Parameters
out_threadResulting thread, KZ_NULL if not required.
KANZI_API kzsError kzsThreadDelete ( struct KzsThread thread)

Deletes a thread.

It is an error to delete a running thread.

KANZI_API kzsError kzsThreadJoin ( struct KzsThread thread)

Waits until the given thread is terminated.

KANZI_API kzsError kzsThreadGetExitResult ( const struct KzsThread thread)

Returns the error result of the thread.

Also returns error if the thread has not yet finished execution. Use kzsThreadJoin to make sure the thread is finished.

KANZI_API KzsThreadId kzsThreadGetCurrent ( void  )

Gets the current thread id.

KANZI_API kzBool kzsThreadIsCurrent ( const struct KzsThread thread)

Checks if the given thread is the thread that is executing this function.

KANZI_API kzsError kzsThreadSleep ( kzUint  milliseconds)

Sleeps the thread that is executing this function by given amount of milliseconds.

KANZI_API kzsError kzsThreadLockCreate ( struct KzsThreadLock **  out_threadLock)

Creates a thread synchronization lock object.

KANZI_API kzsError kzsThreadLockDelete ( struct KzsThreadLock threadLock)

Deletes a thread synchronization lock object.

KANZI_API kzsError kzsThreadLockAcquire ( struct KzsThreadLock threadLock)

Starts a synchronized code section by acquiring a thread lock.

This call must be paired with kzsThreadLockRelease in all code paths.

KANZI_API kzsError kzsThreadLockRelease ( struct KzsThreadLock threadLock)

Ends a synchronized code section by releasing a thread lock.

This call must be paired with kzsThreadLockAcquire in all code paths.

KANZI_API kzsError kzsThreadLockWait ( struct KzsThreadLock threadLock,
kzBool  autoLock 
)

Waits for a given thread lock to become true.

If the lock is already true, this function will not wait. If autoLock is KZ_TRUE, the lock must not be acquired by the thread. If autoLock is KZ_FALSE, the lock must be acquired by the thread exactly once.

KANZI_API kzsError kzsThreadLockWaitAndReset ( struct KzsThreadLock threadLock,
kzBool  autoLock 
)

Waits for a given thread lock to become true.

If the lock is already true, this function will not wait. After the wait is finished, the lock will be set to KZ_FALSE before any other thread wokes up. If autoLock is KZ_TRUE, the lock must not be acquired by the thread. If autoLock is KZ_FALSE, the lock must be acquired by the thread exactly once.

KANZI_API kzsError kzsThreadLockSet ( struct KzsThreadLock threadLock,
kzBool  value,
kzBool  autoLock 
)

Sets the value of the given thread lock to true or false.

If the value is true, any thread waiting for it can wake up. If autoLock is KZ_TRUE, the lock must not be acquired by the thread. If autoLock is KZ_FALSE, the lock must be acquired by the thread exactly once.

KANZI_API kzsError kzsThreadLockIsSet ( struct KzsThreadLock threadLock,
kzBool  autoLock,
kzBool out_isSet 
)

Returns the value of the given thread lock (true or false).

If autoLock is KZ_TRUE, the lock must not be acquired by the thread. If autoLock is KZ_FALSE, the lock must be acquired by the thread exactly once.

KANZI_API kzsException kzsThreadGetProcessorCount ( kzUint out_processorCount)

Gets number of processor cores in system.

Throws KZS_EXCEPTION_UNDEFINED_THREAD_OPERATION if processor count cannot be queried from system.

KANZI_API kzsError kzsThreadLocalStorageKeyInitialize ( KzsThreadLocalStorageKey key)

Initializes thread local storage key.

KANZI_API kzsError kzsThreadLocalStorageKeyUninitialize ( KzsThreadLocalStorageKey key)

Uninitializes thread local storage key.

KANZI_API kzsError kzsThreadLocalStoragePutData ( const KzsThreadLocalStorageKey key,
void *  data 
)

Sets thread specific global data using the given key.

This data is unique between different threads and can be retrieved with GetData.

KANZI_API kzsError kzsThreadLocalStorageGetData ( const KzsThreadLocalStorageKey key,
void **  out_data 
)

Gets thread specific global data using the given key.