ascii-chat
Binary v0.16.50-198-g78f51665f
Library lib/v0.3.2-2240-g78f51665f
Video chat in your terminal
Loading...
Searching...
No Matches
thread_pool.c File Reference

🧵 Generic thread pool implementation for managing worker threads More...

Go to the source code of this file.

Macros

#define THREAD_POOL_THREAD_NAME_COPY_BUFFER_SIZE   64

Functions

thread_pool_t * thread_pool_create (const char *pool_name)
 Create a new thread pool (long-lived threads mode).
thread_pool_t * thread_pool_create_with_workers (const char *pool_name, size_t num_workers)
 Create a new thread pool in work queue mode.
void thread_pool_destroy (thread_pool_t *pool)
 Destroy a thread pool.
asciichat_error_t thread_pool_queue_work (const char *name, thread_pool_t *pool, void *(*work_func)(void *), void *work_arg)
 Queue a named work item to a work queue pool.
asciichat_error_t thread_pool_spawn (thread_pool_t *pool, void *(*thread_func)(void *), void *thread_arg, int stop_id, const char *thread_name)
 Spawn a worker thread in the pool.
asciichat_error_t thread_pool_stop_all (thread_pool_t *pool)
 Stop all threads in the pool in stop_id order.
size_t thread_pool_get_count (const thread_pool_t *pool)
 Get thread count in the pool.
bool thread_pool_has_threads (const thread_pool_t *pool)
 Check if pool has any threads.
asciichat_error_t thread_pool_interrupt_all (thread_pool_t *pool, int sig)
 Send a signal to all threads in the pool.

Detailed Description

🧵 Generic thread pool implementation for managing worker threads

Definition in file thread_pool.c.

Macro Definition Documentation

◆ THREAD_POOL_THREAD_NAME_COPY_BUFFER_SIZE

#define THREAD_POOL_THREAD_NAME_COPY_BUFFER_SIZE   64

Definition at line 7 of file thread_pool.c.

Referenced by thread_pool_spawn().

Function Documentation

◆ thread_pool_create()

thread_pool_t * thread_pool_create ( const char * pool_name)

Create a new thread pool (long-lived threads mode).

Allocates and initializes a thread pool structure. The pool starts empty with no threads. Use thread_pool_spawn() to add threads to the pool.

This mode is used for long-lived worker threads that run for the lifetime of the application or connection (e.g., stats logger, cleanup thread).

Parameters
pool_nameName for the pool (max 63 chars, used for debugging)
Returns
Pointer to new thread pool, or NULL on allocation failure

Definition at line 92 of file thread_pool.c.

92 {
94 if (!pool) {
95 SET_ERRNO(ERROR_MEMORY, "Failed to allocate thread pool");
96 return NULL;
97 }
98
99 memset(pool, 0, sizeof(*pool));
100
101 // Copy pool name (truncate if necessary)
102 if (pool_name) {
103 SAFE_STRNCPY(pool->name, pool_name, sizeof(pool->name));
104 } else {
105 SAFE_STRNCPY(pool->name, "unnamed", sizeof(pool->name));
106 }
107
108 // Initialize linked list
109 pool->threads = NULL;
110 pool->thread_count = 0;
111 pool->is_work_queue_mode = false;
112 pool->num_workers = 0;
113
114 // Initialize mutex
115 if (mutex_init(&pool->threads_mutex, "thread_pool") != 0) {
116 SAFE_FREE(pool);
117 SET_ERRNO(ERROR_THREAD, "Failed to initialize thread pool mutex");
118 return NULL;
119 }
120
121 NAMED_REGISTER_THREAD_POOL(pool, pool->name, NULL);
122
123 // Register sync primitives for debugging
124 NAMED_REGISTER_MUTEX(&pool->threads_mutex, "threads_mutex", (uintptr_t)(const void *)(pool));
125
126 log_debug("Thread pool '%s' created (long-lived thread mode)", pool->name);
127 return pool;
128}
#define SET_ERRNO(code,...)
#define SAFE_STRNCPY(dst, src, size)
#define SAFE_FREE(ptr)
#define SAFE_MALLOC(size, cast)
#define NAMED_REGISTER_THREAD_POOL(pool, name, parent_ptr)
Register a thread pool with automatic format specifier.
#define NAMED_REGISTER_MUTEX(mutex, name, parent_ptr)
Register a mutex with automatic format specifier.
@ ERROR_MEMORY
Definition error_codes.h:55
@ ERROR_THREAD
#define log_debug(...)
Log a DEBUG message.
Definition log/log.h:589
struct thread_pool thread_pool_t
One queued function call waiting for a thread-pool worker.
mutex_t threads_mutex
Mutex protecting thread list.
bool is_work_queue_mode
True if using work queue mode.
thread_pool_entry_t * threads
Linked list of threads (sorted by stop_id).
size_t thread_count
Number of threads in pool.
size_t num_workers
Number of pre-created worker threads.
char name[64]
Pool name for debugging.

References ERROR_MEMORY, ERROR_THREAD, thread_pool::is_work_queue_mode, log_debug, thread_pool::name, NAMED_REGISTER_MUTEX, NAMED_REGISTER_THREAD_POOL, thread_pool::num_workers, SAFE_FREE, SAFE_MALLOC, SAFE_STRNCPY, SET_ERRNO, thread_pool::thread_count, thread_pool::threads, and thread_pool::threads_mutex.

Referenced by acds_server_init(), client_connection_create(), network_server_create(), and server_main().

◆ thread_pool_create_with_workers()

thread_pool_t * thread_pool_create_with_workers ( const char * pool_name,
size_t num_workers )

Create a new thread pool in work queue mode.

Creates a thread pool with pre-allocated worker threads that pull tasks from a work queue. Use thread_pool_queue_work() to add work to the pool.

This mode is used for short-lived tasks that need to be executed without creating new threads from callback context (e.g., WebSocket handlers).

Worker threads are created immediately and wait for work to be queued. The pool will not accept spawn() calls - use queue_work() instead.

Parameters
pool_nameName for the pool (max 63 chars, used for debugging)
num_workersNumber of pre-allocated worker threads
Returns
Pointer to new thread pool, or NULL on allocation failure

Definition at line 130 of file thread_pool.c.

130 {
131 if (num_workers == 0) {
132 SET_ERRNO(ERROR_INVALID_PARAM, "num_workers must be > 0");
133 return NULL;
134 }
135
137 if (!pool) {
138 SET_ERRNO(ERROR_MEMORY, "Failed to allocate thread pool");
139 return NULL;
140 }
141
142 memset(pool, 0, sizeof(*pool));
143
144 // Copy pool name
145 if (pool_name) {
146 SAFE_STRNCPY(pool->name, pool_name, sizeof(pool->name));
147 } else {
148 SAFE_STRNCPY(pool->name, "unnamed", sizeof(pool->name));
149 }
150
151 // Mark as work queue mode
152 pool->is_work_queue_mode = true;
153 pool->num_workers = num_workers;
154 pool->work_queue = NULL;
155 pool->shutdown_requested = false;
156
157 // Initialize mutexes
158 if (mutex_init(&pool->threads_mutex, "worker_list") != 0) {
159 SAFE_FREE(pool);
160 SET_ERRNO(ERROR_THREAD, "Failed to initialize threads_mutex");
161 return NULL;
162 }
163
164 if (mutex_init(&pool->work_queue_mutex, "pending_tasks") != 0) {
165 mutex_destroy(&pool->threads_mutex);
166 SAFE_FREE(pool);
167 SET_ERRNO(ERROR_THREAD, "Failed to initialize work_queue_mutex");
168 return NULL;
169 }
170
171 // Initialize condition variable
172 if (cond_init(&pool->work_available, "task_available") != 0) {
173 mutex_destroy(&pool->work_queue_mutex);
174 mutex_destroy(&pool->threads_mutex);
175 SAFE_FREE(pool);
176 SET_ERRNO(ERROR_THREAD, "Failed to initialize work_available condition");
177 return NULL;
178 }
179
180 // Create worker threads
181 for (size_t i = 0; i < num_workers; i++) {
183 if (!entry) {
184 log_error("Failed to allocate worker entry %zu", i);
186 SET_ERRNO(ERROR_MEMORY, "Failed to allocate worker entry");
187 return NULL;
188 }
189
190 memset(entry, 0, sizeof(*entry));
191 entry->stop_id = 0;
192 entry->thread_func = thread_pool_worker_thread;
193 entry->thread_arg = pool;
194 SAFE_SNPRINTF(entry->name, sizeof(entry->name), "%s_worker_%zu", pool->name, i);
195
196 // Create worker thread
197 if (platform_thread_create(&entry->thread, entry->name, thread_pool_worker_thread, pool) != 0) {
198 log_error("Failed to create worker thread %zu", i);
199 SAFE_FREE(entry);
201 SET_ERRNO(ERROR_THREAD, "Failed to create worker thread %zu", i);
202 return NULL;
203 }
204
205 // Add to thread list
206 mutex_lock(&pool->threads_mutex);
207 entry->next = pool->threads;
208 pool->threads = entry;
209 pool->thread_count++;
210 mutex_unlock(&pool->threads_mutex);
211
212 log_debug("[ThreadPool] Created worker thread %zu for pool '%s'", i, pool->name);
213 }
214
215 NAMED_REGISTER_THREAD_POOL(pool, pool->name, NULL);
216
217 // Register sync primitives for debugging
218 NAMED_REGISTER_MUTEX(&pool->threads_mutex, "threads_mutex", (uintptr_t)(const void *)(pool));
219 NAMED_REGISTER_MUTEX(&pool->work_queue_mutex, "work_queue_mutex", (uintptr_t)(const void *)(pool));
220 NAMED_REGISTER_COND(&pool->work_available, "work_available", (uintptr_t)(const void *)(pool));
221
222 log_info("[ThreadPool] Created work queue pool '%s' with %zu worker threads", pool->name, num_workers);
223 return pool;
224}
#define SAFE_SNPRINTF(buffer, buffer_size,...)
#define NAMED_REGISTER_COND(cond, name, parent_ptr)
Register a condition variable with automatic format specifier.
@ ERROR_INVALID_PARAM
#define log_error(...)
Log an ERROR message.
Definition log/log.h:628
#define log_info(...)
Log an INFO message.
Definition log/log.h:602
platform_thread_t thread
Thread handle.
void *(* thread_func)(void *)
Thread function.
void * thread_arg
Thread argument.
struct thread_pool_entry * next
Linked list next pointer.
int stop_id
Cleanup order (lower = stop first, -1 = unordered).
char name[64]
Thread name for debugging.
cond_t work_available
Condition variable for workers to wait on.
bool shutdown_requested
Signal workers to exit.
thread_pool_work_entry_t * work_queue
Queue of pending work.
mutex_t work_queue_mutex
Mutex protecting work queue.
void thread_pool_destroy(thread_pool_t *pool)
Destroy a thread pool.
struct thread_pool_entry thread_pool_entry_t
Definition thread_pool.h:96

References ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_THREAD, thread_pool::is_work_queue_mode, log_debug, log_error, log_info, thread_pool::name, thread_pool_entry::name, NAMED_REGISTER_COND, NAMED_REGISTER_MUTEX, NAMED_REGISTER_THREAD_POOL, thread_pool_entry::next, thread_pool::num_workers, SAFE_FREE, SAFE_MALLOC, SAFE_SNPRINTF, SAFE_STRNCPY, SET_ERRNO, thread_pool::shutdown_requested, thread_pool_entry::stop_id, thread_pool_entry::thread, thread_pool_entry::thread_arg, thread_pool::thread_count, thread_pool_entry::thread_func, thread_pool_destroy(), thread_pool::threads, thread_pool::threads_mutex, thread_pool::work_available, thread_pool::work_queue, and thread_pool::work_queue_mutex.

Referenced by websocket_server_init().

◆ thread_pool_destroy()

void thread_pool_destroy ( thread_pool_t * pool)

Destroy a thread pool.

Stops all threads (if not already stopped), waits for them to exit, and frees all pool resources. It's safe to call this even if threads are still running - they will be stopped first.

Parameters
poolThread pool to destroy (NULL is safe, does nothing)

Definition at line 226 of file thread_pool.c.

226 {
227 if (!pool) {
228 return;
229 }
230
231 log_debug("Destroying thread pool '%s' (thread_count=%zu, work_queue_mode=%d)", pool->name, pool->thread_count, pool->is_work_queue_mode);
232
233 // Stop all threads first (if not already stopped)
234 if (pool->thread_count > 0) {
235 log_debug("Thread pool '%s' has %zu threads, stopping them first", pool->name, pool->thread_count);
237 log_debug("After thread_pool_stop_all: pool->threads=%p, pool->thread_count=%zu", (void *)pool->threads, pool->thread_count);
238 }
239
240 mutex_lock(&pool->threads_mutex);
241 bool threads_still_running = pool->thread_count > 0;
242 mutex_unlock(&pool->threads_mutex);
243 if (threads_still_running) {
244 // A timed-out thread still owns access to this pool. Retain the pool and
245 // its synchronization objects so that worker cannot race freed memory.
246 log_error("Keeping thread pool '%s' alive because %zu worker thread(s) have not exited", pool->name, pool->thread_count);
247 return;
248 }
249
250 // Clean up work queue (in case there's pending work)
251 if (pool->is_work_queue_mode) {
252 mutex_lock(&pool->work_queue_mutex);
254 while (entry) {
255 thread_pool_work_entry_t *next = entry->next;
256 SAFE_FREE(entry);
257 entry = next;
258 }
259 pool->work_queue = NULL;
260 mutex_unlock(&pool->work_queue_mutex);
261
262 // Destroy condition variable and work queue mutex
263 cond_destroy(&pool->work_available);
264 mutex_destroy(&pool->work_queue_mutex);
265 }
266
267 // Destroy threads mutex
268 mutex_destroy(&pool->threads_mutex);
269
270 NAMED_UNREGISTER(pool);
271
272 // Free pool
273 log_debug("About to free thread pool '%s' at %p", pool->name, (void *)pool);
274 SAFE_FREE(pool);
275
276 log_debug("Thread pool destroyed (freed memory)");
277}
#define NAMED_UNREGISTER(ptr)
Unregister a pointer.
struct thread_pool_work_entry * next
Linked list next pointer.
asciichat_error_t thread_pool_stop_all(thread_pool_t *pool)
Stop all threads in the pool in stop_id order.
struct thread_pool_work_entry thread_pool_work_entry_t
One queued function call waiting for a thread-pool worker.

References thread_pool::is_work_queue_mode, log_debug, log_error, thread_pool::name, NAMED_UNREGISTER, thread_pool_work_entry::next, SAFE_FREE, thread_pool::thread_count, thread_pool_stop_all(), thread_pool::threads, thread_pool::threads_mutex, thread_pool::work_available, thread_pool::work_queue, and thread_pool::work_queue_mutex.

Referenced by acds_server_shutdown(), client_connection_destroy(), network_server_destroy(), thread_pool_create_with_workers(), and websocket_server_destroy().

◆ thread_pool_get_count()

size_t thread_pool_get_count ( const thread_pool_t * pool)

Get thread count in the pool.

Thread-safe count of active threads in the pool.

Parameters
poolThread pool to query
Returns
Number of threads in pool, or 0 if pool is NULL

Definition at line 485 of file thread_pool.c.

485 {
486 if (!pool) {
487 return 0;
488 }
489
490 // Note: We're not locking here for performance
491 // thread_count is a simple size_t which should be atomic on most platforms
492 // If strict thread safety is required, use mutex_lock/unlock
493 return pool->thread_count;
494}

References thread_pool::thread_count.

Referenced by thread_pool_has_threads().

◆ thread_pool_has_threads()

bool thread_pool_has_threads ( const thread_pool_t * pool)

Check if pool has any threads.

Convenience function equivalent to thread_pool_get_count(pool) > 0.

Parameters
poolThread pool to check
Returns
true if pool has threads, false if empty or NULL

Definition at line 496 of file thread_pool.c.

496 {
497 return thread_pool_get_count(pool) > 0;
498}
size_t thread_pool_get_count(const thread_pool_t *pool)
Get thread count in the pool.

References thread_pool_get_count().

◆ thread_pool_interrupt_all()

asciichat_error_t thread_pool_interrupt_all ( thread_pool_t * pool,
int sig )

Send a signal to all threads in the pool.

Sends the specified signal to every thread in the pool. This is used to interrupt threads that are blocked in system calls (e.g., recv(), connect()) so they unblock and can check the global exit flag.

Thread-safe: acquires threads_mutex to iterate the thread list. Not async-signal-safe: cannot be called from signal handlers.

On POSIX systems, uses pthread_kill() to send the signal. On Windows, this is a no-op (pthread_kill is not available, but socket_shutdown() is sufficient for Windows socket unblocking).

Typically used with SIGUSR1 (which should have a registered no-op handler) or another signal that the threads are prepared to handle gracefully.

Parameters
poolThread pool to interrupt
sigSignal number to send (e.g., SIGUSR1)
Returns
ASCIICHAT_OK on success, error code on failure

Definition at line 500 of file thread_pool.c.

500 {
501 if (!pool) {
502 return SET_ERRNO(ERROR_INVALID_PARAM, "pool is NULL");
503 }
504
505#ifndef _WIN32
506 // Only available on POSIX systems (Unix/Linux/macOS)
507 mutex_lock(&pool->threads_mutex);
508
509 if (pool->thread_count == 0) {
510 mutex_unlock(&pool->threads_mutex);
511 log_debug("Thread pool '%s' has no threads to interrupt", pool->name);
512 return ASCIICHAT_OK;
513 }
514
515 log_debug("Sending signal %d to %zu threads in pool '%s'", sig, pool->thread_count, pool->name);
516
517 // Iterate through all threads and send signal
518 thread_pool_entry_t *entry = pool->threads;
519 int sent_count = 0;
520 int failed_count = 0;
521
522 while (entry) {
523 // pthread_kill returns 0 on success, non-zero error code on failure
524 if (pthread_kill(entry->thread, sig) != 0) {
525 log_warn("Failed to send signal %d to thread '%s' in pool '%s'", sig, entry->name, pool->name);
526 failed_count++;
527 } else {
528 sent_count++;
529 }
530 entry = entry->next;
531 }
532
533 mutex_unlock(&pool->threads_mutex);
534
535 log_debug("Sent signal %d to %d/%zu threads in pool '%s' (%d failures)", sig, sent_count, pool->thread_count, pool->name, failed_count);
536
537 if (failed_count > 0 && sent_count == 0) {
538 return SET_ERRNO(ERROR_THREAD, "Failed to send signal to any threads in pool '%s'", pool->name);
539 }
540
541 return ASCIICHAT_OK;
542#else
543 // Windows: no pthread_kill equivalent needed - socket_shutdown() is sufficient
544 (void)sig; // Unused on Windows
545 log_debug("no-op on Windows (socket shutdown is sufficient)");
546 return ASCIICHAT_OK;
547#endif
548}
@ ASCIICHAT_OK
Definition error_codes.h:50
#define log_warn(...)
Log a WARN message.
Definition log/log.h:615

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_THREAD, log_debug, log_warn, thread_pool::name, thread_pool_entry::name, thread_pool_entry::next, SET_ERRNO, thread_pool_entry::thread, thread_pool::thread_count, thread_pool::threads, and thread_pool::threads_mutex.

◆ thread_pool_queue_work()

asciichat_error_t thread_pool_queue_work ( const char * name,
thread_pool_t * pool,
void *(* work_func )(void *),
void * work_arg )

Queue a named work item to a work queue pool.

Adds a named work item to the pool's work queue. One of the pre-created worker threads will pick up the work and execute it. This function is only valid for pools created with thread_pool_create_with_workers(). The work is automatically registered with the debug naming system.

Safe to call from callback context (e.g., LWS callbacks). Work is queued without creating new threads.

Parameters
nameDebug name for the work item
poolThread pool to queue work to (must be in work queue mode)
work_funcFunction to execute
work_argArgument passed to work function
Returns
ASCIICHAT_OK on success, error code on failure

Definition at line 279 of file thread_pool.c.

279 {
280 if (!name) {
281 return SET_ERRNO(ERROR_INVALID_PARAM, "work name is required");
282 }
283
284 if (!pool) {
285 return SET_ERRNO(ERROR_INVALID_PARAM, "pool is NULL");
286 }
287
288 if (!pool->is_work_queue_mode) {
289 return SET_ERRNO(ERROR_INVALID_STATE, "Pool not in work queue mode. Use thread_pool_create_with_workers()");
290 }
291
292 if (!work_func) {
293 return SET_ERRNO(ERROR_INVALID_PARAM, "work_func is NULL");
294 }
295
296 // Allocate work entry
298 if (!entry) {
299 return SET_ERRNO(ERROR_MEMORY, "Failed to allocate work entry");
300 }
301
302 entry->work_func = work_func;
303 entry->work_arg = work_arg;
304 entry->next = NULL;
305
306 // Register work with debug naming system
307 NAMED_REGISTER_THREADPOOL_WORK(entry, name, NULL);
308
309 // Add to work queue (at the end)
310 mutex_lock(&pool->work_queue_mutex);
311
312 // Find the last entry in the queue
313 if (!pool->work_queue) {
314 pool->work_queue = entry;
315 } else {
317 while (last->next) {
318 last = last->next;
319 }
320 last->next = entry;
321 }
322
323 // Signal workers that work is available (WHILE HOLDING MUTEX to prevent lost wakeup race)
324 cond_signal(&pool->work_available);
325
326 mutex_unlock(&pool->work_queue_mutex);
327
328 log_dev("Queued work to pool '%s' (workers=%zu)", pool->name, pool->num_workers);
329 return ASCIICHAT_OK;
330}
#define NAMED_REGISTER_THREADPOOL_WORK(work, name, parent_ptr)
Register a thread pool work item with automatic format specifier.
@ ERROR_INVALID_STATE
#define log_dev(...)
Log a DEV message (most verbose, development only).
Definition log/log.h:575
void * work_arg
Argument passed to work function.
void *(* work_func)(void *)
Work function to execute.

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_MEMORY, thread_pool::is_work_queue_mode, log_dev, thread_pool::name, NAMED_REGISTER_THREADPOOL_WORK, thread_pool_work_entry::next, thread_pool::num_workers, SAFE_MALLOC, SET_ERRNO, thread_pool_work_entry::work_arg, thread_pool::work_available, thread_pool_work_entry::work_func, thread_pool::work_queue, and thread_pool::work_queue_mutex.

◆ thread_pool_spawn()

asciichat_error_t thread_pool_spawn ( thread_pool_t * pool,
void *(* thread_func )(void *),
void * thread_arg,
int stop_id,
const char * thread_name )

Spawn a worker thread in the pool.

Creates and tracks a new worker thread with optional ordered cleanup. Threads are inserted into the pool's linked list in sorted order by stop_id (ascending). When the pool is stopped, threads with lower stop_id values are stopped first.

Stop ID Ordering Guidelines:

  • stop_id < 0: Unordered (stopped last, order undefined)
  • stop_id = 0: General background workers
  • stop_id = 1: Data source threads (e.g., receive, capture)
  • stop_id = 2: Processing threads (e.g., render, encode)
  • stop_id = 3: Data sink threads (e.g., send, write)

Example (Server Per-Client Threads):

  • stop_id=1: Receive thread (stop first to prevent new data)
  • stop_id=2: Render threads (stop after receive)
  • stop_id=3: Send thread (stop last after all processing)
Parameters
poolThread pool to spawn into
thread_funcThread function to execute
thread_argArgument passed to thread function
stop_idCleanup order (-1=unordered, 0+=ordered)
thread_nameThread name for debugging (max 63 chars, NULL=auto-generate)
Returns
ASCIICHAT_OK on success, error code on failure

Definition at line 332 of file thread_pool.c.

332 {
333 if (!pool) {
334 return SET_ERRNO(ERROR_INVALID_PARAM, "pool is NULL");
335 }
336
337 if (pool->is_work_queue_mode) {
338 return SET_ERRNO(ERROR_INVALID_STATE, "Cannot spawn threads in work queue mode. Use thread_pool_queue_work()");
339 }
340
341 if (!thread_func) {
342 return SET_ERRNO(ERROR_INVALID_PARAM, "thread_func is NULL");
343 }
344
345 // Allocate thread entry
347 if (!entry) {
348 return SET_ERRNO(ERROR_MEMORY, "Failed to allocate thread pool entry");
349 }
350
351 memset(entry, 0, sizeof(*entry));
352 entry->stop_id = stop_id;
353 entry->thread_func = thread_func;
354 entry->thread_arg = thread_arg;
355 entry->next = NULL;
356
357 // Copy thread name (truncate if necessary)
358 if (thread_name) {
359 SAFE_STRNCPY(entry->name, thread_name, sizeof(entry->name));
360 } else {
361 // Auto-generate name
362 SAFE_SNPRINTF(entry->name, sizeof(entry->name), "%s_worker_%d", pool->name, stop_id);
363 }
364
365 // Create thread
366 if (platform_thread_create(&entry->thread, entry->name, thread_func, thread_arg) != 0) {
367 // Save name before freeing entry
368 char thread_name_copy[THREAD_POOL_THREAD_NAME_COPY_BUFFER_SIZE];
369 SAFE_STRNCPY(thread_name_copy, entry->name, sizeof(thread_name_copy));
370 SAFE_FREE(entry);
371 return SET_ERRNO(ERROR_THREAD, "Failed to create thread '%s' in pool '%s'", thread_name_copy, pool->name);
372 }
373
374 // Add to thread list (sorted by stop_id)
375 mutex_lock(&pool->threads_mutex);
376
377 if (!pool->threads || pool->threads->stop_id > stop_id) {
378 // Insert at head
379 entry->next = pool->threads;
380 pool->threads = entry;
381 } else {
382 // Find insertion point (maintain sorted order by stop_id)
383 thread_pool_entry_t *prev = pool->threads;
384 while (prev->next && prev->next->stop_id <= stop_id) {
385 prev = prev->next;
386 }
387 entry->next = prev->next;
388 prev->next = entry;
389 }
390
391 pool->thread_count++;
392 mutex_unlock(&pool->threads_mutex);
393
394 log_debug("Spawned thread '%s' (stop_id=%d) in pool '%s' (total_threads=%zu)", entry->name, stop_id, pool->name, pool->thread_count);
395
396 return ASCIICHAT_OK;
397}
#define THREAD_POOL_THREAD_NAME_COPY_BUFFER_SIZE
Definition thread_pool.c:7

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_MEMORY, ERROR_THREAD, thread_pool::is_work_queue_mode, log_debug, thread_pool::name, thread_pool_entry::name, thread_pool_entry::next, SAFE_FREE, SAFE_MALLOC, SAFE_SNPRINTF, SAFE_STRNCPY, SET_ERRNO, thread_pool_entry::stop_id, thread_pool_entry::thread, thread_pool_entry::thread_arg, thread_pool::thread_count, thread_pool_entry::thread_func, THREAD_POOL_THREAD_NAME_COPY_BUFFER_SIZE, thread_pool::threads, and thread_pool::threads_mutex.

Referenced by acds_server_init(), audio_sender_init(), audio_start_thread(), capture_start_thread(), client_protocol_start(), keepalive_start_thread(), and server_main().

◆ thread_pool_stop_all()

asciichat_error_t thread_pool_stop_all ( thread_pool_t * pool)

Stop all threads in the pool in stop_id order.

Joins all threads in ascending stop_id order (lower values first). Threads with negative stop_id are stopped last in undefined order. This function blocks until all threads have exited.

Shutdown Sequence:

  1. Threads with stop_id >= 0 are joined in ascending order
  2. Threads with stop_id < 0 are joined in any order
  3. All thread entries are freed

After this call, the pool is empty but still valid - you can spawn new threads or destroy the pool.

Parameters
poolThread pool to stop
Returns
ASCIICHAT_OK on success, error code on failure

Definition at line 399 of file thread_pool.c.

399 {
400 if (!pool) {
401 return SET_ERRNO(ERROR_INVALID_PARAM, "pool is NULL");
402 }
403
404 mutex_lock(&pool->threads_mutex);
405
406 if (pool->thread_count == 0) {
407 mutex_unlock(&pool->threads_mutex);
408 log_debug("Thread pool '%s' has no threads to stop", pool->name);
409 return ASCIICHAT_OK;
410 }
411
412 log_debug("Stopping %zu threads in pool '%s' in stop_id order", pool->thread_count, pool->name);
413
414 // For work queue mode, signal workers to shutdown (BEFORE releasing the mutex to prevent new work)
415 if (pool->is_work_queue_mode) {
416 mutex_lock(&pool->work_queue_mutex);
417 pool->shutdown_requested = true;
418 cond_broadcast(&pool->work_available);
419 mutex_unlock(&pool->work_queue_mutex);
420 }
421
422 // Detach the current list so workers can finish without holding the pool
423 // mutex. Any thread that misses its join deadline is reinserted below.
424 thread_pool_entry_t *threads_to_join = pool->threads;
425 pool->threads = NULL;
426 pool->thread_count = 0;
427
428 // Release mutex BEFORE joining threads to prevent deadlock if workers need to acquire it
429 mutex_unlock(&pool->threads_mutex);
430
431 // Now join threads (WITHOUT holding the mutex to prevent deadlock)
432 thread_pool_entry_t *entry = threads_to_join;
433 int joined_count = 0, freed_count = 0, still_running_count = 0;
434 thread_pool_entry_t *still_running = NULL;
435 const uint64_t THREAD_JOIN_TIMEOUT_NS = 2 * 1000000000ULL; // 2 second timeout per thread
436
437 while (entry) {
438 log_debug("Joining thread '%s' (stop_id=%d) in pool '%s' with 2s timeout", entry->name, entry->stop_id, pool->name);
439 thread_pool_entry_t *next = entry->next;
440
441 // A timed-out worker may still access its pool and arguments. Keep its
442 // entry tracked so later shutdown can join it before freeing those objects.
443 int join_result = thread_join_timeout(&entry->thread, NULL, THREAD_JOIN_TIMEOUT_NS);
444 if (join_result != 0) {
445 if (join_result == ETIMEDOUT) {
446 log_warn("Thread '%s' (stop_id=%d) did not exit within 2s timeout; retaining its pool entry.", entry->name, entry->stop_id);
447 } else {
448 log_error("Failed to join thread '%s' in pool '%s' (error %d); retaining its pool entry", entry->name, pool->name, join_result);
449 }
450 entry->next = still_running;
451 still_running = entry;
452 still_running_count++;
453 entry = next;
454 continue;
455 } else {
456 joined_count++;
457 }
458
459 log_debug("Freeing thread_pool_entry '%s' at %p", entry->name, (void *)entry);
460 SAFE_FREE(entry);
461 freed_count++;
462 entry = next;
463 }
464
465 if (still_running) {
466 mutex_lock(&pool->threads_mutex);
467 while (still_running) {
468 thread_pool_entry_t *entry = still_running;
469 still_running = still_running->next;
470 entry->next = NULL;
471 thread_pool_insert_entry_locked(pool, entry);
472 }
473 mutex_unlock(&pool->threads_mutex);
474 }
475
476 log_debug("joined=%d, freed=%d", joined_count, freed_count);
477
478 log_debug("All threads stopped in pool '%s'", pool->name);
479 if (still_running_count > 0) {
480 return SET_ERRNO(ERROR_THREAD, "%d thread(s) in pool '%s' did not stop", still_running_count, pool->name);
481 }
482 return ASCIICHAT_OK;
483}
unsigned long long uint64_t

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_THREAD, thread_pool::is_work_queue_mode, log_debug, log_error, log_warn, thread_pool::name, thread_pool_entry::name, thread_pool_entry::next, SAFE_FREE, SET_ERRNO, thread_pool::shutdown_requested, thread_pool_entry::stop_id, thread_pool_entry::thread, thread_pool::thread_count, thread_pool::threads, thread_pool::threads_mutex, thread_pool::work_available, and thread_pool::work_queue_mutex.

Referenced by network_server_stop(), and thread_pool_destroy().