threadpool-a simple thread pool based on pthread
Introduction to Thread Pool
Thread pool can be said to be a component that is often used in projects. It is assumed that the reader has a certain multithreading foundation. If not, it is better to understand it here: POSIX multithreading foundation.
What is a thread pool? My simple understanding is that there is a set of pre-derived threads, and then an administrator to manage and schedule these threads, you just need to constantly give him the task to complete, he will schedule the resources of the thread to help you complete.
So what does the administrator do? A simple way is for an administrator to manage a task queue and add tasks to the end of the queue if new tasks are received. Each thread stares at the queue. If the queue is not empty, it takes a task to process at the head of the queue (each task can only be taken by one thread). After processing, it goes on to the queue to fetch the task. If there are no tasks, the thread will sleep until the task queue is not empty. If the administrator is smarter, he may reduce the number of threads when there are no tasks or few tasks, and increase the number of threads when tasks can not be handled later, thus realizing the dynamic management of resources.
So what is the task? In the background server, for example, every user's request is a task. Threads constantly take requests out of the request queue and continue to process the next request after completion.
The simple illustration is as follows:
One advantage of thread pooling is that it reduces the time of thread creation and destruction. This benefit is very significant when the task processing time is relatively short, and it can improve the efficiency of task processing.
Thread pool implementation
Here is a simple implementation of thread pool, which pre-derives a specified number of threads at the time of creation, and then goes to the task queue to fetch the added tasks for processing.
The author says that more features will be added later, so we can use this version as a guide after learning.
Project Home Page: threadpool
data structure
There are mainly two custom data structures
threadpool_task_t
Used to save a task waiting to be executed. A task needs to be specified: the corresponding function to be run and the parameters of the function. So there are function pointers and void pointers in the struct.
typedef struct { void (*function)(void *); void *argument; } threadpool_task_t;
thread_pool_t
The structure of a thread pool. Because it is C language, the task queue here is implemented by using arrays and maintaining the head and tail of the queue.
struct threadpool_t { pthread_mutex_t lock; /* mutex */ pthread_cond_t notify; /* Conditional variable */ pthread_t *threads; /* Starting Pointer of Thread Array */ threadpool_task_t *queue; /* Starting Pointer of Task Queue Array */ int thread_count; /* Number of threads */ int queue_size; /* Task queue length */ int head; /* Current task queue head */ int tail; /* End of current task queue */ int count; /* Number of tasks currently to be run */ int shutdown; /* Is the current state of the thread pool closed? */ int started; /* Number of threads running */ };
function
External interface
- threadpool_t *threadpool_create(int thread_count, int queue_size, int flags); create a thread pool, use thread_count to specify the number of derived threads, queue_size to specify the length of task queue, flags as reserved parameters, unused.
- int threadpool_add(threadpool_t *pool, void (*routine)(void *),void *arg, int flags); add tasks to be performed. The second parameter is the corresponding function pointer, and the third is the corresponding function parameter. Flags is not in use.
- Int threadpool_destroy (threadpool_t*pool, int flags); destroy the existing thread pool. Flags can specify whether to end immediately or peacefully. Immediate termination refers to the immediate termination of a task queue regardless of whether it is empty or not. Peaceful ending refers to waiting for tasks in the task queue to complete after the completion of the task, in this process can not add new tasks.
Internal auxiliary function
- static void *threadpool_thread(void *threadpool); functions executed by each thread in the thread pool.
- Int threadpool_free (threadpool_t*pool); releases the memory resources requested by the thread pool.
Thread pool usage
Compile
Refer to Makefile in the project root directory and compile it directly with make.
test case
The project provides three test cases (see threadpool/test/), which we can use to learn the use of thread pools and test whether they work properly. Here is one of them:
#define THREAD 32 #define QUEUE 256 #include <stdio.h> #include <pthread.h> #include <unistd.h> #include <assert.h> #include "threadpool.h" int tasks = 0, done = 0; pthread_mutex_t lock; void dummy_task(void *arg) { usleep(10000); pthread_mutex_lock(&lock); /* Record the number of successful tasks completed */ done++; pthread_mutex_unlock(&lock); } int main(int argc, char **argv) { threadpool_t *pool; /* Initialize mutex */ pthread_mutex_init(&lock, NULL); /* Assertion Thread Pool Creation Successful */ assert((pool = threadpool_create(THREAD, QUEUE, 0)) != NULL); fprintf(stderr, "Pool started with %d threads and " "queue size of %d\n", THREAD, QUEUE); /* As long as the task queue is not full, add it all the time */ while(threadpool_add(pool, &dummy_task, NULL, 0) == 0) { pthread_mutex_lock(&lock); tasks++; pthread_mutex_unlock(&lock); } fprintf(stderr, "Added %d tasks\n", tasks); /* Continuously check whether the number of tasks is more than half completed, and if not continue to sleep. */ while((tasks / 2) > done) { usleep(10000); } /* At this point, destroy the thread pool, 0 for immediate_shutdown */ assert(threadpool_destroy(pool, 0) == 0); fprintf(stderr, "Did %d tasks\n", done); return 0; }
Source Code Annotations
Source comments are put together in github. Click on me.
threadpool.h
/* * Copyright (c) 2013, Mathias Brossard <mathias@brossard.org>. * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are * met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ #ifndef _THREADPOOL_H_ #define _THREADPOOL_H_ #ifdef __cplusplus /* For C++ compilers, specify C's syntax compilation */ extern "C" { #endif /** * @file threadpool.h * @brief Threadpool Header File */ /** * Increase this constants at your own risk * Large values might slow down your system */ #define MAX_THREADS 64 #define MAX_QUEUE 65536 /* Simplified variable definition */ typedef struct threadpool_t threadpool_t; /* Define error codes */ typedef enum { threadpool_invalid = -1, threadpool_lock_failure = -2, threadpool_queue_full = -3, threadpool_shutdown = -4, threadpool_thread_failure = -5 } threadpool_error_t; typedef enum { threadpool_graceful = 1 } threadpool_destroy_flags_t; /* Here are three external API s for thread pool */ /** * @function threadpool_create * @brief Creates a threadpool_t object. * @param thread_count Number of worker threads. * @param queue_size Size of the queue. * @param flags Unused parameter. * @return a newly created thread pool or NULL */ /** * Create a thread pool with thread_count threads and queue_size task queues. The flags parameter is not used */ threadpool_t *threadpool_create(int thread_count, int queue_size, int flags); /** * @function threadpool_add * @brief add a new task in the queue of a thread pool * @param pool Thread pool to which add the task. * @param function Pointer to the function that will perform the task. * @param argument Argument to be passed to the function. * @param flags Unused parameter. * @return 0 if all goes well, negative values in case of error (@see * threadpool_error_t for codes). */ /** * Add tasks to thread pool, pool is thread pool pointer, routine is function pointer, arg is function parameter, flags is not used */ int threadpool_add(threadpool_t *pool, void (*routine)(void *), void *arg, int flags); /** * @function threadpool_destroy * @brief Stops and destroys a thread pool. * @param pool Thread pool to destroy. * @param flags Flags for shutdown * * Known values for flags are 0 (default) and threadpool_graceful in * which case the thread pool doesn't accept any new tasks but * processes all pending tasks before shutdown. */ /** * Destroy thread pools, flags can be used to specify how to close them */ int threadpool_destroy(threadpool_t *pool, int flags); #ifdef __cplusplus } #endif #endif /* _THREADPOOL_H_ */
threadpool.c
/* * Copyright (c) 2013, Mathias Brossard <mathias@brossard.org>. * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are * met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ /** * @file threadpool.c * @brief Threadpool implementation file */ #include <stdlib.h> #include <pthread.h> #include <unistd.h> #include "threadpool.h" /** * How thread pool closes */ typedef enum { immediate_shutdown = 1, graceful_shutdown = 2 } threadpool_shutdown_t; /** * @struct threadpool_task * @brief the work struct * * @var function Pointer to the function that will perform the task. * @var argument Argument to be passed to the function. */ /** * Definition of a task in thread pool */ typedef struct { void (*function)(void *); void *argument; } threadpool_task_t; /** * @struct threadpool * @brief The threadpool struct * * @var notify Condition variable to notify worker threads. * @var threads Array containing worker threads ID. * @var thread_count Number of threads * @var queue Array containing the task queue. * @var queue_size Size of the task queue. * @var head Index of the first element. * @var tail Index of the next element. * @var count Number of pending tasks * @var shutdown Flag indicating if the pool is shutting down * @var started Number of started threads */ /** * Structural Definition of Thread Pool * @var lock Mutex Locks for Internal Work * @var notify Conditional variables for interthread notifications * @var threads Thread array, represented here by pointer, array name = first element pointer * @var thread_count Number of threads * @var queue An array of stored tasks, namely task queues * @var queue_size Task queue size * @var head The first task position in the task queue (Note: All tasks in the task queue are not running) * @var tail Next location of the last task in the task queue (note: queues are stored in arrays, and head and tail indicate queue location) * @var count The number of tasks in the task queue, that is, the number of tasks waiting to run * @var shutdown Indicates whether the thread pool is closed * @var started Number of threads started */ struct threadpool_t { pthread_mutex_t lock; pthread_cond_t notify; pthread_t *threads; threadpool_task_t *queue; int thread_count; int queue_size; int head; int tail; int count; int shutdown; int started; }; /** * @function void *threadpool_thread(void *threadpool) * @brief the worker thread * @param threadpool the pool which own the thread */ /** * Functions in the thread pool where each thread is running * Declare that static should only be used to make functions valid in this file */ static void *threadpool_thread(void *threadpool); int threadpool_free(threadpool_t *pool); threadpool_t *threadpool_create(int thread_count, int queue_size, int flags) { if(thread_count <= 0 || thread_count > MAX_THREADS || queue_size <= 0 || queue_size > MAX_QUEUE) { return NULL; } threadpool_t *pool; int i; /* Request memory to create memory pool objects */ if((pool = (threadpool_t *)malloc(sizeof(threadpool_t))) == NULL) { goto err; } /* Initialize */ pool->thread_count = 0; pool->queue_size = queue_size; pool->head = pool->tail = pool->count = 0; pool->shutdown = pool->started = 0; /* Allocate thread and task queue */ /* Memory required to request thread arrays and task queues */ pool->threads = (pthread_t *)malloc(sizeof(pthread_t) * thread_count); pool->queue = (threadpool_task_t *)malloc (sizeof(threadpool_task_t) * queue_size); /* Initialize mutex and conditional variable first */ /* Initialize mutexes and conditional variables */ if((pthread_mutex_init(&(pool->lock), NULL) != 0) || (pthread_cond_init(&(pool->notify), NULL) != 0) || (pool->threads == NULL) || (pool->queue == NULL)) { goto err; } /* Start worker threads */ /* Create a specified number of threads to start running */ for(i = 0; i < thread_count; i++) { if(pthread_create(&(pool->threads[i]), NULL, threadpool_thread, (void*)pool) != 0) { threadpool_destroy(pool, 0); return NULL; } pool->thread_count++; pool->started++; } return pool; err: if(pool) { threadpool_free(pool); } return NULL; } int threadpool_add(threadpool_t *pool, void (*function)(void *), void *argument, int flags) { int err = 0; int next; if(pool == NULL || function == NULL) { return threadpool_invalid; } /* Mutual exclusion lock ownership must be acquired first */ if(pthread_mutex_lock(&(pool->lock)) != 0) { return threadpool_lock_failure; } /* Calculate the next location where task can be stored */ next = pool->tail + 1; next = (next == pool->queue_size) ? 0 : next; do { /* Are we full ? */ /* Check if the task queue is full */ if(pool->count == pool->queue_size) { err = threadpool_queue_full; break; } /* Are we shutting down ? */ /* Check whether the current thread pool state is closed */ if(pool->shutdown) { err = threadpool_shutdown; break; } /* Add task to queue */ /* Place function pointers and parameters in tail to add to the task queue */ pool->queue[pool->tail].function = function; pool->queue[pool->tail].argument = argument; /* Update tail and count */ pool->tail = next; pool->count += 1; /* pthread_cond_broadcast */ /* * Send out signal to indicate that task has been added * If a thread is blocked because the task queue is empty, there will be a wake-up call. * If not, do nothing. */ if(pthread_cond_signal(&(pool->notify)) != 0) { err = threadpool_lock_failure; break; } /* * The do {...} while (0) structure is used here. * Ensure that the process is executed at most once, but in the middle it is easy to jump out of the execution block because of exceptions */ } while(0); /* Release mutex resources */ if(pthread_mutex_unlock(&pool->lock) != 0) { err = threadpool_lock_failure; } return err; } int threadpool_destroy(threadpool_t *pool, int flags) { int i, err = 0; if(pool == NULL) { return threadpool_invalid; } /* Get mutex resources */ if(pthread_mutex_lock(&(pool->lock)) != 0) { return threadpool_lock_failure; } do { /* Already shutting down */ /* Determine whether it has been closed elsewhere */ if(pool->shutdown) { err = threadpool_shutdown; break; } /* Gets the specified closing mode */ pool->shutdown = (flags & threadpool_graceful) ? graceful_shutdown : immediate_shutdown; /* Wake up all worker threads */ /* Wake up all threads blocked by dependent variables and release mutexes */ if((pthread_cond_broadcast(&(pool->notify)) != 0) || (pthread_mutex_unlock(&(pool->lock)) != 0)) { err = threadpool_lock_failure; break; } /* Join all worker thread */ /* Waiting for all threads to end */ for(i = 0; i < pool->thread_count; i++) { if(pthread_join(pool->threads[i], NULL) != 0) { err = threadpool_thread_failure; } } /* Also do{...} while(0) structure*/ } while(0); /* Only if everything went well do we deallocate the pool */ if(!err) { /* Release memory resources */ threadpool_free(pool); } return err; } int threadpool_free(threadpool_t *pool) { if(pool == NULL || pool->started > 0) { return -1; } /* Did we manage to allocate ? */ /* Release memory resources occupied by thread task queue mutex conditional variable thread pool */ if(pool->threads) { free(pool->threads); free(pool->queue); /* Because we allocate pool->threads after initializing the mutex and condition variable, we're sure they're initialized. Let's lock the mutex just in case. */ pthread_mutex_lock(&(pool->lock)); pthread_mutex_destroy(&(pool->lock)); pthread_cond_destroy(&(pool->notify)); } free(pool); return 0; } static void *threadpool_thread(void *threadpool) { threadpool_t *pool = (threadpool_t *)threadpool; threadpool_task_t task; for(;;) { /* Lock must be taken to wait on conditional variable */ /* Get mutex resources */ pthread_mutex_lock(&(pool->lock)); /* Wait on condition variable, check for spurious wakeups. When returning from pthread_cond_wait(), we own the lock. */ /* The purpose of using while is to re-examine the condition during wake-up. */ while((pool->count == 0) && (!pool->shutdown)) { /* The task queue is empty and the thread pool is blocked when it is not closed */ pthread_cond_wait(&(pool->notify), &(pool->lock)); } /* Closing Processing */ if((pool->shutdown == immediate_shutdown) || ((pool->shutdown == graceful_shutdown) && (pool->count == 0))) { break; } /* Grab our task */ /* Get the first task in the task queue */ task.function = pool->queue[pool->head].function; task.argument = pool->queue[pool->head].argument; /* Update head and count */ pool->head += 1; pool->head = (pool->head == pool->queue_size) ? 0 : pool->head; pool->count -= 1; /* Unlock */ /* Release mutex */ pthread_mutex_unlock(&(pool->lock)); /* Get to work */ /* Start running tasks */ (*(task.function))(task.argument); /* Here is the end of a task run */ } /* Threads will end, update the number of running threads */ pool->started--; pthread_mutex_unlock(&(pool->lock)); pthread_exit(NULL); return(NULL); }