XaoS thread library
===================
This description should be usefull for those, who want to port XaoS
into multiprocessor platforms and those, who want to implement some
filter or other relativly computational expensive code. Note that thread
library should be mapped into nothread calls, in case host does not
allows multithreading or it is not SMP architecture (since this library
is used only to distribute calcualtion into other CPUs)
XaoS thread library is simple map of few functions required by XaoS
to system library for threads.
It has following variables:
- Variable: ethreads
This is set to 1 in case that threads are enabled
- Variable: nthreads
Number of threads
It and following calls:
- Function: void xth_init (int THREADS)
This function initializes threading library (starts threads, sets
ETHREAD to 1 and NTHREADS to n. THREADS parameter should be set to
0 -- autodetection or number of threads users wants. In case
threads is set to 1, threading library is disabled and following
functions are mapped into ther nothread_ equivalents defined in
`xthread.h'.
Note that threads are not identical -- there is main thread (one
that called xth_init) that comunicates with drivers, controls
calcualtion etc. and other tasks that are waiting to orders from
main task. They also can't use functions from xthread library.
- Function: void xth_uninit (void)
This function uninitializes thread library -- kills child threads,
sets ETHREAD to 0 and NTHREADS to 1.
- Function: void xth_function (xfunction *FUNCTION, void *data, int
RANGE)
This function is used in case, engine wants to perform some
operation at image in parael. It is expected to wait until all
threads are ready and start FUNCTION at all threads including
control one with following paramters: DATA -- this parameter is
same as DATA passed to xth_function, TASKINFO -- pointer to
structure taskinfo, that is platform depended (defined in
`xthread.h') but must have at least field `n', that holds number
of thread (control thread has 0 and other numbers in range 1 -
NTHREADS). Next two parameters is range of image, function is
expected to do action. Xth_function is expected to divided RANGE
into NTHREADS equal pieces and pass always start of piece and
start of next piece (RANGE in case of last one). Function does not
wait for other threads at the end and returns imediately to main
thread after FUNCTION returns.
This function is called approx 5-10 times per frame
- Function: void xth_sync (void)
This functions waits until all threads are ready for next order
from main task.
This function is called approx 5-10 times per frame
- Function: void xth_bgjob (xfunction *FUNCTION, void *DATA)
This function is expected to behave as follows: look if there is
any thread waiting for orders, if so, ask him to call FUNCTION
with similiar conventions as in xth_function except that range
parameters are set to 0. Otherwise it starts function in normally
(at foreground).
This function is called once per frame.
- Function: void xth_nthread (struct taskinfo *S)
This function should be used to determine number of current
thread. Do not use `taskinfo->n' instead since in case threads are
disabled, it should be defined to 0 and that allows optimizer to
perform better optimizations. This function should be called by
all threads.
- Function: void xth_lock (int N)
- Function: void xth_unlock (int N)
Lock/unlock lock number N. At least `MAXSEMAPHORS' locks must be
available.
Note that locks are used always for very short fragments of code
so they needs to be fast. So spinlocks are maybe better than
Dijskra semaphors. Untested. They are called once per calculated
line/row during zoom and once per approx 10 pixels during
calculation of new image.
- Function: void xth_sleep (int N, int L)
It is expected to atomically unlock lock L and sleep in queue N.
At least `MAXCONDS' queues must be available. After it is waked
up, lock L again. This mechanizm is used by calcualtion of new
image algorithm, but it is designed to minimize its calls, so I
expect they should be called once or twice.
- Function: void xth_wakeup (int N)
Wake up some thread from queue N. Lock used by sleep calls is
locked in this cases. Function should also wake up all threads if
such operation is not supported by host API. With luck, this
function should not be called at all. It should be called by new
image caluclation routines in case queue is empty. This happends
in case of 50 threads but happeds rarely at two or eight threads
according to my tests.
- Function: void xth_wakeall (int N)
Similiar to wakeup but wake up all threads.