vl_thread_pool.c File Reference

#include "vl_thread_pool.h"
#include "vl_condition.h"
#include "vl_memory.h"

Include dependency graph for vl_thread_pool.c:

Functions
VL_API vl_thread_pool *	vlThreadPoolNew (vl_uint_t worker_count)
	Creates a new priority-aware thread pool with work-stealing.
VL_API void	vlThreadPoolDelete (vl_thread_pool *pool)
	Deletes a thread pool and frees all associated resources.
VL_API vl_bool_t	vlThreadPoolEnqueuePriority (vl_thread_pool *pool, vl_thread_pool_priority priority, const vl_thread_pool_task *task)
	Enqueues a single work item at the specified priority level.
VL_API vl_uint_t	vlThreadPoolEnqueueBatchPriority (vl_thread_pool *pool, vl_thread_pool_priority priority, const vl_thread_pool_task *tasks, vl_uint_t count)
	Enqueues multiple work items at the same priority level in a batch.
VL_API vl_bool_t	vlThreadPoolWait (vl_thread_pool *pool, vl_uint_t timeout_ms)
	Waits until all enqueued tasks across all priority tiers have completed.
VL_API void	vlThreadPoolShutdown (vl_thread_pool *pool)
	Initiates graceful shutdown of the thread pool.
VL_API void	vlThreadPoolGetStats (vl_thread_pool *pool, vl_thread_pool_stats *out_stats)
	Retrieves a snapshot of current thread pool statistics.

Function Documentation

vlThreadPoolDelete()

VL_API void vlThreadPoolDelete

(

vl_thread_pool *

pool

)

Deletes a thread pool and frees all associated resources.

Threads must have been joined via shutdown. If threads are still active, behavior is undefined.

Contract

• Ownership: Releases ownership of the thread pool handle and all its internal resources.
• Lifetime: The thread pool handle becomes invalid immediately after this call.
• Thread Safety: Safe to call from any thread, provided no other thread is concurrently using the pool.
• Nullability: Safe to call with NULL (no-op).
• Error Conditions: None.
• Undefined Behavior: Double deletion. Deleting a pool that is being used by another thread.
• Memory Allocation Expectations: Deallocates all heap-allocated resources associated with the pool.
• Return-value Semantics: None (void).

Parameters

pool	Thread pool handle to delete

Warning

Call vlThreadPoolShutdown() first and ensure all threads have exited.

See also

vlThreadPoolShutdown, vlThreadPoolWait

Here is the call graph for this function:

vlThreadPoolEnqueueBatchPriority()

VL_API vl_uint_t vlThreadPoolEnqueueBatchPriority	(	vl_thread_pool *	pool,
		vl_thread_pool_priority	priority,
		const vl_thread_pool_task *	tasks,
		vl_uint_t	count
	)

Enqueues multiple work items at the same priority level in a batch.

This is more efficient than multiple individual enqueues. All tasks are added to the same priority queue atomically.

Contract

• Ownership: The pool copies the tasks in the tasks array into its internal storage.
• Lifetime: Unchanged.
• Thread Safety: Thread-safe (lock-free).
• Nullability: Returns 0 if pool or tasks is NULL.
• Error Conditions: Returns 0 if the pool is shutting down.
• Undefined Behavior: None.
• Memory Allocation Expectations: May trigger node allocation in the underlying async queues.
• Return-value Semantics: Returns the number of tasks successfully enqueued.

Parameters

pool	Thread pool handle
priority	Priority level for all tasks
tasks	Pointer to array of task structures
count	Number of tasks in the array

Returns

Number of tasks successfully enqueued (< count if shutdown in progress)

Note

This function is lock-free and safe to call concurrently.

See also

vlThreadPoolEnqueuePriority

Here is the call graph for this function:

vlThreadPoolEnqueuePriority()

VL_API vl_bool_t vlThreadPoolEnqueuePriority	(	vl_thread_pool *	pool,
		vl_thread_pool_priority	priority,
		const vl_thread_pool_task *	task
	)

Enqueues a single work item at the specified priority level.

The task is atomically added to the appropriate priority queue and a waiting worker thread is signaled. If no workers are waiting, the task is queued for later execution.

Contract

• Ownership: The pool copies the task data into its internal storage. The caller retains ownership of the task pointer.
• Lifetime: Unchanged.
• Thread Safety: Thread-safe (lock-free).
• Nullability: Returns VL_FALSE if pool or task is NULL.
• Error Conditions: Returns VL_FALSE if the pool is in the process of shutting down.
• Undefined Behavior: None.
• Memory Allocation Expectations: May trigger node allocation in the underlying async queues.
• Return-value Semantics: Returns VL_TRUE if the task was successfully enqueued, VL_FALSE otherwise.

Parameters

pool	Thread pool handle
priority	Priority level (HIGH, MEDIUM, or LOW)
task	Pointer to task structure (copied internally)

Returns

VL_TRUE on success, VL_FALSE if pool is shutting down

Note

This function is lock-free and safe to call concurrently from any thread.

See also

vlThreadPoolEnqueueBatchPriority, vlThreadPoolWait

Here is the call graph for this function:

vlThreadPoolGetStats()

VL_API void vlThreadPoolGetStats	(	vl_thread_pool *	pool,
		vl_thread_pool_stats *	out_stats
	)

Retrieves a snapshot of current thread pool statistics.

Returns completed task count and per-priority queue depths.

Contract

• Ownership: None.
• Lifetime: Unchanged.
• Thread Safety: Thread-safe (atomic reads).
• Nullability: pool and out_stats should not be NULL.
• Error Conditions: None.
• Undefined Behavior: Passing NULL.
• Memory Allocation Expectations: None.
• Return-value Semantics: None (void).

Parameters

pool	Thread pool handle
out_stats	Pointer to stats structure to populate

Note

Statistics are atomic but may be stale by the time this function returns.

See also

vl_thread_pool_stats

vlThreadPoolNew()

VL_API vl_thread_pool * vlThreadPoolNew

(

vl_uint_t

worker_count

)

Creates a new priority-aware thread pool with work-stealing.

Worker threads are created immediately and begin waiting for work. Threads employ a work-stealing strategy: HIGH -> MEDIUM -> LOW, with stealing from lower tiers when higher tiers are empty.

Contract

• Ownership: The caller owns the returned vl_thread_pool handle and is responsible for calling vlThreadPoolDelete.
• Lifetime: The thread pool remains valid until vlThreadPoolDelete.
• Thread Safety: This function is thread-safe.
• Nullability: Returns NULL if worker_count is 0 or if the pool could not be created.
• Error Conditions: Returns NULL if any heap allocation fails or if worker threads cannot be spawned.
• Undefined Behavior: None.
• Memory Allocation Expectations: Allocates the pool structure, worker handles, queues, and synchronization primitives on the heap.
• Return-value Semantics: Returns an opaque handle to the new thread pool, or NULL on failure.

Parameters

worker_count

Number of worker threads to create (must be > 0)

Returns

Thread pool handle, or VL_THREAD_POOL_NULL on failure

Note

If worker_count is 0 or thread creation fails, returns null.

See also

vlThreadPoolDelete

Here is the call graph for this function:

vlThreadPoolShutdown()

VL_API void vlThreadPoolShutdown

(

vl_thread_pool *

pool

)

Initiates graceful shutdown of the thread pool.

After calling this function:

• No new tasks are accepted (vlThreadPoolEnqueuePriority returns VL_FALSE)
• In-flight tasks across all priorities continue to completion
• Worker threads exit naturally

This function does not wait for threads. Use vlThreadPoolWait() to block until idle, or vlThreadPoolDelete() to join and cleanup.

Contract

• Ownership: Unchanged.
• Lifetime: The pool enters a shutting-down state.
• Thread Safety: Thread-safe.
• Nullability: Safe to call with NULL (no-op).
• Error Conditions: None.
• Undefined Behavior: None.
• Memory Allocation Expectations: None.
• Return-value Semantics: None (void).

Parameters

pool	Thread pool handle

Note

Safe to call multiple times (idempotent).

See also

vlThreadPoolDelete, vlThreadPoolWait

Here is the call graph for this function:

Here is the caller graph for this function:

vlThreadPoolWait()

VL_API vl_bool_t vlThreadPoolWait	(	vl_thread_pool *	pool,
		vl_uint_t	timeout_ms
	)

Waits until all enqueued tasks across all priority tiers have completed.

Blocks the calling thread until all HIGH, MEDIUM, and LOW priority queues are empty and all workers are idle. May be called concurrently from multiple threads; all will unblock when the pool becomes empty.

Contract

• Ownership: Unchanged.
• Lifetime: Unchanged.
• Thread Safety: Thread-safe (blocking).
• Nullability: Returns VL_FALSE if pool is NULL.
• Error Conditions: Returns VL_FALSE if the timeout expires.
• Undefined Behavior: None.
• Memory Allocation Expectations: None.
• Return-value Semantics: Returns VL_TRUE if the pool became idle within the timeout, VL_FALSE otherwise.

Parameters

pool	Thread pool handle
timeout_ms	Maximum time to wait in milliseconds (0 = infinite)

Returns

VL_TRUE if all tasks completed, VL_FALSE if timeout expired

Note

If new tasks are enqueued from other threads while waiting, behavior is implementation-specific (may or may not wait for them).

See also

vlThreadPoolEnqueuePriority

Here is the call graph for this function: