Nilorea Library
C utilities for networking, threading, graphics
Loading...
Searching...
No Matches
THREADS: tools to create and manage a thread pool

Data Structures

struct  THREAD_POOL
 Structure of a thread pool. More...
struct  THREAD_POOL_NODE
struct  THREAD_WAITING_PROC
 Structure of a waiting process item. More...

Macros

#define DIRECT_PROC   4
 processing mode for added func, direct start, not queued
#define EXITED_THREAD   512
 indicate that the pool is off, all jobs have been consumed
#define EXITING_THREAD   256
 indicate that the pool is exiting, unfinished jobs will finish and the pool will exit the threads and enter the EXITED state
#define IDLE_PROC   16
 status of a thread which is waiting for some proc
#define N_THREAD_POOL_WAIT_POLL_US   1000
 A thread pool node.
#define NO_LOCK   1024
 if passed to add_threaded_process, skip main table lock in case we are in a func which is already locking it
#define NO_QUEUE   8
 special processing mode for waiting_list: do not add the work in queue since it' coming from the queue
#define NORMAL_PROC   1
 processing mode for added func, synced start, can be queued
#define RUNNING_PROC   64
 status of a thread which proc is currently running
#define RUNNING_THREAD   128
 indicate that the pool is running and ready to use
#define SYNCED_PROC   2
 processing mode for added func, synced start, not queued
#define WAITING_PROC   32
 status of a thread who have proc waiting to be processed

Typedefs

typedef void(* N_PARALLEL_FN) (size_t begin, size_t end, void *user)
 work done by n_parallel_for() on one slice [begin, end) of a range

Functions

int add_threaded_process (THREAD_POOL *thread_pool, void *(*func_ptr)(void *param), void *param, int mode)
 add a function to run in an available thread inside a pool
int destroy_threaded_pool (THREAD_POOL **thread_pool, unsigned int delay)
 stop every thread and free the pool; queued jobs still waiting when the retry budget runs out are discarded, see set_thread_pool_discard()
long int get_nb_cpu_cores ()
 get number of core of current system
int n_parallel_for (size_t begin, size_t end, size_t grain, N_PARALLEL_FN fn, void *user)
 Run a loop over a range on several cores, and return when all of it is done.
THREAD_POOL * new_thread_pool (size_t nbmaxthr, size_t nb_max_waiting)
 allocate a new thread pool
int refresh_thread_pool (THREAD_POOL *thread_pool)
 try to add some waiting process on some free thread slots, else do nothing
int set_thread_pool_discard (THREAD_POOL *thread_pool, void(*discard)(void *param))
 set the function destroy_threaded_pool() hands the param of each discarded queued job to
int start_threaded_pool (THREAD_POOL *thread_pool)
 tell all the waiting threads to start their associated process
int wait_for_synced_threaded_pool (THREAD_POOL *thread_pool)
 wait for all the threads in the pool to terminate processing, blocking but light on the CPU as there is no polling
int wait_for_threaded_pool (THREAD_POOL *thread_pool)
 wait for the pool to become idle (no active threads, empty waiting list), blocking without polling

Detailed Description


Data Structure Documentation

◆ THREAD_POOL

struct THREAD_POOL
Collaboration diagram for THREAD_POOL:
Data Fields
void(*)(void *param) discard Called by destroy_threaded_pool() with the param of every queued job it discards without running, so the caller can release it.

NULL by default: the params are then left alone and only counted in the log. Set with set_thread_pool_discard().

pthread_mutex_t lock mutex to prevent mutual access of waiting_list parameters
size_t max_threads Maximum number of running threads in the list.
size_t nb_actives number of threads actually doing a proc
size_t nb_max_waiting Maximum number of waiting procedures in the list, 0 for unlimited.
sem_t nb_tasks semaphore signaling pool idle state: value 0 = work in progress, value 1 = pool is idle (no active threads, empty waiting list).

Consumed by add_threaded_process and posted back only by refresh_thread_pool, so wait_for_threaded_pool() polls refresh rather than blocking on it.

THREAD_POOL_NODE ** thread_list Dynamically allocated but fixed size thread array.
LIST * waiting_list Waiting list handling.

◆ THREAD_POOL_NODE

struct THREAD_POOL_NODE

Definition at line 70 of file n_thread_pool.h.

Collaboration diagram for THREAD_POOL_NODE:
Data Fields
void *(*)(void *param) func function to call in the thread
pthread_mutex_t lock mutex to prevent mutual access of node parameters
void * param if not NULL , passed as argument
int state state of the proc , RUNNING_PROC when it is busy processing func( param) , IDLE_PROC when it waits for some func and param to process , WAITING_PROC when it has things waiting to be processed
sem_t th_end thread ending semaphore
sem_t th_start thread starting semaphore
pthread_t thr thread id
struct THREAD_POOL * thread_pool pointer to assigned thread pool
int thread_state state of the managing thread , RUNNING_THREAD, EXITING_THREAD, EXITED_THREAD
int type SYNCED or DIRECT process start.

◆ THREAD_WAITING_PROC

struct THREAD_WAITING_PROC

Structure of a waiting process item.

Definition at line 129 of file n_thread_pool.h.

Collaboration diagram for THREAD_WAITING_PROC:
Data Fields
void *(*)(void *param) func function to call in the thread
void * param if not NULL , passed as argument

Macro Definition Documentation

◆ DIRECT_PROC

#define DIRECT_PROC   4

processing mode for added func, direct start, not queued

Examples
ex_network.c, ex_network_ssl.c, and ex_network_ssl_hardened.c.

Definition at line 48 of file n_thread_pool.h.

Referenced by add_threaded_process(), main(), main(), and n_vigenere_cypher().

◆ EXITED_THREAD

#define EXITED_THREAD   512

indicate that the pool is off, all jobs have been consumed

Definition at line 62 of file n_thread_pool.h.

Referenced by destroy_threaded_pool(), and thread_pool_processing_function().

◆ EXITING_THREAD

#define EXITING_THREAD   256

indicate that the pool is exiting, unfinished jobs will finish and the pool will exit the threads and enter the EXITED state

Definition at line 60 of file n_thread_pool.h.

Referenced by destroy_threaded_pool(), new_thread_pool(), and thread_pool_processing_function().

◆ IDLE_PROC

#define IDLE_PROC   16

status of a thread which is waiting for some proc

Definition at line 52 of file n_thread_pool.h.

Referenced by add_threaded_process(), destroy_threaded_pool(), new_thread_pool(), and thread_pool_processing_function().

◆ N_THREAD_POOL_WAIT_POLL_US

#define N_THREAD_POOL_WAIT_POLL_US   1000

A thread pool node.

microseconds wait_for_threaded_pool() sleeps between pool-idleness checks

Definition at line 68 of file n_thread_pool.h.

Referenced by wait_for_threaded_pool().

◆ NO_LOCK

#define NO_LOCK   1024

if passed to add_threaded_process, skip main table lock in case we are in a func which is already locking it

Definition at line 64 of file n_thread_pool.h.

Referenced by add_threaded_process(), and refresh_thread_pool().

◆ NO_QUEUE

#define NO_QUEUE   8

special processing mode for waiting_list: do not add the work in queue since it' coming from the queue

Definition at line 50 of file n_thread_pool.h.

Referenced by add_threaded_process(), and refresh_thread_pool().

◆ NORMAL_PROC

#define NORMAL_PROC   1

processing mode for added func, synced start, can be queued

Examples
ex_accept_pool_client.c, ex_accept_pool_server.c, and ex_threads.c.

Definition at line 44 of file n_thread_pool.h.

Referenced by add_threaded_process(), dispatch_to_pool(), main(), main(), refresh_thread_pool(), and run().

◆ RUNNING_PROC

#define RUNNING_PROC   64

status of a thread which proc is currently running

Definition at line 56 of file n_thread_pool.h.

Referenced by refresh_thread_pool(), and thread_pool_processing_function().

◆ RUNNING_THREAD

#define RUNNING_THREAD   128

indicate that the pool is running and ready to use

Definition at line 58 of file n_thread_pool.h.

Referenced by add_threaded_process(), new_thread_pool(), and thread_pool_processing_function().

◆ SYNCED_PROC

#define SYNCED_PROC   2

processing mode for added func, synced start, not queued

Examples
ex_threads.c.

Definition at line 46 of file n_thread_pool.h.

Referenced by add_threaded_process(), main(), n_fluid_simulate_threaded(), start_threaded_pool(), thread_pool_processing_function(), and wait_for_synced_threaded_pool().

◆ WAITING_PROC

#define WAITING_PROC   32

status of a thread who have proc waiting to be processed

Definition at line 54 of file n_thread_pool.h.

Referenced by add_threaded_process(), refresh_thread_pool(), and start_threaded_pool().

Typedef Documentation

◆ N_PARALLEL_FN

typedef void(* N_PARALLEL_FN) (size_t begin, size_t end, void *user)

work done by n_parallel_for() on one slice [begin, end) of a range

Definition at line 157 of file n_thread_pool.h.

Function Documentation

◆ add_threaded_process()

int add_threaded_process ( THREAD_POOL * thread_pool,
void *(* func_ptr )(void *param),
void * param,
int mode )

add a function to run in an available thread inside a pool

add a function to run in an available thread inside a pool

Parameters
thread_poolThe target thread pool
func_ptrThe function pointer to launch
paramEventual parameter struct to pass to the function
modeNORMAL_PROC: add to an available active thread or queue in the waiting list. SYNCED_PROC: add to an available thread and wait for a start call, no waiting list. DIRECT_PROC: add to an available thread, no waiting list.
Returns
TRUE or FALSE

Definition at line 331 of file n_thread_pool.c.

References DIRECT_PROC, THREAD_WAITING_PROC::func, IDLE_PROC, list_push(), LOG_DEBUG, LOG_ERR, Malloc, mode, n_log, NO_LOCK, NO_QUEUE, NORMAL_PROC, THREAD_WAITING_PROC::param, RUNNING_THREAD, SYNCED_PROC, thread_pool, and WAITING_PROC.

Referenced by dispatch_to_pool(), main(), main(), main(), n_fluid_simulate_threaded(), n_vigenere_cypher(), refresh_thread_pool(), and run().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ destroy_threaded_pool()

int destroy_threaded_pool ( THREAD_POOL ** pool,
unsigned int delay )

stop every thread and free the pool; queued jobs still waiting when the retry budget runs out are discarded, see set_thread_pool_discard()

stop every thread and free the pool; queued jobs still waiting when the retry budget runs out are discarded, see set_thread_pool_discard()

Retries every delay microseconds, up to 1000 times, for each busy thread to go idle. A job finishing hands its thread the next queued job, so while the budget lasts the waiting list drains. When it runs out, every thread is told to exit and destroy joins them, which still waits for the job each is running. What running out of budget changes is only this: the jobs still in the waiting list are not run. They are counted in the log at LOG_ERR and, if set_thread_pool_discard() gave one, each param is handed to the discard function. Call wait_for_threaded_pool() first to have every queued job run.

Parameters
poolThe THREAD_POOL *object to kill; set to NULL on return
delaytime in usec between each check
Returns
TRUE or FALSE

Definition at line 573 of file n_thread_pool.c.

References __n_assert, DONE, EXITED_THREAD, EXITING_THREAD, Free, IDLE_PROC, list_destroy(), list_foreach, LOG_ERR, n_log, THREAD_WAITING_PROC::param, pool, and u_sleep().

Referenced by main(), main(), main(), n_vigenere_cypher(), and run().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ get_nb_cpu_cores()

long int get_nb_cpu_cores ( )

get number of core of current system

Definition at line 139 of file n_thread_pool.c.

Referenced by main(), main(), main(), n_parallel_for(), and new_n_fluid().

Here is the caller graph for this function:

◆ n_parallel_for()

int n_parallel_for ( size_t begin,
size_t end,
size_t grain,
N_PARALLEL_FN fn,
void * user )

Run a loop over a range on several cores, and return when all of it is done.

The range [begin, end) is cut into contiguous slices, at least grain items each, and fn is called once per slice, the calling thread doing one of them. Slices never overlap, so a loop whose iterations write only their own item needs no lock.

The extra threads come from one budget shared by the whole process: the cores less one. A caller that finds it spent - because many workers of a pool are each running a parallel loop - gets fewer threads or none, and runs the rest itself, so nested and concurrent use never oversubscribes the machine. A range smaller than two grains runs on the calling thread alone, with no thread started.

Parameters
beginfirst index
endone past the last index
grainsmallest slice worth a thread of its own; 0 is taken as 1
fnthe work for one slice
userpassed to every call of fn
Returns
the number of slices it was run in, at least 1 for a non empty range, 0 otherwise

Definition at line 75 of file n_thread_pool.c.

References N_PARALLEL_SLICE::begin, N_PARALLEL_SLICE::end, N_PARALLEL_SLICE::fn, get_nb_cpu_cores(), n_parallel_slice(), parallel_budget, parallel_lock, and N_PARALLEL_SLICE::user.

Referenced by main(), and nested().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ new_thread_pool()

THREAD_POOL * new_thread_pool ( size_t nbmaxthr,
size_t nb_max_waiting )

allocate a new thread pool

allocate a new thread pool

Parameters
nbmaxthrnumber of active threads in the pool
nb_max_waitingmax number of waiting procs in the pool. Zero for no limit
Returns
NULL or a new thread pool object

Definition at line 227 of file n_thread_pool.c.

References EXITING_THREAD, Free, IDLE_PROC, list_destroy(), LOG_ERR, Malloc, MAX_LIST_ITEMS, n_log, new_generic_list(), RUNNING_THREAD, thread_pool, and thread_pool_processing_function().

Referenced by main(), main(), main(), n_vigenere_cypher(), and run().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ refresh_thread_pool()

int refresh_thread_pool ( THREAD_POOL * thread_pool)

try to add some waiting process on some free thread slots, else do nothing

try to add some waiting process on some free thread slots, else do nothing

Parameters
thread_poolThe thread pool to refresh
Returns
TRUE or FALSE

Definition at line 670 of file n_thread_pool.c.

References __n_assert, add_threaded_process(), Free, THREAD_WAITING_PROC::func, LOG_DEBUG, LOG_ERR, n_log, LIST_NODE::next, NO_LOCK, NO_QUEUE, NORMAL_PROC, THREAD_WAITING_PROC::param, LIST_NODE::ptr, remove_list_node, RUNNING_PROC, thread_pool, and WAITING_PROC.

Referenced by main(), n_fluid_simulate_threaded(), n_vigenere_cypher(), thread_pool_processing_function(), and wait_for_threaded_pool().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ set_thread_pool_discard()

int set_thread_pool_discard ( THREAD_POOL * thread_pool,
void(* discard )(void *param) )

set the function destroy_threaded_pool() hands the param of each discarded queued job to

set the function destroy_threaded_pool() hands the param of each discarded queued job to

The pool never owns a job's param and cannot know how to release one. A job still in the waiting list when destroy_threaded_pool() gives up waiting is not run, so nothing else will ever see its param; this callback is the one place that can release it. Without one those params are left alone, which is a leak whenever the caller allocated them.

Parameters
thread_poolThe pool. Must not be NULL.
discardCalled once per discarded param, from the thread calling destroy_threaded_pool(), after every worker has been joined. NULL to leave discarded params alone, which is the default.
Returns
TRUE, or FALSE if thread_pool is NULL

Definition at line 549 of file n_thread_pool.c.

References __n_assert, and thread_pool.

Referenced by run().

Here is the caller graph for this function:

◆ start_threaded_pool()

int start_threaded_pool ( THREAD_POOL * thread_pool)

tell all the waiting threads to start their associated process

tell all the waiting threads to start their associated process

Parameters
thread_poolThe thread pool to launch
Returns
TRUE or FALSE

Definition at line 437 of file n_thread_pool.c.

References LOG_ERR, n_log, SYNCED_PROC, thread_pool, and WAITING_PROC.

Referenced by main(), and n_fluid_simulate_threaded().

Here is the caller graph for this function:

◆ wait_for_synced_threaded_pool()

int wait_for_synced_threaded_pool ( THREAD_POOL * thread_pool)

wait for all the threads in the pool to terminate processing, blocking but light on the CPU as there is no polling

wait for all the threads in the pool to terminate processing, blocking but light on the CPU as there is no polling

Parameters
thread_poolThe thread pool to wait
Returns
TRUE or FALSE

Definition at line 472 of file n_thread_pool.c.

References __n_assert, LOG_ERR, n_log, SYNCED_PROC, and thread_pool.

Referenced by main(), and n_fluid_simulate_threaded().

Here is the caller graph for this function:

◆ wait_for_threaded_pool()

int wait_for_threaded_pool ( THREAD_POOL * thread_pool)

wait for the pool to become idle (no active threads, empty waiting list), blocking without polling

wait for the pool to become idle (no active threads, empty waiting list), blocking without polling

Parameters
thread_poolThe thread pool to wait on
Returns
TRUE or FALSE

Definition at line 501 of file n_thread_pool.c.

References __n_assert, LOG_ERR, n_log, N_THREAD_POOL_WAIT_POLL_US, refresh_thread_pool(), thread_pool, and u_sleep().

Referenced by main(), main(), main(), and n_vigenere_cypher().

Here is the call graph for this function:
Here is the caller graph for this function: