Advertisement
linux

thpool.h

Jul 16th, 2018
113
0
Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
C 4.71 KB | None | 0 0
  1. /**********************************
  2.  * @author      Johan Hanssen Seferidis
  3.  * License:     MIT
  4.  *
  5.  **********************************/
  6.  
  7. #ifndef _THPOOL_
  8. #define _THPOOL_
  9.  
  10. #ifdef __cplusplus
  11. extern "C" {
  12. #endif
  13.  
  14. /* =================================== API ======================================= */
  15.  
  16.  
  17. typedef struct thpool_* threadpool;
  18.  
  19.  
  20. /**
  21.  * @brief  Initialize threadpool
  22.  *
  23.  * Initializes a threadpool. This function will not return untill all
  24.  * threads have initialized successfully.
  25.  *
  26.  * @example
  27.  *
  28.  *    ..
  29.  *    threadpool thpool;                     //First we declare a threadpool
  30.  *    thpool = thpool_init(4);               //then we initialize it to 4 threads
  31.  *    ..
  32.  *
  33.  * @param  num_threads   number of threads to be created in the threadpool
  34.  * @return threadpool    created threadpool on success,
  35.  *                       NULL on error
  36.  */
  37. threadpool thpool_init(int num_threads);
  38.  
  39.  
  40. /**
  41.  * @brief Add work to the job queue
  42.  *
  43.  * Takes an action and its argument and adds it to the threadpool's job queue.
  44.  * If you want to add to work a function with more than one arguments then
  45.  * a way to implement this is by passing a pointer to a structure.
  46.  *
  47.  * NOTICE: You have to cast both the function and argument to not get warnings.
  48.  *
  49.  * @example
  50.  *
  51.  *    void print_num(int num){
  52.  *       printf("%d\n", num);
  53.  *    }
  54.  *
  55.  *    int main() {
  56.  *       ..
  57.  *       int a = 10;
  58.  *       thpool_add_work(thpool, (void*)print_num, (void*)a);
  59.  *       ..
  60.  *    }
  61.  *
  62.  * @param  threadpool    threadpool to which the work will be added
  63.  * @param  function_p    pointer to function to add as work
  64.  * @param  arg_p         pointer to an argument
  65.  * @return 0 on successs, -1 otherwise.
  66.  */
  67. int thpool_add_work(threadpool, void (*function_p)(void*), void* arg_p);
  68.  
  69.  
  70. /**
  71.  * @brief Wait for all queued jobs to finish
  72.  *
  73.  * Will wait for all jobs - both queued and currently running to finish.
  74.  * Once the queue is empty and all work has completed, the calling thread
  75.  * (probably the main program) will continue.
  76.  *
  77.  * Smart polling is used in wait. The polling is initially 0 - meaning that
  78.  * there is virtually no polling at all. If after 1 seconds the threads
  79.  * haven't finished, the polling interval starts growing exponentially
  80.  * untill it reaches max_secs seconds. Then it jumps down to a maximum polling
  81.  * interval assuming that heavy processing is being used in the threadpool.
  82.  *
  83.  * @example
  84.  *
  85.  *    ..
  86.  *    threadpool thpool = thpool_init(4);
  87.  *    ..
  88.  *    // Add a bunch of work
  89.  *    ..
  90.  *    thpool_wait(thpool);
  91.  *    puts("All added work has finished");
  92.  *    ..
  93.  *
  94.  * @param threadpool     the threadpool to wait for
  95.  * @return nothing
  96.  */
  97. void thpool_wait(threadpool);
  98.  
  99.  
  100. /**
  101.  * @brief Pauses all threads immediately
  102.  *
  103.  * The threads will be paused no matter if they are idle or working.
  104.  * The threads return to their previous states once thpool_resume
  105.  * is called.
  106.  *
  107.  * While the thread is being paused, new work can be added.
  108.  *
  109.  * @example
  110.  *
  111.  *    threadpool thpool = thpool_init(4);
  112.  *    thpool_pause(thpool);
  113.  *    ..
  114.  *    // Add a bunch of work
  115.  *    ..
  116.  *    thpool_resume(thpool); // Let the threads start their magic
  117.  *
  118.  * @param threadpool    the threadpool where the threads should be paused
  119.  * @return nothing
  120.  */
  121. void thpool_pause(threadpool);
  122.  
  123.  
  124. /**
  125.  * @brief Unpauses all threads if they are paused
  126.  *
  127.  * @example
  128.  *    ..
  129.  *    thpool_pause(thpool);
  130.  *    sleep(10);              // Delay execution 10 seconds
  131.  *    thpool_resume(thpool);
  132.  *    ..
  133.  *
  134.  * @param threadpool     the threadpool where the threads should be unpaused
  135.  * @return nothing
  136.  */
  137. void thpool_resume(threadpool);
  138.  
  139.  
  140. /**
  141.  * @brief Destroy the threadpool
  142.  *
  143.  * This will wait for the currently active threads to finish and then 'kill'
  144.  * the whole threadpool to free up memory.
  145.  *
  146.  * @example
  147.  * int main() {
  148.  *    threadpool thpool1 = thpool_init(2);
  149.  *    threadpool thpool2 = thpool_init(2);
  150.  *    ..
  151.  *    thpool_destroy(thpool1);
  152.  *    ..
  153.  *    return 0;
  154.  * }
  155.  *
  156.  * @param threadpool     the threadpool to destroy
  157.  * @return nothing
  158.  */
  159. void thpool_destroy(threadpool);
  160.  
  161.  
  162. /**
  163.  * @brief Show currently working threads
  164.  *
  165.  * Working threads are the threads that are performing work (not idle).
  166.  *
  167.  * @example
  168.  * int main() {
  169.  *    threadpool thpool1 = thpool_init(2);
  170.  *    threadpool thpool2 = thpool_init(2);
  171.  *    ..
  172.  *    printf("Working threads: %d\n", thpool_num_threads_working(thpool1));
  173.  *    ..
  174.  *    return 0;
  175.  * }
  176.  *
  177.  * @param threadpool     the threadpool of interest
  178.  * @return integer       number of threads working
  179.  */
  180. int thpool_num_threads_working(threadpool);
  181.  
  182.  
  183. #ifdef __cplusplus
  184. }
  185. #endif
  186.  
  187. #endif
Advertisement
Add Comment
Please, Sign In to add comment
Advertisement