Thread library overview

This is only a quick overview of the Thread library. The reference of this library should give all its content.

Creating and launching threads: the class THREAD (deferred)

The class of the thread object you want to create should inherit the THREAD class.
Your thread is represented by a class which inherits from THREAD (deferred class).

	class
		MY_THREAD

	inherit
		THREAD>
		...

	feature

		execute is
			-- define the deferred feature from THREAD.
		do
			...
		end
		...

	end --class MY_THREAD

Creating a thread is like creating an Eiffel object:

	my_thread: MY_THREAD
		-- MY_THREAD inherits from THREAD and defines
		-- the deferred procedure `execute'

	create my_thread

Note: You have created a thread object but have not started the thread itself yet.
To run the thread, use the feature launch from THREAD.

	my_thread.launch

On the Eiffel side, the procedure execute will be launched. This procedure is deferred in class THREAD, you have to define it in MY_THREAD.

On the C side, a C thread will be created and launched.

Caution: you may call join_all and the end of the exceution of the parent thread if you do not want it to die before its child, otherwise they may prematurily terminate.

The class MUTEX

The implementation of the class MUTEX is mapped on the C standard thread library. An instance of class MUTEX can be shared between different thread.

my_mutex.pointer is the pointer to the nested C mutex of my_mutex.

Declaration of the mutex:
```
	my_mutex: MUTEX
```
Creation of mutex:
```
	create my_mutex.make
```
Locking the mutex:
```
	my_mutex.lock
```
Unlocking the mutex:
```
	my_mutex.unlock
```
try_lock: if it is not locked yet, lock the mutex and return True, otherwise it returns False.
```
	my_mutex.try_lock
```
Is my mutex initialized?
```
	my_mutex.is_set
```

Note: on Windows: The MUTEX objects on Windows are recursive while they are not on Unix. A recursive mutex can be locked twice by the same thread.

Caution: be sure that a mutex is unlocked when it is disposed.

The class SEMAPHORE

Like MUTEX, the features of this class are mapped on the C thread library. An instance of class SEMAPHORE can be shared between thread.

Declaration of the semaphore :
```
	my_sem: SEMAPHORE
```
Creation of semaphore: initialize semaphore with nb_tokens, it requires nb_tokens >= 0
```
	create my_sem.make (nb_tokens)
```
Wait for a token:
```
	my_sem.wait
```
Give back a token:
```
	my_sem.post
```
try_wait, similar to try_lock from MUTEX, if a token is available, take it and return True, otherwise return False.
```
	my_sem.try_wait
```

Caution: be sure that a semaphore does not wait for a token when it is disposed

The class CONDITION_VARIABLE

This class allows to use condition variables in Eiffel. An instance of class CONDITION_VARIABLE can be shared between threads.

Declaration of the condition variable
```
	my_cond: CONDITION_VARIABLE
```
Creation:
```
	create my_cond.make
```

Wait for a signal (send by signal). You need to use a mutex.

	my_mutex: MUTEX

	create my_mutex.make

my_mutex must be locked by the calling thread so as wait can be called. wait atomically unlocks my_mutex and waits for the condition variable my_mutex to receive a signal. As soon as it received a signal, my_cond locks my_mutex;

	my_mutex.lock
		-- You must lock `my_mutex' before calling wait.

	my_cond.wait (my_mutex)
		-- Here the critical code to execute when `my_cond' received a signal.

	my_mutex.unlock
		-- Unlock the mutex at the end of the critical section.

Send a signal one thread blocked on the condition variable `my_cond'.
```
	my_cond.signal
```
Send a signal to all the threads blocked on the condition variable `my_cond'.
```
	my_cond.broadcast
```

Caution: be sure that a condition variable is unblocked when it is disposed.

Miscellaneous classes

class THREAD_ATTRIBUTES: defines the attributes of an Eiffel Thread regarding the thread scheduling policy and priority.

Controlling execution: THREAD_CONTROL

yield: the calling thread yields its execution in favor of an other thread of same priority.
join_all: the calling thread waits for all other threads to finished (all its children).
A parent thread can wait for the termination of a child process through the feature join of class THREAD_CONTROL (inherited by THREAD):
```
	thr: MY_THREAD
	...
	thr.launch
	...
	thr.join
```