GNU Info

(xaos.info)xthreads

---

Next: filters Prev: driver Up: Hacker

---

Enter node , (file) or (file)node

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.