1321936Shselasky/* 2321936Shselasky * Copyright (c) 2004-2007 Voltaire, Inc. All rights reserved. 3321936Shselasky * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved. 4321936Shselasky * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. 5321936Shselasky * 6321936Shselasky * This software is available to you under a choice of one of two 7321936Shselasky * licenses. You may choose to be licensed under the terms of the GNU 8321936Shselasky * General Public License (GPL) Version 2, available from the file 9321936Shselasky * COPYING in the main directory of this source tree, or the 10321936Shselasky * OpenIB.org BSD license below: 11321936Shselasky * 12321936Shselasky * Redistribution and use in source and binary forms, with or 13321936Shselasky * without modification, are permitted provided that the following 14321936Shselasky * conditions are met: 15321936Shselasky * 16321936Shselasky * - Redistributions of source code must retain the above 17321936Shselasky * copyright notice, this list of conditions and the following 18321936Shselasky * disclaimer. 19321936Shselasky * 20321936Shselasky * - Redistributions in binary form must reproduce the above 21321936Shselasky * copyright notice, this list of conditions and the following 22321936Shselasky * disclaimer in the documentation and/or other materials 23321936Shselasky * provided with the distribution. 24321936Shselasky * 25321936Shselasky * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 26321936Shselasky * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 27321936Shselasky * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 28321936Shselasky * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 29321936Shselasky * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 30321936Shselasky * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 31321936Shselasky * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32321936Shselasky * SOFTWARE. 33321936Shselasky * 34321936Shselasky */ 35321936Shselasky 36321936Shselasky/* 37321936Shselasky * Abstract: 38321936Shselasky * Declaration of thread pool. 39321936Shselasky */ 40321936Shselasky 41321936Shselasky#ifndef _CL_THREAD_POOL_H_ 42321936Shselasky#define _CL_THREAD_POOL_H_ 43321936Shselasky 44321936Shselasky#include <pthread.h> 45321936Shselasky#include <complib/cl_types.h> 46321936Shselasky#include <complib/cl_thread.h> 47321936Shselasky 48321936Shselasky#ifdef __cplusplus 49321936Shselasky# define BEGIN_C_DECLS extern "C" { 50321936Shselasky# define END_C_DECLS } 51321936Shselasky#else /* !__cplusplus */ 52321936Shselasky# define BEGIN_C_DECLS 53321936Shselasky# define END_C_DECLS 54321936Shselasky#endif /* __cplusplus */ 55321936Shselasky 56321936ShselaskyBEGIN_C_DECLS 57321936Shselasky/****h* Component Library/Thread Pool 58321936Shselasky* NAME 59321936Shselasky* Thread Pool 60321936Shselasky* 61321936Shselasky* DESCRIPTION 62321936Shselasky* The Thread Pool manages a user specified number of threads. 63321936Shselasky* 64321936Shselasky* Each thread in the thread pool waits for a user initiated signal before 65321936Shselasky* invoking a user specified callback function. All threads in the thread 66321936Shselasky* pool invoke the same callback function. 67321936Shselasky* 68321936Shselasky* The thread pool functions operate on a cl_thread_pool_t structure which 69321936Shselasky* should be treated as opaque, and should be manipulated only through the 70321936Shselasky* provided functions. 71321936Shselasky* 72321936Shselasky* SEE ALSO 73321936Shselasky* Structures: 74321936Shselasky* cl_thread_pool_t 75321936Shselasky* 76321936Shselasky* Initialization: 77321936Shselasky* cl_thread_pool_init, cl_thread_pool_destroy 78321936Shselasky* 79321936Shselasky* Manipulation 80321936Shselasky* cl_thread_pool_signal 81321936Shselasky*********/ 82321936Shselasky/****s* Component Library: Thread Pool/cl_thread_pool_t 83321936Shselasky* NAME 84321936Shselasky* cl_thread_pool_t 85321936Shselasky* 86321936Shselasky* DESCRIPTION 87321936Shselasky* Thread pool structure. 88321936Shselasky* 89321936Shselasky* The cl_thread_pool_t structure should be treated as opaque, and should be 90321936Shselasky* manipulated only through the provided functions. 91321936Shselasky* 92321936Shselasky* SYNOPSIS 93321936Shselasky*/ 94321936Shselaskytypedef struct _cl_thread_pool { 95321936Shselasky void (*pfn_callback) (void *); 96321936Shselasky void *context; 97321936Shselasky unsigned running_count; 98321936Shselasky unsigned events; 99321936Shselasky pthread_cond_t cond; 100321936Shselasky pthread_mutex_t mutex; 101321936Shselasky pthread_t *tid; 102321936Shselasky} cl_thread_pool_t; 103321936Shselasky/* 104321936Shselasky* FIELDS 105321936Shselasky* pfn_callback 106321936Shselasky* Callback function for the thread to invoke. 107321936Shselasky* 108321936Shselasky* context 109321936Shselasky* Context to pass to the thread callback function. 110321936Shselasky* 111321936Shselasky* running_count 112321936Shselasky* Number of threads running. 113321936Shselasky* 114321936Shselasky* events 115321936Shselasky* events counter 116321936Shselasky* 117321936Shselasky* mutex 118321936Shselasky* mutex for cond variable protection 119321936Shselasky* 120321936Shselasky* cond 121321936Shselasky* conditional variable to signal an event to thread 122321936Shselasky* 123321936Shselasky* tid 124321936Shselasky* array of allocated thread ids. 125321936Shselasky* 126321936Shselasky* SEE ALSO 127321936Shselasky* Thread Pool 128321936Shselasky*********/ 129321936Shselasky 130321936Shselasky/****f* Component Library: Thread Pool/cl_thread_pool_init 131321936Shselasky* NAME 132321936Shselasky* cl_thread_pool_init 133321936Shselasky* 134321936Shselasky* DESCRIPTION 135321936Shselasky* The cl_thread_pool_init function creates the threads to be 136321936Shselasky* managed by a thread pool. 137321936Shselasky* 138321936Shselasky* SYNOPSIS 139321936Shselasky*/ 140321936Shselaskycl_status_t 141321936Shselaskycl_thread_pool_init(IN cl_thread_pool_t * const p_thread_pool, 142321936Shselasky IN unsigned count, 143321936Shselasky IN void (*pfn_callback) (void *), 144321936Shselasky IN void *context, IN const char *const name); 145321936Shselasky/* 146321936Shselasky* PARAMETERS 147321936Shselasky* p_thread_pool 148321936Shselasky* [in] Pointer to a thread pool structure to initialize. 149321936Shselasky* 150321936Shselasky* thread_count 151321936Shselasky* [in] Number of threads to be managed by the thread pool. 152321936Shselasky* 153321936Shselasky* pfn_callback 154321936Shselasky* [in] Address of a function to be invoked by a thread. 155321936Shselasky* See the cl_pfn_thread_callback_t function type definition for 156321936Shselasky* details about the callback function. 157321936Shselasky* 158321936Shselasky* context 159321936Shselasky* [in] Value to pass to the callback function. 160321936Shselasky* 161321936Shselasky* name 162321936Shselasky* [in] Name to associate with the threads. The name may be up to 16 163321936Shselasky* characters, including a terminating null character. All threads 164321936Shselasky* created in the pool have the same name. 165321936Shselasky* 166321936Shselasky* RETURN VALUES 167321936Shselasky* CL_SUCCESS if the thread pool creation succeeded. 168321936Shselasky* 169321936Shselasky* CL_INSUFFICIENT_MEMORY if there was not enough memory to inititalize 170321936Shselasky* the thread pool. 171321936Shselasky* 172321936Shselasky* CL_ERROR if the threads could not be created. 173321936Shselasky* 174321936Shselasky* NOTES 175321936Shselasky* cl_thread_pool_init creates and starts the specified number of threads. 176321936Shselasky* If thread_count is zero, the thread pool creates as many threads as there 177321936Shselasky* are processors in the system. 178321936Shselasky* 179321936Shselasky* SEE ALSO 180321936Shselasky* Thread Pool, cl_thread_pool_destroy, 181321936Shselasky* cl_thread_pool_signal, cl_pfn_thread_callback_t 182321936Shselasky*********/ 183321936Shselasky 184321936Shselasky/****f* Component Library: Thread Pool/cl_thread_pool_destroy 185321936Shselasky* NAME 186321936Shselasky* cl_thread_pool_destroy 187321936Shselasky* 188321936Shselasky* DESCRIPTION 189321936Shselasky* The cl_thread_pool_destroy function performs any necessary cleanup 190321936Shselasky* for a thread pool. 191321936Shselasky* 192321936Shselasky* SYNOPSIS 193321936Shselasky*/ 194321936Shselaskyvoid cl_thread_pool_destroy(IN cl_thread_pool_t * const p_thread_pool); 195321936Shselasky/* 196321936Shselasky* PARAMETERS 197321936Shselasky* p_thread_pool 198321936Shselasky* [in] Pointer to a thread pool structure to destroy. 199321936Shselasky* 200321936Shselasky* RETURN VALUE 201321936Shselasky* This function does not return a value. 202321936Shselasky* 203321936Shselasky* NOTES 204321936Shselasky* This function blocks until all threads exit, and must therefore not 205321936Shselasky* be called from any of the thread pool's threads. Because of its blocking 206321936Shselasky* nature, callers of cl_thread_pool_destroy must ensure that entering a wait 207321936Shselasky* state is valid from the calling thread context. 208321936Shselasky* 209321936Shselasky* This function should only be called after a call to 210321936Shselasky* cl_thread_pool_init. 211321936Shselasky* 212321936Shselasky* SEE ALSO 213321936Shselasky* Thread Pool, cl_thread_pool_init 214321936Shselasky*********/ 215321936Shselasky 216321936Shselasky/****f* Component Library: Thread Pool/cl_thread_pool_signal 217321936Shselasky* NAME 218321936Shselasky* cl_thread_pool_signal 219321936Shselasky* 220321936Shselasky* DESCRIPTION 221321936Shselasky* The cl_thread_pool_signal function signals a single thread of 222321936Shselasky* the thread pool to invoke the thread pool's callback function. 223321936Shselasky* 224321936Shselasky* SYNOPSIS 225321936Shselasky*/ 226321936Shselaskycl_status_t cl_thread_pool_signal(IN cl_thread_pool_t * const p_thread_pool); 227321936Shselasky/* 228321936Shselasky* PARAMETERS 229321936Shselasky* p_thread_pool 230321936Shselasky* [in] Pointer to a thread pool structure to signal. 231321936Shselasky* 232321936Shselasky* RETURN VALUES 233321936Shselasky* CL_SUCCESS if the thread pool was successfully signalled. 234321936Shselasky* 235321936Shselasky* CL_ERROR otherwise. 236321936Shselasky* 237321936Shselasky* NOTES 238321936Shselasky* Each call to this function wakes up at most one waiting thread in 239321936Shselasky* the thread pool. 240321936Shselasky* 241321936Shselasky* If all threads are running, cl_thread_pool_signal has no effect. 242321936Shselasky* 243321936Shselasky* SEE ALSO 244321936Shselasky* Thread Pool 245321936Shselasky*********/ 246321936Shselasky 247321936ShselaskyEND_C_DECLS 248321936Shselasky#endif /* _CL_THREAD_POOL_H_ */ 249