# BlitzMax/Modules/System/Threads

Welcome to the weird and wonderful world of multithreading!
Multithreading effectively allows your programs to do several things at the same time. The word 'thread' in this context means 'thread of execution' - or, the series of instructions, branches and so on executed by your program. Most programs are 'single threaded', meaning there is only one thread of execution. However, more and more programs are using multiple threads.
Multithreading used to be achieved by software trickery, which made threading useful but not really faster - there was still only one CPU pretending to do multiple things at the same time! But these days, multicore CPUs mean that threading can be used to truly do multiple things at the same time (or 'in parallel').
Creating a thread is easy - just call CreateThread. You will need to provide a function for the thread to use as its 'entry point'. Once the thread is created, this function will start executing in parallel with the code that called CreateThread. When the thread function returns, that thread will be 'terminated'.
Alas, threading turns out to be rather tricky due to an issue known as 'synchronization'. Synchronization is required when you need to prevent multiple threads from modifying or accessing the same data at the same time. Synchronization usually involves a thread 'blocking'. When a thread blocks, it completely halts execution until another thread does something that causes it to 'unblock' and resume execution.
BlitzMax provides 2 primitives known as 'mutexes' and 'semaphores' to assist with synchronization:

# Types
## TThread

Thread Type
* Detach
* Wait
* Running
* Create
* Main
* Current

## TThread: Methods

Method Detach
Description: Detach this thread
Method Wait:Object
Description: Wait For this thread To finish
Returns: The Object returned by the thread.
Method Running
Description: Check if this thread is running

## TThread: Functions

Function Create:TThread( entry:Object( data:Object),data:Object )
Description: Create a new thread
Function Main:TThread
Description: Get Main thread
Returns: A thread object representing the main application thread.
Function Current:TThread
Description: Get current thread
Returns: A thread object representing the current thread.

## TThreadData

ThreadData type
* SetValue
* GetValue
* Create

## TThreadData: Methods

Method SetValue( value:Object )
Description: Set thread data value
Method GetValue:Object
Description: Get thread data value

## TThreadData: Functions

Function Create:TThreadData
Description: Create thread data

## TMutex

Mutex type
* Close
* Lock
* TryLock
* Unlock
* Create

## TMutex: Methods

Method Close
Description: Close the mutex
Method Lock
Description: Lock the mutex
Method TryLock
Description: Try to lock the mutex
Returns: True if mutex was successfully locked; False if mutex was already locked by another thread.
Method Unlock
Description: Unlock the mutex

## TMutex: Functions

Function Create:TMutex
Description: Create a new mutex

## TSemaphore

Semaphore Type
* Close
* Wait
* Post
* Create

## TSemaphore: Methods

Method Close
Description: Close the semaphore
Method Wait
Description: Wait for the semaphore
Method Post
Description: Post the semaphore

## TSemaphore: Functions

Function Create:TSemaphore( count )
Description: Create a new semaphore

## TCondVar

CondVar type
* Close
* Wait
* Signal
* Broadcast
* Create

## TCondVar: Methods

Method Close
Description: Close the condvar
Method Wait( mutex:TMutex )
Description: Wait for the condvar
Method Signal
Description: Signal the condvar
Method Broadcast
Description: Broadcast the condvar

## TCondVar: Functions

Function Create:TCondVar
Description: Create a new condvar

# Functions
## CreateThread

Function CreateThread:TThread( entry:Object( data:Object ),data:Object )
Description: Create a thread
Returns: A new thread object.
Information: Creates a thread and returns a thread object.
The value returned by the thread entry routine can be later retrieved using WaitThread.
To 'close' a thread, call either DetachThread or WaitThread. This isn't strictly necessary as the thread will eventually be closed when it is garbage collected, however, it may be a good idea if you are creating many threads very often, as some operating systems have a limit on the number of threads that can be allocated at once.
Example:

## MainThread

Function MainThread:TThread
Description: Get Main thread
Returns: A thread Object representing the Main application thread.

## CurrentThread

Function CurrentThread:TThread
Description: Get current thread
Returns: A thread object representing the current thread.

## DetachThread

Function DetachThread( thread:TThread )
Description: Detach a thread
Information: DetachThread closes a thread's handle, but does not halt or otherwise affect the target thread.
Once one a thread has been detached, it wil no longer be possible to use WaitThread to get its return value.
This allows the thread to run without your program having to continually check whether it has completed in order to close it.

## WaitThread

Function WaitThread:Object( thread:TThread )
Description: Wait for a thread to finish
Returns: The object returned by the thread entry routine.
Information: WaitThread causes the calling thread to block until the target thread has completed execution.
If the target thread has already completed execution, WaitThread returns immediately.
The returned object is the object returned by the thread's entry routine, as passed to CreateThread.

## ThreadRunning

Function ThreadRunning( thread:TThread )
Description: Check if a thread is running
Returns: True if thread is still running, otherwise False.

## CreateThreadData

Function CreateThreadData:TThreadData
Description: Create thread data
Returns: A new thread data object.

## SetThreadDataValue

Function SetThreadDataValue( data:TThreadData,value:Object )
Description: Set thread data value

## GetThreadDataValue

Function GetThreadDataValue:Object( data:TThreadData )
Description: Get thread data value

## CreateMutex

Function CreateMutex:TMutex
Description: Create a mutex
Returns: A new mutex object
Example:

## CloseMutex

Function CloseMutex( mutex:TMutex )
Description: Close a mutex

## LockMutex

Function LockMutex( mutex:TMutex )
Description: Lock a mutex

## TryLockMutex

Function TryLockMutex( mutex:TMutex )
Description: Try to lock a mutex
Returns: True if mutex was successfully locked; False if mutex was already locked by another thread.

## UnlockMutex

Function UnlockMutex( mutex:TMutex )
Description: Unlock a mutex

## CreateSemaphore

Function CreateSemaphore:TSemaphore( count )
Description: Create a semaphore
Returns: A new semaphore object
Example:

## CloseSemaphore

Function CloseSemaphore( semaphore:TSemaphore )
Description: Close a semaphore

## WaitSemaphore

Function WaitSemaphore( semaphore:TSemaphore )
Description: Wait for a semaphore

## PostSemaphore

Function PostSemaphore( semaphore:TSemaphore )
Description: Post a semaphore

## CreateCondVar

Function CreateCondVar:TCondVar
Description: Create a condvar
Returns: A new condvar object

## CloseCondVar

Function CloseCondVar( condvar:TCondVar )
Description: Close a condvar

## WaitCondVar

Function WaitCondVar( condvar:TCondVar,mutex:TMutex )
Description: Wait for a condvar

## SignalCondVar

Function SignalCondVar( condvar:TCondVar )
Description: Signal a condvar

## BroadcastCondVar

Function BroadcastCondVar( condvar:TCondVar )
Description: Broadcast a condvar

## CompareAndSwap

Function CompareAndSwap( target Var,oldValue,newValue )
Description: Compare and swap
Returns: True if target was updated
Information: Atomically replace target with new_value if target equals old_value.

## AtomicAdd

Function AtomicAdd( target Var,value )
Description: Atomic add
Returns: Previous value of target
Information: Atomically add value to target.

## AtomicSwap

Function AtomicSwap( target Var,value )
Description: Atomically swap values
Returns: The old value of target