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.
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:
12 * Redistribution and use in source and binary forms, with or
13 * without modification, are permitted provided that the following
16 * - Redistributions of source code must retain the above
17 * copyright notice, this list of conditions and the following
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.
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
38 * Declaration of thread pool.
41 #ifndef _CL_THREAD_POOL_H_
42 #define _CL_THREAD_POOL_H_
45 #include <complib/cl_types.h>
46 #include <complib/cl_thread.h>
49 # define BEGIN_C_DECLS extern "C" {
50 # define END_C_DECLS }
51 #else /* !__cplusplus */
52 # define BEGIN_C_DECLS
54 #endif /* __cplusplus */
57 /****h* Component Library/Thread Pool
62 * The Thread Pool manages a user specified number of threads.
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.
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
77 * cl_thread_pool_construct, cl_thread_pool_init, cl_thread_pool_destroy
80 * cl_thread_pool_signal
82 /****s* Component Library: Thread Pool/cl_thread_pool_t
87 * Thread pool structure.
89 * The cl_thread_pool_t structure should be treated as opaque, and should be
90 * manipulated only through the provided functions.
94 typedef struct _cl_thread_pool {
95 void (*pfn_callback) (void *);
97 unsigned running_count;
100 pthread_mutex_t mutex;
106 * Callback function for the thread to invoke.
109 * Context to pass to the thread callback function.
112 * Number of threads running.
118 * mutex for cond variable protection
121 * conditional variable to signal an event to thread
124 * array of allocated thread ids.
130 /****f* Component Library: Thread Pool/cl_thread_pool_init
132 * cl_thread_pool_init
135 * The cl_thread_pool_init function creates the threads to be
136 * managed by a thread pool.
141 cl_thread_pool_init(IN cl_thread_pool_t * const p_thread_pool,
143 IN void (*pfn_callback) (void *),
144 IN void *context, IN const char *const name);
148 * [in] Pointer to a thread pool structure to initialize.
151 * [in] Number of threads to be managed by the thread pool.
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.
159 * [in] Value to pass to the callback function.
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.
167 * CL_SUCCESS if the thread pool creation succeeded.
169 * CL_INSUFFICIENT_MEMORY if there was not enough memory to inititalize
172 * CL_ERROR if the threads could not be created.
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.
180 * Thread Pool, cl_thread_pool_construct, cl_thread_pool_destroy,
181 * cl_thread_pool_signal, cl_pfn_thread_callback_t
184 /****f* Component Library: Thread Pool/cl_thread_pool_destroy
186 * cl_thread_pool_destroy
189 * The cl_thread_pool_destroy function performs any necessary cleanup
194 void cl_thread_pool_destroy(IN cl_thread_pool_t * const p_thread_pool);
198 * [in] Pointer to a thread pool structure to destroy.
201 * This function does not return a value.
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.
209 * This function should only be called after a call to
210 * cl_thread_pool_construct or cl_thread_pool_init.
213 * Thread Pool, cl_thread_pool_construct, cl_thread_pool_init
216 /****f* Component Library: Thread Pool/cl_thread_pool_signal
218 * cl_thread_pool_signal
221 * The cl_thread_pool_signal function signals a single thread of
222 * the thread pool to invoke the thread pool's callback function.
226 cl_status_t cl_thread_pool_signal(IN cl_thread_pool_t * const p_thread_pool);
230 * [in] Pointer to a thread pool structure to signal.
233 * CL_SUCCESS if the thread pool was successfully signalled.
235 * CL_ERROR otherwise.
238 * Each call to this function wakes up at most one waiting thread in
241 * If all threads are running, cl_thread_pool_signal has no effect.
248 #endif /* _CL_THREAD_POOL_H_ */