1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
/* SPDX-License-Identifier: LGPL-3.0-or-later */
/*
* threadpool.h
*
* Copyright (C) 2021 David Oberhollenzer <goliath@infraroot.at>
*/
#ifndef THREADPOOL_H
#define THREADPOOL_H
#include "sqfs/predef.h"
typedef int (*thread_pool_worker_t)(void *user, void *work_item);
/**
* @struct thread_pool_t
*
* @brief A thread pool with a ticket number based work item ordering.
*
* While the order in which items are non-deterministic, the thread pool
* implementation internally uses a ticket system to ensure the completed
* items are deqeueued in the same order that they were enqueued.
*/
typedef struct thread_pool_t {
/**
* @brief Shutdown and destroy a thread pool.
*
* @param pool A pointer to a pool returned by thread_pool_create
*/
void (*destroy)(struct thread_pool_t *pool);
/**
* @brief Get the actual number of worker threads available.
*
* @return A number greater or equal to 1.
*/
size_t (*get_worker_count)(struct thread_pool_t *pool);
/**
* @brief Change the user data pointer for a thread pool worker
* by index.
*
* @param idx A zero-based index into the worker list.
* @param ptr A user pointer that this specific worker thread should
* pass to the worker callback.
*/
void (*set_worker_ptr)(struct thread_pool_t *pool, size_t idx,
void *ptr);
/**
* @brief Submit a work item to a thread pool.
*
* This function will fail on allocation failure or if the internal
* error state is set was set by one of the workers.
*
* @param ptr A pointer to a work object to enqueue.
*
* @return Zero on success.
*/
int (*submit)(struct thread_pool_t *pool, void *ptr);
/**
* @brief Wait for a work item to be completed.
*
* This function dequeues a single completed work item. It may block
* until one of the worker threads signals completion of an additional
* item.
*
* This function guarantees to return the items in the same order as
* they were submitted, so the function can actually block longer than
* necessary, because it has to wait until the next item in sequence
* is finished.
*
* @return A pointer to a new work item or NULL if there are none
* in the pipeline.
*/
void *(*dequeue)(struct thread_pool_t *pool);
/**
* @brief Get the internal worker return status value.
*
* If the worker functions returns a non-zero exit status in one of the
* worker threads, the thread pool stors the value internally and shuts
* down. This function can be used to retrieve the value.
*
* @return A non-zero value returned by the worker callback or zero if
* everything is A-OK.
*/
int (*get_status)(struct thread_pool_t *pool);
} thread_pool_t;
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Create a thread pool instance.
*
* @param num_jobs The number of worker threads to launch.
* @param worker A function to call from the worker threads to process
* the work items.
*
* @return A pointer to a thread pool on success, NULL on failure.
*/
SQFS_INTERNAL thread_pool_t *thread_pool_create(size_t num_jobs,
thread_pool_worker_t worker);
/**
* @brief Create a serial mockup thread pool implementation.
*
* This returns a @ref thread_pool_t implementation that, instead of running a
* thread pool actually does the work in-situ when dequeueing.
*
* @param worker A function to call from the worker threads to process
* the work items.
*
* @return A pointer to a thread pool on success, NULL on failure.
*/
SQFS_INTERNAL
thread_pool_t *thread_pool_create_serial(thread_pool_worker_t worker);
#ifdef __cplusplus
}
#endif
#endif /* THREADPOOL_H */
|
