dthreads.h 8.31 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
/*  Copyright (C) 2011 CZ.NIC, z.s.p.o. <knot-dns@labs.nic.cz>

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
Marek Vavrusa's avatar
Marek Vavrusa committed
16 17
/*!
 * \file dthreads.h
18
 *
19
 * \author Marek Vavrusa <marek.vavusa@nic.cz>
Marek Vavrusa's avatar
Marek Vavrusa committed
20 21 22 23 24 25 26 27 28
 *
 * \brief Threading API.
 *
 * Dynamic threads provide:
 * - coherent and incoherent threading capabilities
 * - thread repurposing
 * - thread prioritization
 * - on-the-fly changing of threading unit size
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
29 30 31 32 33 34
 * Coherent threading unit is when all threads execute
 * the same runnable function.
 *
 * Incoherent function is when at least one thread executes
 * a different runnable than the others.
 *
35
 * \addtogroup threading
Marek Vavrusa's avatar
Marek Vavrusa committed
36 37 38
 * @{
 */

39
#pragma once
Marek Vavrusa's avatar
Marek Vavrusa committed
40 41 42

#include <pthread.h>

Daniel Salzman's avatar
Daniel Salzman committed
43 44
#define DEFAULT_THR_COUNT 2  /*!< Default thread count. */

Marek Vavrusa's avatar
Marek Vavrusa committed
45
/* Forward decls */
46 47
struct dthread;
struct dt_unit;
Marek Vavrusa's avatar
Marek Vavrusa committed
48 49 50 51

/*!
 * \brief Thread state enumeration.
 */
Marek Vavrusa's avatar
Marek Vavrusa committed
52
typedef enum {
Marek Vavrusa's avatar
Marek Vavrusa committed
53
	ThreadJoined    = 1 << 0, /*!< Thread is finished and joined. */
Marek Vavrusa's avatar
Marek Vavrusa committed
54
	ThreadJoinable  = 1 << 1, /*!< Thread is waiting to be reclaimed. */
Marek Vavrusa's avatar
Marek Vavrusa committed
55 56 57 58
	ThreadCancelled = 1 << 2, /*!< Thread is cancelled, finishing task. */
	ThreadDead      = 1 << 3, /*!< Thread is finished, exiting. */
	ThreadIdle      = 1 << 4, /*!< Thread is idle, waiting for purpose. */
	ThreadActive    = 1 << 5  /*!< Thread is active, working on a task. */
Marek Vavrusa's avatar
Marek Vavrusa committed
59 60 61 62 63
} dt_state_t;

/*!
 * \brief Thread runnable prototype.
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
64 65 66 67 68
 * Runnable is basically a pointer to function which is called on active
 * thread runtime.
 *
 * \note When implementing a runnable, keep in mind to check thread state as
 *       it may change, and implement a cooperative cancellation point.
Marek Vavrusa's avatar
Marek Vavrusa committed
69
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
70
 *       Implement this by checking dt_is_cancelled() and return
Marek Vavrusa's avatar
Marek Vavrusa committed
71 72
 *       as soon as possible.
 */
73
typedef int (*runnable_t)(struct dthread *);
Marek Vavrusa's avatar
Marek Vavrusa committed
74 75 76 77

/*!
 * \brief Single thread descriptor public API.
 */
78
typedef struct dthread {
Marek Vavrusa's avatar
Marek Vavrusa committed
79 80
	volatile unsigned  state; /*!< Bitfield of dt_flag flags. */
	runnable_t           run; /*!< Runnable function or 0. */
81
	runnable_t      destruct; /*!< Destructor function or 0. */
Marek Vavrusa's avatar
Marek Vavrusa committed
82
	void               *data; /*!< Currently active data */
83 84 85 86 87
	struct dt_unit     *unit; /*!< Reference to assigned unit. */
	void             *_adata; /*!< Thread-specific data. */
	pthread_t           _thr; /*!< Thread */
	pthread_attr_t     _attr; /*!< Thread attributes */
	pthread_mutex_t      _mx; /*!< Thread state change lock. */
Marek Vavrusa's avatar
Marek Vavrusa committed
88 89 90 91 92 93 94 95 96
} dthread_t;

/*!
 * \brief Thread unit descriptor API.
 *
 * Thread unit consists of 1..N threads.
 * Unit is coherent if all threads execute
 * the same runnable.
 */
97
typedef struct dt_unit {
Marek Vavrusa's avatar
Marek Vavrusa committed
98
	int                   size; /*!< Unit width (number of threads) */
99 100 101 102 103 104
	struct dthread   **threads; /*!< Array of threads */
	pthread_cond_t     _notify; /*!< Notify thread */
	pthread_mutex_t _notify_mx; /*!< Condition mutex */
	pthread_cond_t     _report; /*!< Report thread state */
	pthread_mutex_t _report_mx; /*!< Condition mutex */
	pthread_mutex_t        _mx; /*!< Unit lock */
Marek Vavrusa's avatar
Marek Vavrusa committed
105 106 107 108 109
} dt_unit_t;

/*!
 * \brief Create a set of coherent threads.
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
110 111
 * Coherent means, that the threads will share a common runnable and the data.
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
112 113
 * \param count Requested thread count.
 * \param runnable Runnable function for all threads.
114
 * \param destructor Destructor for all threads.
Marek Vavrusa's avatar
Marek Vavrusa committed
115
 * \param data Any data passed onto threads.
116
 *
117 118
 * \retval New instance if successful
 * \retval NULL on error
Marek Vavrusa's avatar
Marek Vavrusa committed
119
 */
Marek Vavrusa's avatar
Marek Vavrusa committed
120
dt_unit_t *dt_create(int count, runnable_t runnable, runnable_t destructor, void *data);
Marek Vavrusa's avatar
Marek Vavrusa committed
121 122 123 124

/*!
 * \brief Free unit.
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
125 126
 * \warning Behavior is undefined if threads are still active, make sure
 *          to call dt_join() first.
127 128
 *
 * \param unit Unit to be deleted.
Marek Vavrusa's avatar
Marek Vavrusa committed
129
 */
130
void dt_delete(dt_unit_t **unit);
Marek Vavrusa's avatar
Marek Vavrusa committed
131 132 133 134

/*!
 * \brief Start all threads in selected unit.
 *
135
 * \param unit Unit to be started.
136
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
137 138
 * \retval KNOT_EOK on success.
 * \retval KNOT_EINVAL on invalid parameters (unit is null).
Marek Vavrusa's avatar
Marek Vavrusa committed
139
 */
140
int dt_start(dt_unit_t *unit);
Marek Vavrusa's avatar
Marek Vavrusa committed
141 142

/*!
143
 * \brief Send given signal to thread.
Marek Vavrusa's avatar
Marek Vavrusa committed
144
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
145 146
 * \note This is useful to interrupt some blocking I/O as well, for example
 *       with SIGALRM, which is handled by default.
147
 * \note Signal handler may be overriden in runnable.
Marek Vavrusa's avatar
Marek Vavrusa committed
148
 *
149
 * \param thread Target thread instance.
Marek Vavrusa's avatar
Marek Vavrusa committed
150
 * \param signum Signal code.
151
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
152 153 154
 * \retval KNOT_EOK on success.
 * \retval KNOT_EINVAL on invalid parameters.
 * \retval KNOT_ERROR unspecified error.
Marek Vavrusa's avatar
Marek Vavrusa committed
155
 */
156
int dt_signalize(dthread_t *thread, int signum);
Marek Vavrusa's avatar
Marek Vavrusa committed
157 158

/*!
159
 * \brief Wait for all thread in unit to finish.
Marek Vavrusa's avatar
Marek Vavrusa committed
160
 *
161
 * \param unit Unit to be joined.
162
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
163 164
 * \retval KNOT_EOK on success.
 * \retval KNOT_EINVAL on invalid parameters.
Marek Vavrusa's avatar
Marek Vavrusa committed
165
 */
166
int dt_join(dt_unit_t *unit);
Marek Vavrusa's avatar
Marek Vavrusa committed
167

168
/*!
169
 * \brief Stop all threads in unit.
170
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
171
 * Thread is interrupted at the nearest runnable cancellation point.
172
 *
173
 * \param unit Unit to be stopped.
174
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
175 176
 * \retval KNOT_EOK on success.
 * \retval KNOT_EINVAL on invalid parameters.
177
 */
178
int dt_stop(dt_unit_t *unit);
Marek Vavrusa's avatar
Marek Vavrusa committed
179

180 181 182 183
/*!
 * \brief Set thread affinity to masked CPU's.
 *
 * \param thread Target thread instance.
184 185
 * \param cpu_id Array of CPU IDs to set affinity to.
 * \param cpu_count Number of CPUs in the array, set to 0 for no CPU.
186
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
187 188
 * \retval KNOT_EOK on success.
 * \retval KNOT_EINVAL on invalid parameters.
189
 */
190
int dt_setaffinity(dthread_t *thread, unsigned* cpu_id, size_t cpu_count);
191

192 193 194
/*!
 * \brief Wake up thread from idle state.
 *
195 196 197 198 199
 * Thread is awoken from idle state and reenters runnable.
 * This function only affects idle threads.
 *
 * \note Unit needs to be started with dt_start() first, as the function
 *       doesn't affect dead threads.
200 201
 *
 * \param thread Target thread instance.
202
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
203 204 205
 * \retval KNOT_EOK on success.
 * \retval KNOT_EINVAL on invalid parameters.
 * \retval KNOT_ENOTSUP operation not supported.
206
 */
207
int dt_activate(dthread_t *thread);
208

Marek Vavrusa's avatar
Marek Vavrusa committed
209 210 211 212 213 214
/*!
 * \brief Put thread to idle state, cancells current runnable function.
 *
 * Thread is flagged with Cancel flag and returns from runnable at the nearest
 * cancellation point, which requires complying runnable function.
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
215 216
 * \note Thread isn't disposed, but put to idle state until it's requested
 *       again or collected by dt_compact().
Marek Vavrusa's avatar
Marek Vavrusa committed
217
 *
218
 * \param thread Target thread instance.
219
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
220 221
 * \retval KNOT_EOK on success.
 * \retval KNOT_EINVAL on invalid parameters.
Marek Vavrusa's avatar
Marek Vavrusa committed
222
 */
223
int dt_cancel(dthread_t *thread);
Marek Vavrusa's avatar
Marek Vavrusa committed
224 225 226 227

/*!
 * \brief Collect and dispose idle threads.
 *
228
 * \param unit Target unit instance.
229
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
230 231
 * \retval KNOT_EOK on success.
 * \retval KNOT_EINVAL on invalid parameters.
Marek Vavrusa's avatar
Marek Vavrusa committed
232
 */
233
int dt_compact(dt_unit_t *unit);
Marek Vavrusa's avatar
Marek Vavrusa committed
234

235 236 237 238 239 240
/*!
 * \brief Return number of online processors.
 *
 * \retval Number of online CPU's if success.
 * \retval <0 on failure.
 */
241
int dt_online_cpus(void);
242

243 244 245
/*!
 * \brief Return optimal number of threads for instance.
 *
246
 * It is estimated as NUM_CPUs + CONSTANT.
247 248
 * Fallback is DEFAULT_THR_COUNT  (\see common.h).
 *
249
 * \return Number of threads.
250
 */
251
int dt_optimal_size(void);
252

253 254 255 256
/*!
 * \brief Return true if thread is cancelled.
 *
 * Synchronously check for ThreadCancelled flag.
257 258
 *
 * \param thread Target thread instance.
259
 *
260 261
 * \retval 1 if cancelled.
 * \retval 0 if not cancelled.
262
 */
263
int dt_is_cancelled(dthread_t *thread);
Marek Vavrusa's avatar
Marek Vavrusa committed
264

265 266 267 268 269 270 271 272 273 274 275
/*!
 * \brief Return thread index in threading unit.
 *
 * \note Returns 0 when thread doesn't have a unit.
 *
 * \param thread Target thread instance.
 *
 * \return Thread index.
 */
unsigned dt_get_id(dthread_t *thread);

276 277 278 279
/*!
 * \brief Lock unit to prevent parallel operations which could alter unit
 *        at the same time.
 *
280
 * \param unit Target unit instance.
281
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
282 283 284 285
 * \retval KNOT_EOK on success.
 * \retval KNOT_EINVAL on invalid parameters.
 * \retval KNOT_EAGAIN lack of resources to lock unit, try again.
 * \retval KNOT_ERROR unspecified error.
286 287 288 289 290 291 292 293
 */
int dt_unit_lock(dt_unit_t *unit);

/*!
 * \brief Unlock unit.
 *
 * \see dt_unit_lock()
 *
294
 * \param unit Target unit instance.
295
 *
Marek Vavrusa's avatar
Marek Vavrusa committed
296 297 298 299
 * \retval KNOT_EOK on success.
 * \retval KNOT_EINVAL on invalid parameters.
 * \retval KNOT_EAGAIN lack of resources to unlock unit, try again.
 * \retval KNOT_ERROR unspecified error.
300 301 302
 */
int dt_unit_unlock(dt_unit_t *unit);

303
/*! @} */