contrib/ofed/management/opensm/include/complib/cl_threadpool.h

   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_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 */
  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_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 */
 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_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 */
 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_ */