cthpool2 Files

Author: Tamas K Lengyel, Johan Hanssen Seferidis
Created: 2011-08-12
Updated: 2012-10-16


=================================== Compiling =====================================

  ./configure
  make
  make check

  (optionally) make install


====================================== Linking =====================================

If you want to link with the library, pass the -lthpool flag to your compiler.

For example: gcc mycode.c -lthpool -lpthread -o myprogram

================================ Basic Usage  ======================================

1. Make a thread pool:                       thpool_t* thpool;
2. Initialise the thread pool with number
   of threads(workers) you want:             thpool=thpool_init(4);
3. Add work to the pool:                     thpool_add_work(thpool, (void*)doSth, (void*)arg, 0, NULL);
4. Destroy pool:                             thpool_destroy(thpool);

=============================== Threadpool Interface ===============================


NAME
     thpool_t* thpool_init(int num_of_threads);

SYNOPSIS
  
     #include <thpool.h>

     thpool_t* thpool_init(int num_of_threads);

DESCRIPTION

     Initialises the threadpool. On success a threadpool structure is returned. Otherwise if memory could not be allocated NULL is returned. The argument which is the number of threads in the threadpool should be a thoughfull choice. A common suggestion is to use as many threads as the ones supported by your cpu.

     Example:
     thpool_t* myThreadpool;                 //First we declare a threadpool
     myThreadpool=thpool_init(4);            //then we initialise it to 4 threads


-----------------------------------------------------------------------------------



NAME
     thpool_add_work(thpool_t* thpool, void *(*function_p)(void*), void* arg_p, unsigned int priority, pthread_cond_t *cond);

SYNOPSIS
  
     #include <thpool.h>

     int thpool_add_work(thpool_t* thpool, void *(*function_p)(void*), void* arg_p, unsigned int priority, pthread_cond_t *cond);

DESCRIPTION

     Adds work to the thread pool. Work is concidered an individual function with an argument. First argument is a pointer to the pool itself. The second argument is a pointer to a function and third argument is a pointer to an argument. To pass multiple arguments just use a struct. If the function you want to pass doesn't fit the parameters of this prototype, use casting. If your function or argument doesn't fit the parameters' and return's value type then you should use casting to avoid warnings from the compiler.

     Example:
	void printSth(char* str);                                 	     //Prints a text on the screen
	thpool_add_work(thpool, (void*)printSth, (void*)str, 0, NULL);  //Pay attention to the casting

     Priority example:
	thpool_add_work(thpool, (void*)printSth, (void*)str,100,NULL);  // Higher the number, the sooner the job will be scheduled

     Signal example (if you want to be notified when the job finished):
	pthread_mutex_t mutex;
        pthread_cond_t  cond;
        pthread_mutex_init(&mutex, NULL);
        pthread_cond_init(&cond,NULL);
        pthread_mutex_lock(&mutex);
     	thpool_add_work(thpool, (void*)printSth, (void*)str, 0, &cond);
	pthread_cond_wait(&cond); // will be blocked until the job finishes
     
-----------------------------------------------------------------------------------


NAME
     void thpool_destroy(thpool_t* tp_p);

SYNOPSIS
  
     #include <thpool.h>

     void thpool_destroy(thpool_t* tp_p);

DESCRIPTION

     This function will destroy a threadpool. If some threads are working in the pool then thpool_destroy() will wait for them to finish. Once they are finished the threadpool is deallocated releasing all resources back to the system.

     Example:
     thpool_destroy(threadpool_p);           //threadpool_p being a pointer to a thpool_t