MAGMA  2.7.1
Matrix Algebra for GPU and Multicore Architectures
magma_thread_queue Class Reference

TODO: replace with OpenMP tasks. More...

Public Member Functions

 magma_thread_queue ()
 Creates queue with NO threads. More...
 
 ~magma_thread_queue ()
 Calls quit(), then deallocates data.
 
void launch (magma_int_t in_nthread)
 Creates threads. More...
 
void push_task (magma_task *task)
 Add task to queue. More...
 
void sync ()
 Block until all outstanding tasks have been finished. More...
 
void quit ()
 Sets quit_flag, so pop_task() will return NULL once queue is empty, telling threads to exit. More...
 

Protected Member Functions

magma_taskpop_task ()
 Get next task from queue. More...
 
void task_done ()
 Marks task as finished, decrementing number of outstanding tasks. More...
 
magma_int_t get_thread_index (pthread_t thread) const
 Mostly for debugging, returns thread index in range 0, ..., nthread-1.
 

Friends

void * magma_thread_main (void *arg)
 Thread's main routine, executed by pthread_create. More...
 

Detailed Description

TODO: replace with OpenMP tasks.

Implements a thread pool with a multi-producer, multi-consumer queue.

Typical use: A main thread creates the queue and tells it to launch worker threads. Then the main thread inserts (pushes) tasks into the queue. Threads will execute the tasks. No dependencies are tracked. The main thread can sync the queue, waiting for all current tasks to finish, and then insert more tasks into the queue. When finished, the main thread calls quit or simply destructs the queue, which will exit all worker threads.

Tasks are sub-classes of magma_task. They must implement the run() function.

Example

class task1: public magma_task {
public:
task1( int arg ):
m_arg( arg ) {}
virtual void run() { do_task1( m_arg ); }
private:
int m_arg;
};
class task2: public magma_task {
public:
task2( int arg1, int arg2 ):
m_arg1( arg1 ), m_arg2( arg2 ) {}
virtual void run() { do_task2( m_arg1, m_arg2 ); }
private:
int m_arg1, m_arg2;
};
void master( int n ) {
queue.launch( 12 ); // 12 worker threads
for( int i=0; i < n; ++i ) {
queue.push_task( new task1( i ));
}
queue.sync(); // wait for all task1 to finish before doing task2.
for( int i=0; i < n; ++i ) {
for( int j=0; j < i; ++j ) {
queue.push_task( new task2( i, j ));
}
}
queue.quit(); // [optional] explicitly exit worker threads
}

This is similar to python's queue class, but also implements worker threads and adds quit() mechanism. sync() is like python's join, but threads do not exit, so join would be a misleading name.

Constructor & Destructor Documentation

◆ magma_thread_queue()

magma_thread_queue::magma_thread_queue ( )

Creates queue with NO threads.

Use launch() to create threads.

Member Function Documentation

◆ launch()

void magma_thread_queue::launch ( magma_int_t  in_nthread)

Creates threads.

Parameters
[in]in_nthreadNumber of threads to launch.

◆ push_task()

void magma_thread_queue::push_task ( magma_task task)

Add task to queue.

Task must be allocated with C++ new. Increments number of outstanding tasks. Signals threads that are waiting in pop_task().

Parameters
[in]taskTask to queue.

◆ sync()

void magma_thread_queue::sync ( )

Block until all outstanding tasks have been finished.

Threads continue to be alive; more tasks can be pushed after sync.

◆ quit()

void magma_thread_queue::quit ( )

Sets quit_flag, so pop_task() will return NULL once queue is empty, telling threads to exit.

Signals all threads that are waiting in pop_task(). Waits for all threads to exit (i.e., joins them). It is safe to call quit multiple times – the first time all the threads are joined; subsequent times it does nothing. (Destructor also calls quit, but you may prefer to call it explicitly.)

◆ pop_task()

magma_task * magma_thread_queue::pop_task ( )
protected

Get next task from queue.

Returns
next task, blocking until a task is inserted if necesary.
NULL if queue is empty and quit() has been called.

This does not decrement number of outstanding tasks; thread should call task_done() when task is completed.

◆ task_done()

void magma_thread_queue::task_done ( )
protected

Marks task as finished, decrementing number of outstanding tasks.

Signals threads that are waiting in sync().

Friends And Related Function Documentation

◆ magma_thread_main

void* magma_thread_main ( void *  arg)
friend

Thread's main routine, executed by pthread_create.

Executes tasks from queue (given as arg), until a NULL task is returned. Deletes each task when it is done.

Parameters
[in,out]argmagma_thread_queue to get tasks from.

The documentation for this class was generated from the following files: