| /* |
| * Implements dynamic task queues to provide load balancing |
| * Sanjeev Kumar --- December, 2004 |
| */ |
| |
| #ifndef __TASKQ_H__ |
| #define __TASKQ_H__ |
| |
| #ifdef __cplusplus |
| # define __BEGIN_DECLS extern "C" { |
| # define __END_DECLS } |
| #else |
| # define __BEGIN_DECLS |
| # define __END_DECLS |
| #endif |
| |
| |
| #define MAX_DIMENSION 3 |
| |
| __BEGIN_DECLS |
| |
| // An identifier that uniquely identifies a thread. The TaskQThreadId for the |
| // main thread is 0. The TaskQThreadId ranges from 0 to "numThreads-1". So it |
| // can be used to index arrays. |
| |
| typedef long TaskQThreadId; |
| |
| // A task is a unit of work. A task has two componenets: A function (called |
| // "task function" and a set of arguments (called "task arguments"). They |
| // following are valid types for a task function. When the task is executed |
| // by the run time library, it executes the task function with the task's |
| // arguments. In addition, it provides a threadId. |
| // Note: The threadId that is provided to the task function (identity of the |
| // thread executing the task) is not necessarily the same as the threadId |
| // that was supplied to the taskQEnqueue function (which is the identity of |
| // the thread enqueuing the task). |
| |
| typedef void *TaskQTask; // Generic task type |
| typedef void (*TaskQTask1) (TaskQThreadId threadId, void *arg1); |
| typedef void (*TaskQTask2) (TaskQThreadId threadId, void *arg1, void *arg2); |
| typedef void (*TaskQTask3) (TaskQThreadId threadId, void *arg1, void *arg2, void *arg3); |
| |
| // These functions can be used to set the parameters in the task queue |
| // implementations. The different parameters affect different |
| // implementations. Setting a parameter that is specific a particular |
| // implementation is treated as a "nop" (as is therefore harmless) on the |
| // other implementations. |
| // These have to be called before TaskQInit to have an effect. |
| // Usually you don't have to use this function---the default values will work |
| // just fine. |
| |
| enum TaskQParam { TaskQInvalidParam, |
| // parameters for Distributed implementations |
| TaskQThreadsPerQueue, // Number of threads per queue (default=1) |
| // End of parameters |
| TaskQNumParams |
| }; |
| |
| void taskQSetParam (enum TaskQParam param, long value); |
| long taskQGetParam (enum TaskQParam param); |
| |
| // This function initializes the taskQ library and starts the worker threads. |
| // This has to be called before calling any other taskQ functions (Except the |
| // taskQ functions that set the various parameters). |
| // numThreads: Total number of parallel threads (including the main |
| // thread) |
| // maxTasks: The maximum number of tasks that can be in the taskQ at any |
| // point. Bad things happen when you specify this wrong (understate it). |
| // This should be executed only once and that too by the main thread. |
| |
| void taskQInit (int numThreads, int maxTasks); |
| |
| // These functions are used to enqueue a task. You have to call the |
| // appropriate function depending on whether your task function takes 1, 2, |
| // or 3 arguments. |
| // taskFunction: The task function |
| // threadId: This should be the TaskQThreadId of the thread that is |
| // enqueuing the task (as stated above). Note: It cannot be used to |
| // specify the thread you want the task to executed on. |
| // args[1..3]: The task arguments |
| |
| void taskQEnqueueTask1 (TaskQTask1 taskFunction, TaskQThreadId threadId, void *arg1); |
| void taskQEnqueueTask2 (TaskQTask2 taskFunction, TaskQThreadId threadId, void *arg1, void *arg2); |
| void taskQEnqueueTask3 (TaskQTask3 taskFunction, TaskQThreadId threadId, void *arg1, void *arg2, void *arg3); |
| |
| // This function is used to enqueue a set of tasks at once. Suppose |
| // you are operating on a grid (with at most MAX_DIMENSIONS). If you |
| // want to break down the grid into tiles where each tile is an |
| // independant task, you can enqueue all the tasks at once. |
| // taskFunction: The task function. To satisfy the C type system, a type |
| // cast should be used. For instance, if the numDimensions is 2, then |
| // a task function (say taskFn2) of type TaskQTask2 should be defined |
| // and cast into TaskQTask when it is supplied as an argument to |
| // taskQEnqueueGrid. |
| // numDimensions: The number of dimensions in the grid. |
| // dimensionSize: Size of the grid in each dimension. Only indices 0 to |
| // numDimensions-1 need to have valid values. |
| // tileSize: Size of the tile in each dimension. Only indices 0 to |
| // numDimensions-1 need to have valid values. |
| |
| void taskQEnqueueGrid (TaskQTask taskFuntion, TaskQThreadId threadId, long numDimensions, |
| long dimensionSize[MAX_DIMENSION], long tileSize[MAX_DIMENSION]); |
| |
| // This function is used to wait for all the tasks that have been enqueued to |
| // be compeleted. |
| // Implementation Note: Currently, the worker threads (as well as the main |
| // thread) start executing the tasks only after the taskQWait function is |
| // invoked by the main thread. This might change in the future and so a |
| // program should not rely on this for correctness. However, this is stated |
| // here because it is sometimes easier to understand the behavior and |
| // performance of the program when you know this. |
| // This should be executed only by the main thread. |
| |
| void taskQWait (void); |
| |
| // This function returns a rough estimate of the number of tasks |
| // that are currently queued up in the task queues. |
| // Note 1: This is just a hint. |
| // Note 2: This is currently implemented only for the Central Queues. |
| // Note 3: This is an experimental feature and might disappear in the future. |
| |
| int taskQPendingTasksHint (void); |
| |
| // This function performs clean up actions and should be the last taskQ |
| // function to be executed by the program. |
| // This should be executed only once and that too by the main thread. |
| |
| void taskQEnd (void); |
| |
| // These functions reset and print some statistics collected by taskQ library. |
| // This should be executed only by the main thread. |
| |
| void taskQResetStats (void); |
| void taskQPrnStats (void); |
| |
| __END_DECLS |
| |
| // These macros can be used to eliminate task queueing code entirely from |
| // the program. This is useful to measure the performance of the serial |
| // version of the program without any task queuing overhead. These work only |
| // for the Baseline and the Grid flavors of task queues. |
| |
| #ifdef SERIAL_TASKQ |
| |
| #define taskQInit(nt,mt) { if ( nt != 1) { printf( "ERROR: Serial version. numThreads should be 1\n"); exit(1); } } |
| #define taskQEnqueueTask1(tf,tId,a) { (tf)(0,a); } |
| #define taskQEnqueueTask2(tf,tId,a,b) { (tf)(0,a,b); } |
| #define taskQEnqueueTask3(tf,tId,a,b,c) { (tf)(0,a,b,c); } |
| #define taskQWait() |
| #define taskQResetStats() |
| #define taskQPrintStats() |
| #define taskQEnd() |
| |
| #define taskQEnqueueGrid(tf,tId,nd,max,step) { \ |
| if ( MAX_DIMENSION != 3) { \ |
| printf( "ERROR: Serial version not implemented for MAX_DIMENSION != 3.\n"); \ |
| exit(1); \ |
| } \ |
| long __TQ__i, __TQ__j[MAX_DIMENSION], __TQ__max[MAX_DIMENSION], __TQ__step[MAX_DIMENSION]; \ |
| for ( __TQ__i = 0; __TQ__i < MAX_DIMENSION; __TQ__i++) { \ |
| if ( __TQ__i < nd) { \ |
| __TQ__max[__TQ__i] = max[__TQ__i]; \ |
| __TQ__step[__TQ__i] = step[__TQ__i]; \ |
| } else { \ |
| __TQ__max[__TQ__i] = 1; \ |
| __TQ__step[__TQ__i] = 1; \ |
| } \ |
| } \ |
| for ( __TQ__j[0] = 0; __TQ__j[0] < __TQ__max[0]; __TQ__j[0] += __TQ__step[0]) { \ |
| for ( __TQ__j[1] = 0; __TQ__j[1] < __TQ__max[1]; __TQ__j[1] += __TQ__step[1]) { \ |
| for ( __TQ__j[2] = 0; __TQ__j[2] < __TQ__max[2]; __TQ__j[2] += __TQ__step[2]) { \ |
| tf( 0, ( void *)__TQ__j[0], ( void *)__TQ__j[1], ( void *)__TQ__j[2]); \ |
| } \ |
| } \ |
| } \ |
| } |
| |
| #endif |
| |
| #endif |
| |
