parallel_runner.h (6843B)
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 */ 10 /** 11 * @file parallel_runner.h 12 */ 13 14 /** API for running data operations in parallel in a multi-threaded environment. 15 * This module allows the JPEG XL caller to define their own way of creating and 16 * assigning threads. 17 * 18 * The JxlParallelRunner function type defines a parallel data processing 19 * runner that may be implemented by the caller to allow the library to process 20 * in multiple threads. The multi-threaded processing in this library only 21 * requires to run the same function over each number of a range, possibly 22 * running each call in a different thread. The JPEG XL caller is responsible 23 * for implementing this logic using the thread APIs available in their system. 24 * For convenience, a C++ implementation based on std::thread is provided in 25 * jpegxl/parallel_runner_thread.h (part of the jpegxl_threads library). 26 * 27 * Thread pools usually store small numbers of heterogeneous tasks in a queue. 28 * When tasks are identical or differ only by an integer input parameter, it is 29 * much faster to store just one function of an integer parameter and call it 30 * for each value. Conventional vector-of-tasks can be run in parallel using a 31 * lambda function adapter that simply calls task_funcs[task]. 32 * 33 * If no multi-threading is desired, a @c NULL value of JxlParallelRunner 34 * will use an internal implementation without multi-threading. 35 */ 36 37 #ifndef JXL_PARALLEL_RUNNER_H_ 38 #define JXL_PARALLEL_RUNNER_H_ 39 40 #include <stddef.h> 41 #include <stdint.h> 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 /** Return code used in the JxlParallel* functions as return value. A value 48 * of ::JXL_PARALLEL_RET_SUCCESS means success and any other value means error. 49 * The special value ::JXL_PARALLEL_RET_RUNNER_ERROR can be used by the runner 50 * to indicate any other error. 51 */ 52 typedef int JxlParallelRetCode; 53 54 /** 55 * Code returned by the @ref JxlParallelRunInit function to indicate success. 56 */ 57 #define JXL_PARALLEL_RET_SUCCESS (0) 58 59 /** 60 * Code returned by the @ref JxlParallelRunInit function to indicate a general 61 * error. 62 */ 63 #define JXL_PARALLEL_RET_RUNNER_ERROR (-1) 64 65 /** 66 * Parallel run initialization callback. See @ref JxlParallelRunner for details. 67 * 68 * This function MUST be called by the JxlParallelRunner only once, on the 69 * same thread that called @ref JxlParallelRunner, before any parallel 70 * execution. The purpose of this call is to provide the maximum number of 71 * threads that the 72 * @ref JxlParallelRunner will use, which can be used by JPEG XL to allocate 73 * per-thread storage if needed. 74 * 75 * @param jpegxl_opaque the @p jpegxl_opaque handle provided to 76 * @ref JxlParallelRunner() must be passed here. 77 * @param num_threads the maximum number of threads. This value must be 78 * positive. 79 * @return 0 if the initialization process was successful. 80 * @return an error code if there was an error, which should be returned by 81 * @ref JxlParallelRunner(). 82 */ 83 typedef JxlParallelRetCode (*JxlParallelRunInit)(void* jpegxl_opaque, 84 size_t num_threads); 85 86 /** 87 * Parallel run data processing callback. See @ref JxlParallelRunner for 88 * details. 89 * 90 * This function MUST be called once for every number in the range [start_range, 91 * end_range) (including start_range but not including end_range) passing this 92 * number as the @p value. Calls for different value may be executed from 93 * different threads in parallel. 94 * 95 * @param jpegxl_opaque the @p jpegxl_opaque handle provided to 96 * @ref JxlParallelRunner() must be passed here. 97 * @param value the number in the range [start_range, end_range) of the call. 98 * @param thread_id the thread number where this function is being called from. 99 * This must be lower than the @p num_threads value passed to 100 * @ref JxlParallelRunInit. 101 */ 102 typedef void (*JxlParallelRunFunction)(void* jpegxl_opaque, uint32_t value, 103 size_t thread_id); 104 105 /** 106 * JxlParallelRunner function type. A parallel runner implementation can be 107 * provided by a JPEG XL caller to allow running computations in multiple 108 * threads. This function must call the initialization function @p init in the 109 * same thread that called it and then call the passed @p func once for every 110 * number in the range [start_range, end_range) (including start_range but not 111 * including end_range) possibly from different multiple threads in parallel. 112 * 113 * The @ref JxlParallelRunner function does not need to be re-entrant. This 114 * means that the same @ref JxlParallelRunner function with the same 115 * runner_opaque provided parameter will not be called from the library from 116 * either @p init or 117 * @p func in the same decoder or encoder instance. However, a single decoding 118 * or encoding instance may call the provided @ref JxlParallelRunner multiple 119 * times for different parts of the decoding or encoding process. 120 * 121 * @return 0 if the @p init call succeeded (returned 0) and no other error 122 * occurred in the runner code. 123 * @return JXL_PARALLEL_RET_RUNNER_ERROR if an error occurred in the runner 124 * code, for example, setting up the threads. 125 * @return the return value of @p init() if non-zero. 126 */ 127 typedef JxlParallelRetCode (*JxlParallelRunner)( 128 void* runner_opaque, void* jpegxl_opaque, JxlParallelRunInit init, 129 JxlParallelRunFunction func, uint32_t start_range, uint32_t end_range); 130 131 /* The following is an example of a @ref JxlParallelRunner that doesn't use any 132 * multi-threading. Note that this implementation doesn't store any state 133 * between multiple calls of the ExampleSequentialRunner function, so the 134 * runner_opaque value is not used. 135 136 JxlParallelRetCode ExampleSequentialRunner(void* runner_opaque, 137 void* jpegxl_opaque, 138 JxlParallelRunInit init, 139 JxlParallelRunFunction func, 140 uint32_t start_range, 141 uint32_t end_range) { 142 // We only use one thread (the currently running thread). 143 JxlParallelRetCode init_ret = (*init)(jpegxl_opaque, 1); 144 if (init_ret != 0) return init_ret; 145 146 // In case of other initialization error (for example when initializing the 147 // threads) one can return JXL_PARALLEL_RET_RUNNER_ERROR. 148 149 for (uint32_t i = start_range; i < end_range; i++) { 150 // Every call is in the thread number 0. These don't need to be in any 151 // order. 152 (*func)(jpegxl_opaque, i, 0); 153 } 154 return JXL_PARALLEL_RET_SUCCESS; 155 } 156 */ 157 158 #ifdef __cplusplus 159 } 160 #endif 161 162 #endif /* JXL_PARALLEL_RUNNER_H_ */ 163 164 /** @}*/