cl_threadpool.h revision 219820
1/* 2 * Copyright (c) 2004-2007 Voltaire, Inc. All rights reserved. 3 * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved. 4 * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. 5 * 6 * This software is available to you under a choice of one of two 7 * licenses. You may choose to be licensed under the terms of the GNU 8 * General Public License (GPL) Version 2, available from the file 9 * COPYING in the main directory of this source tree, or the 10 * OpenIB.org BSD license below: 11 * 12 * Redistribution and use in source and binary forms, with or 13 * without modification, are permitted provided that the following 14 * conditions are met: 15 * 16 * - Redistributions of source code must retain the above 17 * copyright notice, this list of conditions and the following 18 * disclaimer. 19 * 20 * - Redistributions in binary form must reproduce the above 21 * copyright notice, this list of conditions and the following 22 * disclaimer in the documentation and/or other materials 23 * provided with the distribution. 24 * 25 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 26 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 27 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 28 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 29 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 30 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 31 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32 * SOFTWARE. 33 * 34 */ 35 36/* 37 * Abstract: 38 * Declaration of thread pool. 39 */ 40 41#ifndef _CL_THREAD_POOL_H_ 42#define _CL_THREAD_POOL_H_ 43 44#include <pthread.h> 45#include <complib/cl_types.h> 46#include <complib/cl_thread.h> 47 48#ifdef __cplusplus 49# define BEGIN_C_DECLS extern "C" { 50# define END_C_DECLS } 51#else /* !__cplusplus */ 52# define BEGIN_C_DECLS 53# define END_C_DECLS 54#endif /* __cplusplus */ 55 56BEGIN_C_DECLS 57/****h* Component Library/Thread Pool 58* NAME 59* Thread Pool 60* 61* DESCRIPTION 62* The Thread Pool manages a user specified number of threads. 63* 64* Each thread in the thread pool waits for a user initiated signal before 65* invoking a user specified callback function. All threads in the thread 66* pool invoke the same callback function. 67* 68* The thread pool functions operate on a cl_thread_pool_t structure which 69* should be treated as opaque, and should be manipulated only through the 70* provided functions. 71* 72* SEE ALSO 73* Structures: 74* cl_thread_pool_t 75* 76* Initialization: 77* cl_thread_pool_construct, cl_thread_pool_init, cl_thread_pool_destroy 78* 79* Manipulation 80* cl_thread_pool_signal 81*********/ 82/****s* Component Library: Thread Pool/cl_thread_pool_t 83* NAME 84* cl_thread_pool_t 85* 86* DESCRIPTION 87* Thread pool structure. 88* 89* The cl_thread_pool_t structure should be treated as opaque, and should be 90* manipulated only through the provided functions. 91* 92* SYNOPSIS 93*/ 94typedef struct _cl_thread_pool { 95 void (*pfn_callback) (void *); 96 void *context; 97 unsigned running_count; 98 unsigned events; 99 pthread_cond_t cond; 100 pthread_mutex_t mutex; 101 pthread_t *tid; 102} cl_thread_pool_t; 103/* 104* FIELDS 105* pfn_callback 106* Callback function for the thread to invoke. 107* 108* context 109* Context to pass to the thread callback function. 110* 111* running_count 112* Number of threads running. 113* 114* events 115* events counter 116* 117* mutex 118* mutex for cond variable protection 119* 120* cond 121* conditional variable to signal an event to thread 122* 123* tid 124* array of allocated thread ids. 125* 126* SEE ALSO 127* Thread Pool 128*********/ 129 130/****f* Component Library: Thread Pool/cl_thread_pool_init 131* NAME 132* cl_thread_pool_init 133* 134* DESCRIPTION 135* The cl_thread_pool_init function creates the threads to be 136* managed by a thread pool. 137* 138* SYNOPSIS 139*/ 140cl_status_t 141cl_thread_pool_init(IN cl_thread_pool_t * const p_thread_pool, 142 IN unsigned count, 143 IN void (*pfn_callback) (void *), 144 IN void *context, IN const char *const name); 145/* 146* PARAMETERS 147* p_thread_pool 148* [in] Pointer to a thread pool structure to initialize. 149* 150* thread_count 151* [in] Number of threads to be managed by the thread pool. 152* 153* pfn_callback 154* [in] Address of a function to be invoked by a thread. 155* See the cl_pfn_thread_callback_t function type definition for 156* details about the callback function. 157* 158* context 159* [in] Value to pass to the callback function. 160* 161* name 162* [in] Name to associate with the threads. The name may be up to 16 163* characters, including a terminating null character. All threads 164* created in the pool have the same name. 165* 166* RETURN VALUES 167* CL_SUCCESS if the thread pool creation succeeded. 168* 169* CL_INSUFFICIENT_MEMORY if there was not enough memory to inititalize 170* the thread pool. 171* 172* CL_ERROR if the threads could not be created. 173* 174* NOTES 175* cl_thread_pool_init creates and starts the specified number of threads. 176* If thread_count is zero, the thread pool creates as many threads as there 177* are processors in the system. 178* 179* SEE ALSO 180* Thread Pool, cl_thread_pool_construct, cl_thread_pool_destroy, 181* cl_thread_pool_signal, cl_pfn_thread_callback_t 182*********/ 183 184/****f* Component Library: Thread Pool/cl_thread_pool_destroy 185* NAME 186* cl_thread_pool_destroy 187* 188* DESCRIPTION 189* The cl_thread_pool_destroy function performs any necessary cleanup 190* for a thread pool. 191* 192* SYNOPSIS 193*/ 194void cl_thread_pool_destroy(IN cl_thread_pool_t * const p_thread_pool); 195/* 196* PARAMETERS 197* p_thread_pool 198* [in] Pointer to a thread pool structure to destroy. 199* 200* RETURN VALUE 201* This function does not return a value. 202* 203* NOTES 204* This function blocks until all threads exit, and must therefore not 205* be called from any of the thread pool's threads. Because of its blocking 206* nature, callers of cl_thread_pool_destroy must ensure that entering a wait 207* state is valid from the calling thread context. 208* 209* This function should only be called after a call to 210* cl_thread_pool_construct or cl_thread_pool_init. 211* 212* SEE ALSO 213* Thread Pool, cl_thread_pool_construct, cl_thread_pool_init 214*********/ 215 216/****f* Component Library: Thread Pool/cl_thread_pool_signal 217* NAME 218* cl_thread_pool_signal 219* 220* DESCRIPTION 221* The cl_thread_pool_signal function signals a single thread of 222* the thread pool to invoke the thread pool's callback function. 223* 224* SYNOPSIS 225*/ 226cl_status_t cl_thread_pool_signal(IN cl_thread_pool_t * const p_thread_pool); 227/* 228* PARAMETERS 229* p_thread_pool 230* [in] Pointer to a thread pool structure to signal. 231* 232* RETURN VALUES 233* CL_SUCCESS if the thread pool was successfully signalled. 234* 235* CL_ERROR otherwise. 236* 237* NOTES 238* Each call to this function wakes up at most one waiting thread in 239* the thread pool. 240* 241* If all threads are running, cl_thread_pool_signal has no effect. 242* 243* SEE ALSO 244* Thread Pool 245*********/ 246 247END_C_DECLS 248#endif /* _CL_THREAD_POOL_H_ */ 249