Submitting Tasks to the Thread Pool

The Producer-Consumer Model

A thread pool is a classic example of the producer-consumer problem.

• Producers create work and add it to a shared buffer (our task queue).
• Consumers take work from the buffer and process it.

In our case, the worker threads are the consumers. The "producer" is any part of your application that calls the function to submit a task—most commonly, the main thread.

The diagram below illustrates this flow. The Main Thread (producer) submits a task, which goes into the Waiting Queue. A Worker Thread (consumer) then takes a task from the queue to execute.

The Logic of Submitting a Task

To implement our threadpool_add_task function, we need to perform a sequence of operations very carefully to ensure thread safety and correctness. The core logic involves these five steps:

1. Allocate and Initialize a Task: Dynamically allocate memory for a thread_task_t struct and populate it with the function pointer and argument provided by the caller.
2. Acquire the Lock: Before accessing the shared task queue, we must lock the pool's mutex (pthread_mutex_lock) to prevent race conditions.
3. Add the Task to the Queue: Append the newly created task to the end of our linked list queue.
4. Signal a Waiting Worker: After the task is successfully added, we must wake up one of the sleeping worker threads. This is done by calling pthread_cond_signal.
5. Release the Lock: Unlock the mutex (pthread_mutex_unlock) to allow other threads (either producers or consumers) to access the queue.

Let's see how this is implemented in practice.

Deconstructing the Task Submission Function

Let's integrate the logic from the reading into our own threadpool_t structure. The implementation will look like this:

// Our structs for context (from previous lessons)
typedef struct thread_task {
    void (*function)(void*);
    void *argument;
    struct thread_task *next;
} thread_task_t;

typedef struct threadpool {
    pthread_mutex_t lock;
    pthread_cond_t notify;
    pthread_t *threads;
    thread_task_t *head;
    thread_task_t *tail;
    int thread_count;
    int task_count;
    int shutdown;
} threadpool_t;

// The function to add a task
int threadpool_add_task(threadpool_t *pool, void (*function)(void*), void *argument) {
    if (pool == NULL || function == NULL) {
        return -1; // Invalid arguments
    }

    // 1. Allocate a new task structure
    thread_task_t *task = (thread_task_t *)malloc(sizeof(thread_task_t));
    if (task == NULL) {
        return -1; // Malloc failed
    }
    task->function = function;
    task->argument = argument;
    task->next = NULL;

    // 2. Lock the mutex to protect the queue
    pthread_mutex_lock(&(pool->lock));

    // 3. Add the task to the end of the queue
    if (pool->task_count == 0) {
        pool->head = task;
        pool->tail = task;
    } else {
        pool->tail->next = task;
        pool->tail = task;
    }
    pool->task_count++;

    // 4. Signal a worker thread that a new task is available
    pthread_cond_signal(&(pool->notify));

    // 5. Unlock the mutex
    pthread_mutex_unlock(&(pool->lock));

    return 0; // Success
}

This function is the public API for submitting work. It encapsulates all the necessary synchronization, making it safe to be called by multiple producer threads simultaneously.

Signaling: pthread_cond_signal vs. pthread_cond_broadcast

In our code, we used pthread_cond_signal, but the "John's Blog" article used pthread_cond_broadcast. What's the difference?

• pthread_cond_signal: Wakes up at least one thread that is currently waiting on the condition variable. If no threads are waiting, the signal is lost.
• pthread_cond_broadcast: Wakes up all threads that are currently waiting on the condition variable.

When adding a single task, pthread_cond_signal is generally more efficient. It wakes one worker to handle the one new task. Using pthread_cond_broadcast would wake up all idle workers, who would then all contend for the mutex lock. Only one would succeed in taking the task, and the rest would find the queue empty and go back to sleep. This unnecessary contention is known as the "thundering herd" problem.

So why might one use broadcast? It can be simpler and is sometimes necessary if a state change might satisfy multiple threads (e.g., adding a batch of 10 tasks, or signaling a pool-wide shutdown). For our one-task-at-a-time submission, signal is the better choice.

Let's watch a video that builds this submission logic from the ground up.

// ... inside threadpool_add_task ...
    pool->task_count++;

    // Unlock first...
    pthread_mutex_unlock(&(pool->lock));

    // ...then signal.
    pthread_cond_signal(&(pool->notify));

    return 0;

Finally, let's look at one more resource that provides a very clear, concise pseudo-code and C implementation of the producer side.

Conclusion

Congratulations! You have now implemented both sides of the producer-consumer pattern for our thread pool. The worker threads ("consumers") can wait for work, and now you have a safe and efficient threadpool_add_task function for the "producers" to submit work.

Key Takeaways:

• Submitting a task is the "producer" role in the producer-consumer pattern.
• The five steps for task submission are: allocate task, lock mutex, add to queue, signal worker, and unlock mutex.
• pthread_cond_signal is used to wake up a single sleeping worker thread after a task is added.
• For adding single tasks, pthread_cond_signal is generally more efficient than pthread_cond_broadcast as it avoids the "thundering herd" problem.
• Unlocking the mutex before signaling is a valid and often preferred optimization to reduce lock contention.

Preview of the Next Lesson:
Our thread pool can be created, can execute tasks in parallel, and can have new tasks submitted to it. The last piece of essential functionality is a graceful shutdown. In the next lesson, we will design and implement the threadpool_destroy function, which will ensure that all pending tasks are completed before the threads are joined and all resources are deallocated.