|
|
thread
Index
void BroadcastCondition(
void * cond );
Signals all threads waiting on a condition variable.
cond - the condition to signal.
This function always succeeds.
LockMutex(mutex);
BroadcastCondition(cond);
UnlockMutex(mutex);
Before calling this function you should lock the mutex that protects
the condition. WaitCondition() atomically unlocks the mutex and waits
on the condition, so by locking the mutex first before sending the
signal, you ensure that the signal cannot be missed. See
WaitCondition() for more details.
If no threads are waiting on the condition, nothing happens.
void * CreateCondition();
Creates a condition variable.
The newly created condition, or NULL if one couldn't be created.
Condition cond = CreateCondition();
Creates a mutual exclusion device (aka lock).
The newly created mutex, or NULL if a mutex couldn't be created.
Mutex mutex = CreateMutex();
uint32_t CreateThread(
ThreadEntryFunction entry,
void * data );
entry - pointer to a function to run in the new thread
data - pointer to pass in the first in the first argument to function
pointed to by entry
Numeric thread ID, or 0 if the thread could not be started.
uint32_t id = CreateThread(entry, data);
if (id < 0)
printf("thread creation failed\n");
else
printf("thread %d created\n", id);
uint32_t CurrentThread();
Get the ID of the running thread.
Numeric thread ID, or 0 if this is not a thread.
uint32_t id = CurrentThread();
printf("this is thread %d\n", id);
BOOL DestroyCondition(
void * cond );
Destroys a condition variable.
cond - the condition variable to destroy.
TRUE if the condition was destroyed, otherwise FALSE.
You cannot destroy a condition variable if other threads are waiting on
it.
BOOL DestroyMutex(
void * mutex );
mutex - the mutex to destroy.
TRUE if the mutex was destroyed, otherwise FALSE.
You cannot destroy a mutex that is currently locked or has tasks
waiting to lock it.
BOOL DetachThread(
uint32_t thread_id );
Detaches a thread from the parent process.
thread_id - ID of thread to detach.
TRUE if the thread was detached, FALSE if the thread was already
detached or another error occured.
You cannot detach a thread that is already detached.
Once detached, the thread is no longer accessible from any other
thread.
Currently this doesn't really do anything other than make it so you
can't call WaitThread() on the thread. Threads can't truly be detached
from the parent process since they run in the same address space, and
so when the process exits the program code and all its other resources
a freed.
thread.library protects against this by waiting for all threads to
complete (detached or not) before allowing the main process to exit.
Detached threads can't be truly implemented until a thread task and its
allocated resources can exist independently of the process that created
it.
void LockMutex(
void * mutex );
Locks a mutex. If the lock is already held, this function blocks.
This function always succeeds.
void SignalCondition(
void * cond );
Signals a thread waiting on condition variable.
cond - the condition to signal.
This function always succeeds.
LockMutex(mutex);
SignalCondition(cond);
UnlockMutex(mutex);
Before calling this function you should lock the mutex that protects
the condition. WaitCondition() atomically unlocks the mutex and waits
on the condition, so by locking the mutex first before sending the
signal, you ensure that the signal cannot be missed. See
WaitCondition() for more details.
If no threads are waiting on the condition, nothing happens. If more
than one thread is waiting, only one will be signalled. Which one is
undefined.
BOOL TryLockMutex(
void * mutex );
Tries to lock a mutex. If the lock is already held, this function
fails.
TRUE if the lock was acquired, FALSE if the lock is already held.
void UnlockMutex(
void * mutex );
This function always succeeds.
Blocks the current task until all threads exit.
This function always succeeds.
This function will ignore detached threads.
BOOL WaitCondition(
void * cond,
void * mutex );
Blocks until a condition is signaled.
cond - the condition variable to wait on.
mutex - a mutex that protects the condition
TRUE if the condition was signaled, FALSE if an error occured.
LockMutex(mutex);
WaitCondition(cond, mutex);
UnlockMutex(mutex);
This function will atomically unlock the mutex and wait on the
condition. The thread is suspended until the condition is signalled.
After the condition is signalled, the mutex is relocked before
returning to the caller.
The use of a mutex in conjunction with waiting on and signalling the
condition ensures that no signals are missed. See SignalCondition() for
more details.
BOOL WaitThread(
uint32_t thread_id,
void ** result );
Blocks the current task until the requested thread exits.
thread_id - ID of thread to detach.
result - pointer to storage for the thread's return value. You can
pass NULL here if you don't care about the return value.
TRUE when the thread completed successfully. FALSE if thread could not
be waited on.
void *ret;
WaitThread(id, &ret);
A thread cannot wait on itself. A thread cannot be waited on if it is
detached.
If the thread has already completed, this call returns immediately with
the thread result. Further calls to this function for that thread will
fail.
Multiple threads can wait for a thread to complete. They will all
be notified when the thread completes, and will all receive the result.
|
