1 /*! 2 * \file sccp_threadpool.h 3 * \brief SCCP Threadpool Header 4 * \author Diederik de Groot < ddegroot@users.sourceforge.net > 5 * \note This program is free software and may be modified and distributed under the terms of the GNU Public License. 6 * See the LICENSE file at the top of the source tree. 7 * \note Based on the work of Johan Hanssen Seferidis 8 * Library providing a threading pool where you can add work. 9 * \since 2009-01-16 10 */ 11 #pragma once 12 //#include "config.h" 13 //#include "common.h" 14 15 __BEGIN_C_EXTERN__ 16 /* Description: Library providing a threading pool where you can add work on the fly. The number 17 * of threads in the pool is adjustable when creating the pool. In most cases 18 * this should equal the number of threads supported by your cpu. 19 * 20 * In this header file a detailed overview of the functions and the threadpool logical 21 * scheme is present in case tweaking of the pool is needed. 22 * */ 23 24 /* 25 * Fast reminders: 26 * 27 * tp = threadpool 28 * sccp_threadpool = threadpool 29 * sccp_threadpool_t = threadpool type 30 * tp_p = threadpool pointer 31 * xN = x can be any string. N stands for amount 32 * 33 * */ 34 35 /* _______________________________________________________ 36 * / \ 37 * | JOB QUEUE | job1 | job2 | job3 | job4 | .. | 38 * | | 39 * | threadpool | thread1 | thread2 | .. | 40 * \_______________________________________________________/ 41 * 42 * Description: Jobs are added to the job queue. Once a thread in the pool 43 * is idle, it is assigned with the first job from the queue(and 44 * erased from the queue). It's each thread's job to read from 45 * the queue serially(using lock) and executing each job 46 * until the queue is empty. 47 * 48 */ 49 /* ================================= STRUCTURES ================================================ */ 50 51 /* Individual job */ 52 typedef struct sccp_threadpool_job sccp_threadpool_job_t; 53 54 struct sccp_threadpool_job { 55 void *(*function) (void *arg); /*!< function pointer */ 56 void *arg; /*!< function's argument */ 57 SCCP_LIST_ENTRY (sccp_threadpool_job_t) list; 58 }; 59 60 /* =========================== FUNCTIONS ================================================ */ 61 62 /* ----------------------- Threadpool specific --------------------------- */ 63 64 /*! 65 * \brief Initialize threadpool 66 * 67 * Allocates memory for the threadpool, jobqueue, semaphore and fixes 68 * pointers in jobqueue. 69 * 70 * \param threadsN number of threads to be used 71 * \return threadpool struct on success, 72 * NULL on error 73 */ 74 SCCP_API sccp_threadpool_t * SCCP_CALL sccp_threadpool_init(int threadsN); 75 76 /*! 77 * \brief Add work to the job queue 78 * 79 * Takes an action and its argument and adds it to the threadpool's job queue. 80 * If you want to add to work a function with more than one arguments then 81 * a way to implement this is by passing a pointer to a structure. 82 * 83 * ATTENTION: You have to cast both the function and argument to not get warnings. 84 * 85 * \param tp_p threadpool to which the work will be added to 86 * \param function_p callback function to add as work 87 * \param arg_p argument to the above function 88 * \return int 89 */ 90 SCCP_API int sccp_threadpool_add_work(sccp_threadpool_t * SCCP_CALL tp_p, void *(*function_p) (void *), void *arg_p); 91 92 /*! 93 * \brief Destroy the threadpool 94 * 95 * This will 'kill' the threadpool and free up memory. If threads are active when this 96 * is called, they will finish what they are doing and then they will get destroyied. 97 * 98 * \param tp_p threadpool a pointer to the threadpool structure you want to destroy 99 */ 100 SCCP_API boolean_t SCCP_CALL sccp_threadpool_destroy(sccp_threadpool_t * tp_p); 101 102 /*! 103 * \brief Return number of currently allocate threads in the threadpool 104 * \param tp_p threadpool a pointer to the threadpool structure for which we would like to know the number of workers 105 */ 106 SCCP_API int __PURE__ SCCP_CALL sccp_threadpool_thread_count(sccp_threadpool_t * tp_p); 107 108 /* ------------------------- Queue specific ------------------------------ */ 109 110 /*! 111 * \brief Initialize queue 112 * \param tp_p pointer to threadpool 113 * \return 0 on success, 114 * -1 on memory allocation error 115 */ 116 SCCP_API int SCCP_CALL sccp_threadpool_jobqueue_init(sccp_threadpool_t * tp_p); 117 118 /*! 119 * \brief Add job to queue 120 * 121 * A new job will be added to the queue. The new job MUST be allocated 122 * before passed to this function or else other functions like sccp_threadpool_jobqueue_empty() 123 * will be broken. 124 * 125 * \param tp_p pointer to threadpool 126 * \param newjob_p pointer to the new job(MUST BE ALLOCATED) 127 * \return nothing 128 */ 129 SCCP_API void SCCP_CALL sccp_threadpool_jobqueue_add(sccp_threadpool_t * tp_p, sccp_threadpool_job_t * newjob_p); 130 131 /*! 132 * \brief Return Number of Jobs in the Queue 133 * \param tp_p pointer to threadpool 134 */ 135 SCCP_API int SCCP_CALL sccp_threadpool_jobqueue_count(sccp_threadpool_t * tp_p); 136 __END_C_EXTERN__ 137 // kate: indent-width 8; replace-tabs off; indent-mode cstyle; auto-insert-doxygen on; line-numbers on; tab-indents on; keep-extra-spaces off; auto-brackets off; 138