 |
GCGlib
0.04.228
GCG Graphics Engine
|
|
GCGlib
0.04.228
GCG Graphics Engine
|
Controls a pool of threads for executing multiple jobs concurrently. More...
#include <gcg.h>
Public Member Functions | |
| gcgTHREADPOOL (unsigned int numThreads=gcgGetNumberOfProcessors()) | |
| Constructs a valid object but no thread is created. If numthreads is non zero, calls setNumberOfThreads() to create the threads. More... | |
| virtual | ~gcgTHREADPOOL () |
| Deletes the object, releasing its resources. If the thread pool is executing, it calls waitAndDestroy() to finish all threads. The object destruction is delayed until all executing jobs are finished. Before deleting an gcgTHREADPOOL object, it is a good practice to ask all executing jobs to exit normally (synchronously). The pool is deleted only after all threads exit. The jobs still in the queue are deleted, or inserted in the discarded output queue, without being executed. Despite not recommended, call destroyPool() before destruction if a fast release is absolutely needed. More... | |
| bool | setNumberOfThreads (unsigned int numThreads=gcgGetNumberOfProcessors()) |
| Upon the first call, this method creates a job queue and starts numThreads threads that start picking jobs from the queue. If the pool is already running and working, it creates or stops threads until the number of threads as defined by numThreads is reached. if numThreads is 0, it calls waitAndDestroy() to stop the pool and release its resources. setNumberOfThreads() blocks until the number of threads is reached. This function is not allowed to be called by jobs being executed by the thread pool to avoid deadlock. More... | |
| unsigned int | getNumberOfThreads () |
| Gets the number of threads ready to work in the thread pool. Returns zero if the thread pool is not running or being destroyed, even if still there are threads that did not finished. More... | |
| bool | assignJob (gcgJOB *job) |
| Assigns a new job to the threadpool by inserting it in the queue and waking idle threads. job must be a valid instance of a class specializing gcgJOB. If the thread pool is not running (has no active threads), it returns false without changing the job. More... | |
| uintptr_t | getNumberOfPendingJobs () |
| Gets the number of jobs in the queue waiting to be executed by the thread pool. More... | |
| bool | wait () |
| Waits the queue to become empty and all threads to become idle. While waiting, however, new jobs can be inserted by calling assignJob(). This function is not allowed to be called by jobs executed by the thread pool to avoid deadlock. More... | |
| bool | waitAndDestroy () |
| Flags all threads to exit and waits them to stop. Pending jobs in the queue are discarded and, thus, not executed. The threads are not canceled. This means that the return of waitAndDestroy() occurs only after all current jobs in execution finish. Discarded jobs are inserted into the queue discarded defined by setOutputQueue(). If the output queue is NULL (default), the discarded job is deleted. This function is not allowed to be called by jobs executed by the thread pool to avoid deadlock. More... | |
| bool | destroyPool () |
| Cancel all threads and discards all pending jobs from the queue that are, thus, not executed. Thread cancellation is not a good practice since the jobs might be interrupted before releasing important resources and saving data. When stopping the threadpool, prefer a method using waitAndDestroy(), asking the executing jobs to exit normally (synchronously). Method destroyPool() cancel the threads and wait for their cancellation. In Windows systems, the threads cannot be assynchronously stopped, blocking the calling thread if the jobs do not return normally. In Linux, the sudden stop is not a good practice and may lead to memory leaks, deadlocks and unsaved data. The jobs still in the queue are discarded without being executed. Discarded jobs are inserted into the queue discarded defined by setOutputQueue(). If the output queue is NULL (default), the discarded job is deleted. This function is not allowed to be called by jobs executed by the thread pool to avoid deadlock. More... | |
| bool | setOutputQueue (gcgQUEUE *executed, gcgQUEUE *discarded=NULL) |
| Sets the output queues for executed and discarded jobs. The executed queue indicates where a job must be inserted after being executed. When a job exits, it is inserted in this queue for later control. If executed is NULL, any executed job is deleted. If any error is detected during execution (raised exceptions), or the job is not executed due to waitAndDestroy() or destroyPool() calls, it is inserted into the discarded queue. If discarded is NULL, the job is deleted. This functionality helps the output control of jobs. Both output queues are NULL by default. Once set up, the queues are preserved until thread pool destruction. More... | |
| bool | getOutputQueue (gcgQUEUE **pexecuted, gcgQUEUE **pdiscarded) |
| Gets the current output queues used for executed and discarded jobs. More... | |
| bool | isRunning () |
 Public Member Functions inherited from gcgCLASS | |
| void * | operator new (size_t size) |
| Defines a new operator to be used by instatiations of GCGlib classes instead the global one. More... | |
| void * | operator new (size_t size, const std::nothrow_t &) throw () |
| Defines a new operator to be used by instantiations of GCGlib classes instead the global one. Returns a NULL pointer instead of throwing an exception if an error occurs. More... | |
| void * | operator new[] (size_t size) |
| Defines a new operator to be used by GCGlib array allocations instead the global one. More... | |
| void * | operator new[] (size_t size, const std::nothrow_t &) throw () |
| Defines a new operator to be used by vector allocations instead the global one. More... | |
| void | operator delete (void *p) |
| Defines a delete operator to free instances of GCGlib classes instead the global one. It is designed to match the new operator. More... | |
| void | operator delete (void *p, const std::nothrow_t &) throw () |
| Defines a delete operator to free instances of GCGlib classes instead the global one. It is designed to match the new operator. More... | |
| void | operator delete[] (void *p) |
| Defines a delete operator to free instances of arrays for GCGlib classes instead the global one. It is designed to match the new[] operator. More... | |
| void | operator delete[] (void *p, const std::nothrow_t &) throw () |
| Defines a delete operator to free instances of arrays for GCGlib classes instead the global one. It is designed to match the new[] operator. More... | |
Public Attributes | |
| void * | handle |
| Internal handle of this object. | |
Controls a pool of threads for executing multiple jobs concurrently.
A thread pool is intended to reduce the overhead of creating threads. It works by allocating a number of threads that start waiting for jobs. When jobs (see gcgJOB) are assigned, they are inserted into a FIFO queue, and only one idle thread is waken up to process it. Threads might race to dequeue new jobs after finishing their jobs. If no new jobs are available, the thread puts itself again in a wait state. The thread that dequeue a job executes its gcgJOB:run(). When it finishes, the gcgJOB instance is deleted if a specific output queue is not given by the user. There are two possible output queues for jobs: executed, for successfully executed threads, and discarded, for jobs that raised any exception in gcgJOB:run(). If executed queue is not NULL, all jobs that did not raised exception are inserted into it. If executed is NULL (default), the finished job is deleted. If discarded queue is not NULL, all jobs that raised exceptions inside gcgJOB:run() are inserted into it. If discarded is NULL (default), the failed job is deleted. Also, if there are pending jobs in the FIFO queue, waiting to be executed, but the thread pool is destroyed by destroyPool() or waitAndDestroy(), they are all inserted into the discarded queue if it is not NULL. Otherwise all non executed jobs are deleted. Output queues are important features to create processing tool-chains.
| gcgTHREADPOOL::gcgTHREADPOOL | ( | unsigned int | numThreads = gcgGetNumberOfProcessors() | ) |
Constructs a valid object but no thread is created. If numthreads is non zero, calls setNumberOfThreads() to create the threads.
| [in] | numThreads | number of threads to be used for executing jobs. Greater the number of threads, higher is the capacity of the threadpool to execute jobs preemptively (but consuming more system resources). It may be zero. |
|
virtual |
Deletes the object, releasing its resources. If the thread pool is executing, it calls waitAndDestroy() to finish all threads. The object destruction is delayed until all executing jobs are finished. Before deleting an gcgTHREADPOOL object, it is a good practice to ask all executing jobs to exit normally (synchronously). The pool is deleted only after all threads exit. The jobs still in the queue are deleted, or inserted in the discarded output queue, without being executed. Despite not recommended, call destroyPool() before destruction if a fast release is absolutely needed.
| bool gcgTHREADPOOL::assignJob | ( | gcgJOB * | job | ) |
Assigns a new job to the threadpool by inserting it in the queue and waking idle threads. job must be a valid instance of a class specializing gcgJOB. If the thread pool is not running (has no active threads), it returns false without changing the job.
| [in] | job | an instance of a class specializing gcgJOB that must be executed by calling run(). A NULL value is not allowed. |
| bool gcgTHREADPOOL::destroyPool | ( | ) |
Cancel all threads and discards all pending jobs from the queue that are, thus, not executed. Thread cancellation is not a good practice since the jobs might be interrupted before releasing important resources and saving data. When stopping the threadpool, prefer a method using waitAndDestroy(), asking the executing jobs to exit normally (synchronously). Method destroyPool() cancel the threads and wait for their cancellation. In Windows systems, the threads cannot be assynchronously stopped, blocking the calling thread if the jobs do not return normally. In Linux, the sudden stop is not a good practice and may lead to memory leaks, deadlocks and unsaved data. The jobs still in the queue are discarded without being executed. Discarded jobs are inserted into the queue discarded defined by setOutputQueue(). If the output queue is NULL (default), the discarded job is deleted. This function is not allowed to be called by jobs executed by the thread pool to avoid deadlock.
| uintptr_t gcgTHREADPOOL::getNumberOfPendingJobs | ( | ) |
Gets the number of jobs in the queue waiting to be executed by the thread pool.
| unsigned int gcgTHREADPOOL::getNumberOfThreads | ( | ) |
Gets the number of threads ready to work in the thread pool. Returns zero if the thread pool is not running or being destroyed, even if still there are threads that did not finished.
Gets the current output queues used for executed and discarded jobs.
| [in] | pexecuted | a gcgQUEUE pointer address that will receive the queue for executed jobs. A NULL value is allowed. |
| [in] | pdiscarded | a gcgQUEUE pointer address that will receive the queue for discarded jobs. A NULL value is allowed. |
| bool gcgTHREADPOOL::isRunning | ( | ) |
Checks if the thread pool has threads running or waiting jobs. Returns immediately.
| bool gcgTHREADPOOL::setNumberOfThreads | ( | unsigned int | numThreads = gcgGetNumberOfProcessors() | ) |
Upon the first call, this method creates a job queue and starts numThreads threads that start picking jobs from the queue. If the pool is already running and working, it creates or stops threads until the number of threads as defined by numThreads is reached. if numThreads is 0, it calls waitAndDestroy() to stop the pool and release its resources. setNumberOfThreads() blocks until the number of threads is reached. This function is not allowed to be called by jobs being executed by the thread pool to avoid deadlock.
| [in] | numThreads | number of threads to be used for executing jobs. Greater the number of threads, higher is the capacity of the threadpool to execute jobs preemptively (but consuming more system resources). If the current number of threads is greather than numThreads, threads that finish their jobs exit until numThreads threads is reached. Otherwise, the number of threads is increased to match numThreads. If numThreads is zero, the pool is destroyed by calling waitAndDestroy(). |
Sets the output queues for executed and discarded jobs. The executed queue indicates where a job must be inserted after being executed. When a job exits, it is inserted in this queue for later control. If executed is NULL, any executed job is deleted. If any error is detected during execution (raised exceptions), or the job is not executed due to waitAndDestroy() or destroyPool() calls, it is inserted into the discarded queue. If discarded is NULL, the job is deleted. This functionality helps the output control of jobs. Both output queues are NULL by default. Once set up, the queues are preserved until thread pool destruction.
| [in] | executed | a gcgQUEUE instance into which executed jobs must be inserted. If NULL, the output is disabled and all executed jobs are deleted. |
| [in] | discarded | a gcgQUEUE instance into which discarded jobs must be inserted. Discarded jobs are those that could not be executed due to errors (raised exception) or due to destruction by waitAndDestroy() or destroyPool(). If NULL, the output is disabled and all discarded jobs are deleted. |
| bool gcgTHREADPOOL::wait | ( | ) |
Waits the queue to become empty and all threads to become idle. While waiting, however, new jobs can be inserted by calling assignJob(). This function is not allowed to be called by jobs executed by the thread pool to avoid deadlock.
| bool gcgTHREADPOOL::waitAndDestroy | ( | ) |
Flags all threads to exit and waits them to stop. Pending jobs in the queue are discarded and, thus, not executed. The threads are not canceled. This means that the return of waitAndDestroy() occurs only after all current jobs in execution finish. Discarded jobs are inserted into the queue discarded defined by setOutputQueue(). If the output queue is NULL (default), the discarded job is deleted. This function is not allowed to be called by jobs executed by the thread pool to avoid deadlock.
1.8.13