thread_parallel_runner.h (2459B)
1 /* Copyright (c) the JPEG XL Project Authors. All rights reserved. 2 * 3 * Use of this source code is governed by a BSD-style 4 * license that can be found in the LICENSE file. 5 */ 6 7 /** @addtogroup libjxl_threads 8 * @{ 9 * @file thread_parallel_runner.h 10 * @brief implementation using std::thread of a ::JxlParallelRunner. 11 */ 12 13 /** Implementation of JxlParallelRunner than can be used to enable 14 * multithreading when using the JPEG XL library. This uses std::thread 15 * internally and related synchronization functions. The number of threads 16 * created is fixed at construction time and the threads are re-used for every 17 * ThreadParallelRunner::Runner call. Only one concurrent 18 * JxlThreadParallelRunner call per instance is allowed at a time. 19 * 20 * This is a scalable, lower-overhead thread pool runner, especially suitable 21 * for data-parallel computations in the fork-join model, where clients need to 22 * know when all tasks have completed. 23 * 24 * This thread pool can efficiently load-balance millions of tasks using an 25 * atomic counter, thus avoiding per-task virtual or system calls. With 48 26 * hyperthreads and 1M tasks that add to an atomic counter, overall runtime is 27 * 10-20x higher when using std::async, and ~200x for a queue-based thread 28 */ 29 30 #ifndef JXL_THREAD_PARALLEL_RUNNER_H_ 31 #define JXL_THREAD_PARALLEL_RUNNER_H_ 32 33 #include <jxl/jxl_threads_export.h> 34 #include <jxl/memory_manager.h> 35 #include <jxl/parallel_runner.h> 36 #include <stddef.h> 37 #include <stdint.h> 38 #include <stdlib.h> 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /** Parallel runner internally using std::thread. Use as @ref JxlParallelRunner. 45 */ 46 JXL_THREADS_EXPORT JxlParallelRetCode JxlThreadParallelRunner( 47 void* runner_opaque, void* jpegxl_opaque, JxlParallelRunInit init, 48 JxlParallelRunFunction func, uint32_t start_range, uint32_t end_range); 49 50 /** Creates the runner for @ref JxlThreadParallelRunner. Use as the opaque 51 * runner. 52 */ 53 JXL_THREADS_EXPORT void* JxlThreadParallelRunnerCreate( 54 const JxlMemoryManager* memory_manager, size_t num_worker_threads); 55 56 /** Destroys the runner created by @ref JxlThreadParallelRunnerCreate. 57 */ 58 JXL_THREADS_EXPORT void JxlThreadParallelRunnerDestroy(void* runner_opaque); 59 60 /** Returns a default num_worker_threads value for 61 * @ref JxlThreadParallelRunnerCreate. 62 */ 63 JXL_THREADS_EXPORT size_t JxlThreadParallelRunnerDefaultNumWorkerThreads(void); 64 65 #ifdef __cplusplus 66 } 67 #endif 68 69 #endif /* JXL_THREAD_PARALLEL_RUNNER_H_ */ 70 71 /** @}*/