1 #pragma once 2 #ifndef IWTP_H 3 #define IWTP_H 4 5 /************************************************************************************************** 6 * Threads pool. 7 * 8 * IOWOW library 9 * 10 * MIT License 11 * 12 * Copyright (c) 2012-2022 Softmotions Ltd <info@softmotions.com> 13 * 14 * Permission is hereby granted, free of charge, to any person obtaining a copy 15 * of this software and associated documentation files (the "Software"), to deal 16 * in the Software without restriction, including without limitation the rights 17 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 18 * copies of the Software, and to permit persons to whom the Software is 19 * furnished to do so, subject to the following conditions: 20 * 21 * The above copyright notice and this permission notice shall be included in all 22 * copies or substantial portions of the Software. 23 * 24 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 25 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 26 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 27 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 28 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 29 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 30 * SOFTWARE. 31 *************************************************************************************************/ 32 33 #include "basedefs.h" 34 35 IW_EXTERN_C_START 36 37 struct iwtp; 38 typedef struct iwtp*IWTP; 39 40 struct iwtp_spec { 41 /** Optional thread name prefix in thread pool. 42 * @note Thread name length must be not greater then 15 characters. 43 */ 44 const char *thread_name_prefix; 45 46 /** Number of hot threads in thread pool. 47 * Threads are allocated on when thread pool created. 48 * @note Value must be in rage [1-1024]. 49 * @note If zero then value will be set to number of cpu cores. 50 */ 51 int num_threads; 52 53 /** Maximum number of tasks in queue. 54 Zero for unlimited queue. */ 55 int queue_limit; 56 57 /** If task queue is full and the `overflow_threads_factor` is not zero 58 * then pool is allowed to spawn extra threads to process tasks as long 59 * as overall number of threads less of equal to `num_threads * overflow_threads_factor` 60 * @note Max: 2 61 */ 62 int overflow_threads_factor; 63 64 /** 65 * It true performs log warning in the case of spawning overflow thread. 66 */ 67 bool warn_on_overflow_thread_spawn; 68 }; 69 70 /** 71 * @brief Task to execute 72 */ 73 typedef void (*iwtp_task_f)(void *arg); 74 75 /** 76 * @brief Creates a new thread pool instance using provided `spec` config. 77 */ 78 IW_EXPORT iwrc iwtp_start_by_spec(const struct iwtp_spec *spec, IWTP *out_tp); 79 80 /** 81 * @brief Creates a new thread pool instance. 82 * @param num_threads Number of threads in the pool, accepted values in range `[1-1024]` 83 * @param queue_limit Maximum number of tasks in queue. Zero for unlimited queue. 84 * @param [out] out_tp Holder for thread pool instance. 85 */ 86 IW_EXPORT iwrc iwtp_start(const char *thread_name_prefix, int num_threads, int queue_limit, IWTP *out_tp); 87 88 /** 89 * @brief Submits new task into thread pool. 90 * @note `IW_ERROR_INVALID_STATE` if called after `iwtp_shutdown()`. 91 * @note `IW_ERROR_OVERFLOW` if size of tasks queue reached `queue_limit`. 92 * @param tp Pool instance 93 * @param task Task function 94 * @param task_arg Argument for task function 95 */ 96 IW_EXPORT iwrc iwtp_schedule(IWTP tp, iwtp_task_f task, void *task_arg); 97 98 /** 99 * @brief Shutdowns thread pool and disposes all nresources. 100 * @note Function will wait until current task completes or 101 * wait for all enqueued tasks if `wait_for_all` is set to `true`. 102 * No new tasks will be accepted during `iwstw_shutdown` call. 103 104 * @param tpp Pointer to pool which should be disposed. 105 * @param wait_for_all If true worker will wait for completion of all enqueued tasks before shutdown. 106 */ 107 IW_EXPORT iwrc iwtp_shutdown(IWTP *tpp, bool wait_for_all); 108 109 /** 110 * @brief Returns size of tasks queue. 111 */ 112 IW_EXPORT int iwtp_queue_size(IWTP tp); 113 114 IW_EXTERN_C_END 115 #endif 116