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 56 BEGIN_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_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 */ 94 typedef 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 */ 140 cl_status_t 141 cl_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_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 */ 194 void 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_init. 211 * 212 * SEE ALSO 213 * Thread Pool, 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 */ 226 cl_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 247 END_C_DECLS 248 #endif /* _CL_THREAD_POOL_H_ */ 249