JPEG XL Multi-thread library (libjxl_threads)

Additional multi-threaded implementations for the parallel runner. More...

## Files

file | resizable_parallel_runner.h
| implementation using std::thread of a resizeable JxlParallelRunner.
file | resizable_parallel_runner_cxx.h
| C++ header-only helper for resizable_parallel_runner.h.
file | resizable_parallel_runner_cxx.h
| C++ header-only helper for resizable_parallel_runner.h.
file | thread_parallel_runner.h
| implementation using std::thread of a JxlParallelRunner.
file | thread_parallel_runner_cxx.h
| C++ header-only helper for thread_parallel_runner.h.

## Classes

struct | JxlResizableParallelRunnerDestroyStruct
struct | JxlThreadParallelRunnerDestroyStruct

## Typedefs

typedef std::unique_ptr< void, JxlResizableParallelRunnerDestroyStruct > | JxlResizableParallelRunnerPtr
typedef std::unique_ptr< void, JxlThreadParallelRunnerDestroyStruct > | JxlThreadParallelRunnerPtr

## Functions

JXL_THREADS_EXPORT JxlParallelRetCode | JxlResizableParallelRunner (void *runner_opaque, void *jpegxl_opaque, JxlParallelRunInit init, JxlParallelRunFunction func, uint32_t start_range, uint32_t end_range)
JXL_THREADS_EXPORT void * | JxlResizableParallelRunnerCreate (const JxlMemoryManager *memory_manager)
JXL_THREADS_EXPORT void | JxlResizableParallelRunnerSetThreads (void *runner_opaque, size_t num_threads)
JXL_THREADS_EXPORT uint32_t | JxlResizableParallelRunnerSuggestThreads (uint64_t xsize, uint64_t ysize)
JXL_THREADS_EXPORT void | JxlResizableParallelRunnerDestroy (void *runner_opaque)
JXL_THREADS_EXPORT JxlParallelRetCode | JxlThreadParallelRunner (void *runner_opaque, void *jpegxl_opaque, JxlParallelRunInit init, JxlParallelRunFunction func, uint32_t start_range, uint32_t end_range)
JXL_THREADS_EXPORT void * | JxlThreadParallelRunnerCreate (const JxlMemoryManager *memory_manager, size_t num_worker_threads)
JXL_THREADS_EXPORT void | JxlThreadParallelRunnerDestroy (void *runner_opaque)
JXL_THREADS_EXPORT size_t | JxlThreadParallelRunnerDefaultNumWorkerThreads ()

## Detailed Description

Additional multi-threaded implementations for the parallel runner.

## Typedef Documentation

## JxlResizableParallelRunnerPtr

typedef std::unique_ptr<void, JxlResizableParallelRunnerDestroyStruct> JxlResizableParallelRunnerPtr

std::unique_ptr<> type that calls JxlResizableParallelRunnerDestroy() when releasing the runner.

Use this helper type from C++ sources to ensure the runner is destroyed and their internal resources released.

## JxlThreadParallelRunnerPtr

typedef std::unique_ptr<void, JxlThreadParallelRunnerDestroyStruct> JxlThreadParallelRunnerPtr

std::unique_ptr<> type that calls JxlThreadParallelRunnerDestroy() when releasing the runner.

Use this helper type from C++ sources to ensure the runner is destroyed and their internal resources released.

## Function Documentation

## JxlResizableParallelRunner()

JXL_THREADS_EXPORT JxlParallelRetCode JxlResizableParallelRunner | ( | void * | runner_opaque,
|  | void * | jpegxl_opaque,
|  | JxlParallelRunInit | init,
|  | JxlParallelRunFunction | func,
|  | uint32_t | start_range,
|  | uint32_t | end_range
| ) |  |

Implementation of JxlParallelRunner than can be used to enable multithreading when using the JPEG XL library. This uses std::thread internally and related synchronization functions. The number of threads created can be changed after creation of the thread pool; the threads (including the main thread) are re-used for every ResizableParallelRunner::Runner call. Only one concurrent JxlResizableParallelRunner call per instance is allowed at a time.

This is a scalable, lower-overhead thread pool runner, especially suitable for data-parallel computations in the fork-join model, where clients need to know when all tasks have completed.

Compared to the implementation in thread_parallel_runner.h, this implementation is tuned for execution on lower-powered systems, including for example ARM CPUs with big.LITTLE computation models. Parallel runner internally using std::thread. Use as JxlParallelRunner.

## JxlResizableParallelRunnerCreate()

JXL_THREADS_EXPORT void * JxlResizableParallelRunnerCreate | ( | const JxlMemoryManager * | memory_manager | ) |

Creates the runner for JxlResizableParallelRunner. Use as the opaque runner. The runner will execute tasks on the calling thread until JxlResizableParallelRunnerSetThreads is called.

## JxlResizableParallelRunnerDestroy()

JXL_THREADS_EXPORT void JxlResizableParallelRunnerDestroy | ( | void * | runner_opaque | ) |

Destroys the runner created by JxlResizableParallelRunnerCreate.

## JxlResizableParallelRunnerSetThreads()

JXL_THREADS_EXPORT void JxlResizableParallelRunnerSetThreads | ( | void * | runner_opaque,
|  | size_t | num_threads
| ) |  |

Changes the number of threads for JxlResizableParallelRunner.

## JxlResizableParallelRunnerSuggestThreads()

JXL_THREADS_EXPORT uint32_t JxlResizableParallelRunnerSuggestThreads | ( | uint64_t | xsize,
|  | uint64_t | ysize
| ) |  |

Suggests a number of threads to use for an image of given size.

## JxlThreadParallelRunner()

JXL_THREADS_EXPORT JxlParallelRetCode JxlThreadParallelRunner | ( | void * | runner_opaque,
|  | void * | jpegxl_opaque,
|  | JxlParallelRunInit | init,
|  | JxlParallelRunFunction | func,
|  | uint32_t | start_range,
|  | uint32_t | end_range
| ) |  |

Implementation of JxlParallelRunner than can be used to enable multithreading when using the JPEG XL library. This uses std::thread internally and related synchronization functions. The number of threads created is fixed at construction time and the threads are re-used for every ThreadParallelRunner::Runner call. Only one concurrent JxlThreadParallelRunner call per instance is allowed at a time.

This is a scalable, lower-overhead thread pool runner, especially suitable for data-parallel computations in the fork-join model, where clients need to know when all tasks have completed.

This thread pool can efficiently load-balance millions of tasks using an atomic counter, thus avoiding per-task virtual or system calls. With 48 hyperthreads and 1M tasks that add to an atomic counter, overall runtime is 10-20x higher when using std::async, and ~200x for a queue-based thread Parallel runner internally using std::thread. Use as JxlParallelRunner.

## JxlThreadParallelRunnerCreate()

JXL_THREADS_EXPORT void * JxlThreadParallelRunnerCreate | ( | const JxlMemoryManager * | memory_manager,
|  | size_t | num_worker_threads
| ) |  |

Creates the runner for JxlThreadParallelRunner. Use as the opaque runner.

## JxlThreadParallelRunnerDefaultNumWorkerThreads()

JXL_THREADS_EXPORT size_t JxlThreadParallelRunnerDefaultNumWorkerThreads | ( |  | ) |

Returns a default num_worker_threads value for JxlThreadParallelRunnerCreate.

## JxlThreadParallelRunnerDestroy()

JXL_THREADS_EXPORT void JxlThreadParallelRunnerDestroy | ( | void * | runner_opaque | ) |

Destroys the runner created by JxlThreadParallelRunnerCreate.