1219820Sjeff/* 2219820Sjeff * Copyright (c) 2004-2007 Voltaire, Inc. All rights reserved. 3219820Sjeff * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved. 4219820Sjeff * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. 5219820Sjeff * 6219820Sjeff * This software is available to you under a choice of one of two 7219820Sjeff * licenses. You may choose to be licensed under the terms of the GNU 8219820Sjeff * General Public License (GPL) Version 2, available from the file 9219820Sjeff * COPYING in the main directory of this source tree, or the 10219820Sjeff * OpenIB.org BSD license below: 11219820Sjeff * 12219820Sjeff * Redistribution and use in source and binary forms, with or 13219820Sjeff * without modification, are permitted provided that the following 14219820Sjeff * conditions are met: 15219820Sjeff * 16219820Sjeff * - Redistributions of source code must retain the above 17219820Sjeff * copyright notice, this list of conditions and the following 18219820Sjeff * disclaimer. 19219820Sjeff * 20219820Sjeff * - Redistributions in binary form must reproduce the above 21219820Sjeff * copyright notice, this list of conditions and the following 22219820Sjeff * disclaimer in the documentation and/or other materials 23219820Sjeff * provided with the distribution. 24219820Sjeff * 25219820Sjeff * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 26219820Sjeff * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 27219820Sjeff * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 28219820Sjeff * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 29219820Sjeff * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 30219820Sjeff * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 31219820Sjeff * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 32219820Sjeff * SOFTWARE. 33219820Sjeff * 34219820Sjeff */ 35219820Sjeff 36219820Sjeff/* 37219820Sjeff * Abstract: 38219820Sjeff * Declaration of thread pool. 39219820Sjeff */ 40219820Sjeff 41219820Sjeff#ifndef _CL_THREAD_POOL_H_ 42219820Sjeff#define _CL_THREAD_POOL_H_ 43219820Sjeff 44219820Sjeff#include <pthread.h> 45219820Sjeff#include <complib/cl_types.h> 46219820Sjeff#include <complib/cl_thread.h> 47219820Sjeff 48219820Sjeff#ifdef __cplusplus 49219820Sjeff# define BEGIN_C_DECLS extern "C" { 50219820Sjeff# define END_C_DECLS } 51219820Sjeff#else /* !__cplusplus */ 52219820Sjeff# define BEGIN_C_DECLS 53219820Sjeff# define END_C_DECLS 54219820Sjeff#endif /* __cplusplus */ 55219820Sjeff 56219820SjeffBEGIN_C_DECLS 57219820Sjeff/****h* Component Library/Thread Pool 58219820Sjeff* NAME 59219820Sjeff* Thread Pool 60219820Sjeff* 61219820Sjeff* DESCRIPTION 62219820Sjeff* The Thread Pool manages a user specified number of threads. 63219820Sjeff* 64219820Sjeff* Each thread in the thread pool waits for a user initiated signal before 65219820Sjeff* invoking a user specified callback function. All threads in the thread 66219820Sjeff* pool invoke the same callback function. 67219820Sjeff* 68219820Sjeff* The thread pool functions operate on a cl_thread_pool_t structure which 69219820Sjeff* should be treated as opaque, and should be manipulated only through the 70219820Sjeff* provided functions. 71219820Sjeff* 72219820Sjeff* SEE ALSO 73219820Sjeff* Structures: 74219820Sjeff* cl_thread_pool_t 75219820Sjeff* 76219820Sjeff* Initialization: 77219820Sjeff* cl_thread_pool_construct, cl_thread_pool_init, cl_thread_pool_destroy 78219820Sjeff* 79219820Sjeff* Manipulation 80219820Sjeff* cl_thread_pool_signal 81219820Sjeff*********/ 82219820Sjeff/****s* Component Library: Thread Pool/cl_thread_pool_t 83219820Sjeff* NAME 84219820Sjeff* cl_thread_pool_t 85219820Sjeff* 86219820Sjeff* DESCRIPTION 87219820Sjeff* Thread pool structure. 88219820Sjeff* 89219820Sjeff* The cl_thread_pool_t structure should be treated as opaque, and should be 90219820Sjeff* manipulated only through the provided functions. 91219820Sjeff* 92219820Sjeff* SYNOPSIS 93219820Sjeff*/ 94219820Sjefftypedef struct _cl_thread_pool { 95219820Sjeff void (*pfn_callback) (void *); 96219820Sjeff void *context; 97219820Sjeff unsigned running_count; 98219820Sjeff unsigned events; 99219820Sjeff pthread_cond_t cond; 100219820Sjeff pthread_mutex_t mutex; 101219820Sjeff pthread_t *tid; 102219820Sjeff} cl_thread_pool_t; 103219820Sjeff/* 104219820Sjeff* FIELDS 105219820Sjeff* pfn_callback 106219820Sjeff* Callback function for the thread to invoke. 107219820Sjeff* 108219820Sjeff* context 109219820Sjeff* Context to pass to the thread callback function. 110219820Sjeff* 111219820Sjeff* running_count 112219820Sjeff* Number of threads running. 113219820Sjeff* 114219820Sjeff* events 115219820Sjeff* events counter 116219820Sjeff* 117219820Sjeff* mutex 118219820Sjeff* mutex for cond variable protection 119219820Sjeff* 120219820Sjeff* cond 121219820Sjeff* conditional variable to signal an event to thread 122219820Sjeff* 123219820Sjeff* tid 124219820Sjeff* array of allocated thread ids. 125219820Sjeff* 126219820Sjeff* SEE ALSO 127219820Sjeff* Thread Pool 128219820Sjeff*********/ 129219820Sjeff 130219820Sjeff/****f* Component Library: Thread Pool/cl_thread_pool_init 131219820Sjeff* NAME 132219820Sjeff* cl_thread_pool_init 133219820Sjeff* 134219820Sjeff* DESCRIPTION 135219820Sjeff* The cl_thread_pool_init function creates the threads to be 136219820Sjeff* managed by a thread pool. 137219820Sjeff* 138219820Sjeff* SYNOPSIS 139219820Sjeff*/ 140219820Sjeffcl_status_t 141219820Sjeffcl_thread_pool_init(IN cl_thread_pool_t * const p_thread_pool, 142219820Sjeff IN unsigned count, 143219820Sjeff IN void (*pfn_callback) (void *), 144219820Sjeff IN void *context, IN const char *const name); 145219820Sjeff/* 146219820Sjeff* PARAMETERS 147219820Sjeff* p_thread_pool 148219820Sjeff* [in] Pointer to a thread pool structure to initialize. 149219820Sjeff* 150219820Sjeff* thread_count 151219820Sjeff* [in] Number of threads to be managed by the thread pool. 152219820Sjeff* 153219820Sjeff* pfn_callback 154219820Sjeff* [in] Address of a function to be invoked by a thread. 155219820Sjeff* See the cl_pfn_thread_callback_t function type definition for 156219820Sjeff* details about the callback function. 157219820Sjeff* 158219820Sjeff* context 159219820Sjeff* [in] Value to pass to the callback function. 160219820Sjeff* 161219820Sjeff* name 162219820Sjeff* [in] Name to associate with the threads. The name may be up to 16 163219820Sjeff* characters, including a terminating null character. All threads 164219820Sjeff* created in the pool have the same name. 165219820Sjeff* 166219820Sjeff* RETURN VALUES 167219820Sjeff* CL_SUCCESS if the thread pool creation succeeded. 168219820Sjeff* 169219820Sjeff* CL_INSUFFICIENT_MEMORY if there was not enough memory to inititalize 170219820Sjeff* the thread pool. 171219820Sjeff* 172219820Sjeff* CL_ERROR if the threads could not be created. 173219820Sjeff* 174219820Sjeff* NOTES 175219820Sjeff* cl_thread_pool_init creates and starts the specified number of threads. 176219820Sjeff* If thread_count is zero, the thread pool creates as many threads as there 177219820Sjeff* are processors in the system. 178219820Sjeff* 179219820Sjeff* SEE ALSO 180219820Sjeff* Thread Pool, cl_thread_pool_construct, cl_thread_pool_destroy, 181219820Sjeff* cl_thread_pool_signal, cl_pfn_thread_callback_t 182219820Sjeff*********/ 183219820Sjeff 184219820Sjeff/****f* Component Library: Thread Pool/cl_thread_pool_destroy 185219820Sjeff* NAME 186219820Sjeff* cl_thread_pool_destroy 187219820Sjeff* 188219820Sjeff* DESCRIPTION 189219820Sjeff* The cl_thread_pool_destroy function performs any necessary cleanup 190219820Sjeff* for a thread pool. 191219820Sjeff* 192219820Sjeff* SYNOPSIS 193219820Sjeff*/ 194219820Sjeffvoid cl_thread_pool_destroy(IN cl_thread_pool_t * const p_thread_pool); 195219820Sjeff/* 196219820Sjeff* PARAMETERS 197219820Sjeff* p_thread_pool 198219820Sjeff* [in] Pointer to a thread pool structure to destroy. 199219820Sjeff* 200219820Sjeff* RETURN VALUE 201219820Sjeff* This function does not return a value. 202219820Sjeff* 203219820Sjeff* NOTES 204219820Sjeff* This function blocks until all threads exit, and must therefore not 205219820Sjeff* be called from any of the thread pool's threads. Because of its blocking 206219820Sjeff* nature, callers of cl_thread_pool_destroy must ensure that entering a wait 207219820Sjeff* state is valid from the calling thread context. 208219820Sjeff* 209219820Sjeff* This function should only be called after a call to 210219820Sjeff* cl_thread_pool_construct or cl_thread_pool_init. 211219820Sjeff* 212219820Sjeff* SEE ALSO 213219820Sjeff* Thread Pool, cl_thread_pool_construct, cl_thread_pool_init 214219820Sjeff*********/ 215219820Sjeff 216219820Sjeff/****f* Component Library: Thread Pool/cl_thread_pool_signal 217219820Sjeff* NAME 218219820Sjeff* cl_thread_pool_signal 219219820Sjeff* 220219820Sjeff* DESCRIPTION 221219820Sjeff* The cl_thread_pool_signal function signals a single thread of 222219820Sjeff* the thread pool to invoke the thread pool's callback function. 223219820Sjeff* 224219820Sjeff* SYNOPSIS 225219820Sjeff*/ 226219820Sjeffcl_status_t cl_thread_pool_signal(IN cl_thread_pool_t * const p_thread_pool); 227219820Sjeff/* 228219820Sjeff* PARAMETERS 229219820Sjeff* p_thread_pool 230219820Sjeff* [in] Pointer to a thread pool structure to signal. 231219820Sjeff* 232219820Sjeff* RETURN VALUES 233219820Sjeff* CL_SUCCESS if the thread pool was successfully signalled. 234219820Sjeff* 235219820Sjeff* CL_ERROR otherwise. 236219820Sjeff* 237219820Sjeff* NOTES 238219820Sjeff* Each call to this function wakes up at most one waiting thread in 239219820Sjeff* the thread pool. 240219820Sjeff* 241219820Sjeff* If all threads are running, cl_thread_pool_signal has no effect. 242219820Sjeff* 243219820Sjeff* SEE ALSO 244219820Sjeff* Thread Pool 245219820Sjeff*********/ 246219820Sjeff 247219820SjeffEND_C_DECLS 248219820Sjeff#endif /* _CL_THREAD_POOL_H_ */ 249