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.h File Reference

🧵 Thread lifecycle management helpers More...

Go to the source code of this file.

Macros

#define THREAD_IS_CREATED(created_flag)
#define THREAD_CREATE_SAFE(thread_var, func, arg)
#define THREAD_CREATE_OR_RETURN_VOID(thread_var, func, arg, error_msg)
#define THREAD_JOIN_SAFE(thread_var, exit_code)
#define THREAD_JOIN(thread_var)
#define THREAD_CLEAR_HANDLE(thread_var)

Detailed Description

🧵 Thread lifecycle management helpers

Provides macros and utilities for managing thread creation, initialization, and cleanup patterns. Reduces code duplication in modules that manage dedicated worker threads.

Common Pattern: Many modules in ascii-chat create dedicated threads with a similar lifecycle:

  1. Initialize a static thread handle
  2. Create the thread on demand
  3. Track creation status with a boolean flag
  4. Join the thread during cleanup
  5. Clear the handle to prevent accidental reuse

Usage:

// In module header
typedef struct {
platform_thread_t thread_handle;
bool created;
} my_worker_t;
// In module implementation
static my_worker_t g_worker = {0};
void start_worker(void) {
if (THREAD_IS_CREATED(g_worker.created)) {
return; // Already created
}
if (THREAD_CREATE_SAFE(g_worker.thread_handle, worker_func, NULL) != 0) {
log_error("Failed to create worker thread");
return;
}
g_worker.created = true;
}
void stop_worker(void) {
if (THREAD_IS_CREATED(g_worker.created)) {
THREAD_JOIN_SAFE(g_worker.thread_handle);
THREAD_CLEAR_HANDLE(g_worker.thread_handle);
g_worker.created = false;
}
}
#define log_error(...)
Log an ERROR message.
Definition log/log.h:628
#define THREAD_JOIN_SAFE(thread_var, exit_code)
Definition thread.h:123
#define THREAD_IS_CREATED(created_flag)
Definition thread.h:66
#define THREAD_CREATE_SAFE(thread_var, func, arg)
Definition thread.h:80
#define THREAD_CLEAR_HANDLE(thread_var)
Definition thread.h:149

Definition in file thread.h.

Macro Definition Documentation

◆ THREAD_CLEAR_HANDLE

#define THREAD_CLEAR_HANDLE ( thread_var)
Value:
memset(&(thread_var), 0, sizeof(thread_var))

Initialize a thread handle to an invalid/uninitialized state. Call this before creating the thread to ensure clean state.

Parameters
thread_varThread handle (platform_thread_t)

Usage:

static platform_thread_t g_worker = THREAD_INVALID;

Definition at line 149 of file thread.h.

◆ THREAD_CREATE_OR_RETURN_VOID

#define THREAD_CREATE_OR_RETURN_VOID ( thread_var,
func,
arg,
error_msg )
Value:
do { \
if (platform_thread_create(&(thread_var), (func), (arg)) != 0) { \
log_error("%s", (error_msg)); \
return; \
} \
} while (0)

Create a thread with automatic error handling and logging (void return version).

Parameters
thread_varThread handle (platform_thread_t)
funcThread function pointer
argThread argument
error_msgMessage to log on failure

On failure, logs an error and the macro exits the enclosing function with return. Useful for mandatory thread creation where failure is fatal.

Note: Use THREAD_CREATE_OR_RETURN from common.h for int-returning functions. This version is for void-returning functions with custom error messages.

Usage:

THREAD_CREATE_OR_RETURN_VOID(g_worker_thread, worker_func, NULL, "Failed to create worker");
#define THREAD_CREATE_OR_RETURN_VOID(thread_var, func, arg, error_msg)
Definition thread.h:101

Definition at line 101 of file thread.h.

101#define THREAD_CREATE_OR_RETURN_VOID(thread_var, func, arg, error_msg) \
102 do { \
103 if (platform_thread_create(&(thread_var), (func), (arg)) != 0) { \
104 log_error("%s", (error_msg)); \
105 return; \
106 } \
107 } while (0)

◆ THREAD_CREATE_SAFE

#define THREAD_CREATE_SAFE ( thread_var,
func,
arg )
Value:
platform_thread_create(&(thread_var), (func), (arg))

Safely create a thread with error handling and logging. Does NOT set the created flag - caller must do that.

Parameters
thread_varThread handle (platform_thread_t)
funcThread function pointer (void *(*)(void *))
argThread argument (void *)
Returns
Return value from platform_thread_create (0 on success)

This is a direct call to platform_thread_create with no error handling. Caller should check return value and log if needed.

Definition at line 80 of file thread.h.

◆ THREAD_IS_CREATED

#define THREAD_IS_CREATED ( created_flag)
Value:
((created_flag) == true)

Check if a thread has been created.

Parameters
created_flagBoolean flag indicating thread creation status
Returns
true if thread has been created, false otherwise

Definition at line 66 of file thread.h.

Referenced by audio_sender_cleanup(), audio_stop_thread(), capture_start_thread(), and capture_stop_thread().

◆ THREAD_JOIN

#define THREAD_JOIN ( thread_var)
Value:
thread_join(&(thread_var), NULL)

Join a thread without capturing its exit code. Simpler version when exit code is not needed.

Parameters
thread_varThread handle (platform_thread_t)

Usage:

THREAD_JOIN(g_worker_thread);
#define THREAD_JOIN(thread_var)
Definition thread.h:136

Definition at line 136 of file thread.h.

◆ THREAD_JOIN_SAFE

#define THREAD_JOIN_SAFE ( thread_var,
exit_code )
Value:
thread_join(&(thread_var), (exit_code))

Join a thread and wait for it to complete. Returns the thread's exit code in the output parameter.

Parameters
thread_varThread handle (platform_thread_t)
exit_codePointer to store thread exit code (void **), or NULL to ignore

Usage:

void *exit_code = NULL;
THREAD_JOIN_SAFE(g_worker_thread, &exit_code);
log_debug("Worker thread exited with code %p", exit_code);
#define log_debug(...)
Log a DEBUG message.
Definition log/log.h:589

Definition at line 123 of file thread.h.