Changeset 650 for trunk/libs/libalmosmkh/almosmkh.h

Timestamp:

Nov 14, 2019, 11:44:12 AM (4 years ago)

Author:

alain

Message:

Simplify the pthread_parallel_create() syscall.

File:

• trunk/libs/libalmosmkh/almosmkh.h (modified) (4 diffs)

trunk/libs/libalmosmkh/almosmkh.h

@@ -101 +101 @@
  * @ level    : [in]  macro-cluster level in [1,2,3,4,5].
  * @ cxy      : [out] selected core cluster identifier.
- * @ lid      : [out] selectod core local index.
+ * @ lid      : [out] selected core local index.
  * @ return 0 if success / 1 if no core in macro-cluster / -1 if illegal arguments.
  **************************************************************************************/
@@ -415 +415 @@
  * This function releases the memory buffer identified by the <ptr> argument,
  * to the store identified by the <cxy> argument.
- * It displays an error message, but does nothing if the ptr is illegal.
+ * It  does nothing, but displays an error message, if the ptr is illegal.
  *****************************************************************************************
  * @ ptr   : pointer on the released buffer.
@@ -456 +456 @@
 
 //////////////////////////////////////////////////////////////////////////////////////////
-// This system call can be used to parallelize the creation and the termination
-// of a parallel multi-threaded application. It removes the loop in the main thread that
-// creates the N working threads (N  sequencial pthread_create() ). It also removes the
-// loop that waits completion of these N working threads (N sequencial pthread_join() ).
-// It creates one "work" thread (in detached mode) per core in the target architecture.
-// Each "work" thread is identified by the [cxy][lid] indexes (cluster / local core). 
-// The pthread_parallel_create() function returns only when all "work" threads completed
+// This syscall can be used to parallelize the creation, and the termination 
+// of a parallel multi-threaded application. 
+// It removes in the main thread the sequencial loop that creates the N working threads 
+// (N pthread_create() ), and removes also the sequencial loop that waits completion 
+// of these N working threads (N pthread_join() ).
+// It creates one <work> thread (in detached mode) per core in the target architecture.
+// Each <work> thread is identified by a continuous [tid] index. 
+// For a regular architecture, defined by the [x_size , y_size , ncores] parameters,
+// the number of working threads can be the simply computed as (x_size * y_size * ncores), 
+// and the coordinates[x,y,lid] of the core running the thread[tid] cand be directly 
+// derived from the [tid] value with the following relations:
+//     . cid = (x * y_size) + y
+//     . tid = (cid * ncores ) + lid
+//     . lid = tid % ncores
+//     . cid = tid / ncores
+//     . y   = cid % y_size
+//     . x   = cid / y_size
+// The pthread_parallel_create() function returns only when all <work> threads completed
 // (successfully or not).
 //
-// To use this system call, the application code must define the following structures:
-// - To define the arguments to pass to the <work> function the application must allocate
-//   and initialize a first 2D array, indexed by [cxy] and [lid] indexes, where each slot
-//   contains an application specific structure, and another 2D array, indexed by the same
-//   indexes, containing pointers on these structures. This array of pointers is one
-//   argument of the pthread_parallel_create() function.
-// - To detect the completion of the <work> threads, the application must allocate a 1D
-//   array, indexed by the cluster index [cxy], where each slot contains a pthread_barrier
-//   descriptor. This barrier is initialised by the pthread_parallel_create() function,
-//   in all cluster containing at least one work thread. This array of barriers is another
-//   argument of the pthread_parallel_create() function.
+// WARNING : The function executed by the working thread is application specific,
+// but the structure defining the arguments passed to this function is imposed.
+// The "pthread_parallel_work_args_t" structure is defined below, and contains
+// two fields: the tid value, and a pointer on a pthread_barrier_t.
+// This barrier must be used by each working thread to signal completion before exit.
+// The global variables implementing these stuctures for each working thread
+// are allocated and initialised by the pthread_parallel_create() function.
 //
-// Implementation note:
-// To parallelize the "work" threads creation and termination, the pthread_parallel_create()
-// function creates a distributed quad-tree (DQT) of "build" threads covering all cores 
-// required to execute the parallel application. 
+// Implementation note: the pthread_parallel_create()a function creates a distributed
+// quad-tree (DQT) of <build> threads covering all cores required to execute the parallel
+// application. This quad tree is entirely defined by the root_level parameter. 
 // Depending on the hardware topology, this DQT can be truncated, (i.e. some
 // parent nodes can have less than 4 chidren), if (x_size != y_size), or if one size
-// is not a power of 2. Each "build" thread is identified by two indexes [cxy][level].
-// Each "build" thread makes the following tasks:
+// is not a power of 2. Each <build> thread is identified by two indexes [cid][level].
+// Each <build> thread makes the following tasks:
 // 1) It calls the pthread_create() function to create up to 4 children threads, that
-//    are are "work" threads when (level == 0), or "build" threads, when (level > 0).
-// 2) It initializes the barrier (global variable), used to block/unblock
-//    the parent thread until children completion.
+//    are <work> threads when (level == 0), or <build> threads, when (level > 0).
+// 2) It allocates and initializes the barrier, used to block the parent thread until
+//    children completion.
 // 3) It calls the pthread_barrier_wait( self ) to wait until all children threads
 //    completed (successfully or not).
@@ -495 +501 @@
 
 /*****************************************************************************************
- * This blocking function creates N working threads that execute the code defined
- * by the <work_func> and <work_args> arguments, and returns only when all working
- * threads completed.
- * The number N of created threads is entirely defined by the <root_level> argument.
- * This value defines an abstract quad-tree, with a square base : level in [0,1,2,3,4],
+ *    structure defining the arguments for the <build> thread function
+ ****************************************************************************************/
+typedef struct pthread_parallel_build_args_s           
+{
+    unsigned char        cid;                    // this <build> thread cluster index
+    unsigned char        level;                  // this <build> thread level in quad-tree
+    unsigned char        parent_cid;             // parent <build> thread cluster index
+    pthread_barrier_t  * parent_barrier;         // pointer on parent <build> thread barrier
+    unsigned char        root_level;             // quad-tree root level 
+    void               * work_func;              // pointer on working thread function
+    unsigned int         x_size;                 // platform global parameter
+    unsigned int         y_size;                 // platform global parameter
+    unsigned int         ncores;                 // platform global parameter
+    unsigned int         error;                  // return value : 0 if success 
+}
+pthread_parallel_build_args_t;
+
+/*****************************************************************************************
+ *    structure defining the arguments for the <work> thread function
+ ****************************************************************************************/
+typedef struct pthread_parallel_work_args_s           
+{
+    unsigned int         tid;                    // thread identifier
+    pthread_barrier_t  * barrier;                // to signal completion
+}
+pthread_parallel_work_args_t;           
+
+/*****************************************************************************************
+ * This blocking function creates N working threads identified by the [tid] continuous
+ * index, that execute the code defined by the <work_func> argument, and returns only 
+ * when all working threads completed.
+ * The number N of created threads is entirely defined by the <root_level> argument,
+ * that defines an abstract quad-tree, with a square base : root_level in [0,1,2,3,4],
  * side in [1,2,4,8,16], nclusters in [1,4,16,64,256]. This base is called  macro_cluster.
- * A working thread is created on all cores contained in the specified macro-cluster.
+ * A working thread is created on all cores contained in this abstract macro-cluster.
  * The actual number of physical clusters containing cores can be smaller than the number
- * of clusters covered by the quad tree. The actual number of cores in a cluster can be
- * less than the max value.
- *
- * In the current implementation, all threads execute the same <work_func> function,
- * on different arguments, that are specified as a 2D array of pointers <work_args>.
- * This can be modified in a future version, where the <work_func> argument can become
- * a 2D array of pointers, to have one specific function for each thread.
+ * of clusters covered by the abstract quad tree.
+ * All threads execute the same <work_func> function, on different arguments, that are 
+ * specified as an array of structures pthread_parallel_work_args_t, allocated and
+ * initialised by this function.
  *****************************************************************************************
  * @ root_level            : [in]  DQT root level in [0,1,2,3,4].
  * @ work_func             : [in]  pointer on start function.
- * @ work_args_array       : [in]  pointer on a 2D array of pointers.
- * @ parent_barriers_array : [in]  pointer on a 1D array of barriers.
  * @ return 0 if success / return -1 if failure.
  ****************************************************************************************/
-int pthread_parallel_create( unsigned int   root_level,
-                             void         * work_func,
-                             void         * work_args_array,
-                             void         * parent_barriers_array );
+int pthread_parallel_create( unsigned int         root_level,
+                             void               * work_func );
+
+
+
+
 
 /********* Non standard (ALMOS-MKH specific) Frame Buffer access syscalls   *************/