[DAPL2] sync with WinOF 2.1 branch
[mirror/winof/.git] / inc / complib / cl_qlockpool.h
1 /*\r
2  * Copyright (c) 2005 SilverStorm Technologies.  All rights reserved.\r
3  * Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.\r
4  * Copyright (c) 1996-2003 Intel Corporation. All rights reserved. \r
5  *\r
6  * This software is available to you under the OpenIB.org BSD license\r
7  * below:\r
8  *\r
9  *     Redistribution and use in source and binary forms, with or\r
10  *     without modification, are permitted provided that the following\r
11  *     conditions are met:\r
12  *\r
13  *      - Redistributions of source code must retain the above\r
14  *        copyright notice, this list of conditions and the following\r
15  *        disclaimer.\r
16  *\r
17  *      - Redistributions in binary form must reproduce the above\r
18  *        copyright notice, this list of conditions and the following\r
19  *        disclaimer in the documentation and/or other materials\r
20  *        provided with the distribution.\r
21  *\r
22  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,\r
23  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r
24  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\r
25  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\r
26  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\r
27  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
28  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r
29  * SOFTWARE.\r
30  *\r
31  * $Id$\r
32  */\r
33 \r
34 \r
35 /*\r
36  * Abstract:\r
37  *      Declaration of cl_qlock_pool_t.\r
38  *      This object represents a threadsafe quick-pool of objects.\r
39  *\r
40  * Environment:\r
41  *      All\r
42  */\r
43 \r
44 #ifndef _CL_QLOCKPOOL_H_\r
45 #define _CL_QLOCKPOOL_H_\r
46 \r
47 \r
48 #include <complib/cl_qpool.h>\r
49 #include <complib/cl_spinlock.h>\r
50 \r
51 \r
52 /****h* Component Library/Quick Locking Pool\r
53 * NAME\r
54 *       Quick Locking Pool\r
55 *\r
56 * DESCRIPTION\r
57 *       The Quick Locking Pool represents a thread-safe quick pool.\r
58 *\r
59 *       This object should be treated as opaque and should be\r
60 *       manipulated only through the provided functions.\r
61 *\r
62 * SEE ALSO\r
63 *       Structures:\r
64 *               cl_qlock_pool_t\r
65 *\r
66 *       Initialization:\r
67 *               cl_qlock_pool_construct, cl_qlock_pool_init, cl_qlock_pool_destroy\r
68 *\r
69 *       Manipulation\r
70 *               cl_qlock_pool_get, cl_qlock_pool_put\r
71 *********/\r
72 \r
73 \r
74 /****s* Component Library: Quick Locking Pool/cl_qlock_pool_t\r
75 * NAME\r
76 *       cl_qlock_pool_t\r
77 *\r
78 * DESCRIPTION\r
79 *       Quick Locking Pool structure.\r
80 *\r
81 *       This object should be treated as opaque and should\r
82 *       be manipulated only through the provided functions.\r
83 *\r
84 * SYNOPSIS\r
85 */\r
86 typedef struct _cl_qlock_pool\r
87 {\r
88         cl_spinlock_t                           lock;\r
89         cl_qpool_t                                      pool;\r
90 \r
91 } cl_qlock_pool_t;\r
92 /*\r
93 * FIELDS\r
94 *       lock\r
95 *               Spinlock guarding the pool.\r
96 *\r
97 *       pool\r
98 *               quick_pool of user objects.\r
99 *\r
100 * SEE ALSO\r
101 *       Quick Locking Pool\r
102 *********/\r
103 \r
104 \r
105 #ifdef __cplusplus\r
106 extern "C"\r
107 {\r
108 #endif\r
109 \r
110 \r
111 /****f* Component Library: Quick Locking Pool/cl_qlock_pool_construct\r
112 * NAME\r
113 *       cl_qlock_pool_construct\r
114 *\r
115 * DESCRIPTION\r
116 *       This function constructs a Quick Locking Pool.\r
117 *\r
118 * SYNOPSIS\r
119 */\r
120 static inline void\r
121 cl_qlock_pool_construct(\r
122         IN cl_qlock_pool_t* const p_pool )\r
123 {\r
124         cl_qpool_construct( &p_pool->pool );\r
125         cl_spinlock_construct( &p_pool->lock );\r
126 }\r
127 \r
128 /*\r
129 * PARAMETERS\r
130 *       p_pool\r
131 *               [in] Pointer to a Quick Locking Pool to construct.\r
132 *\r
133 * RETURN VALUE\r
134 *       This function does not return a value.\r
135 *\r
136 * NOTES\r
137 *       Allows calling cl_qlock_pool_init, cl_qlock_pool_destroy\r
138 *\r
139 *       Calling cl_qlock_pool_construct is a prerequisite to calling any other\r
140 *       method except cl_qlock_pool_init.\r
141 *\r
142 * SEE ALSO\r
143 *       Quick Locking Pool, cl_qlock_pool_init, cl_qlock_pool_destroy\r
144 *********/\r
145 \r
146 \r
147 /****f* Component Library: Quick Locking Pool/cl_qlock_pool_destroy\r
148 * NAME\r
149 *       cl_qlock_pool_destroy\r
150 *\r
151 * DESCRIPTION\r
152 *       The cl_qlock_pool_destroy function destroys a node, releasing\r
153 *       all resources.\r
154 *\r
155 * SYNOPSIS\r
156 */\r
157 static inline void\r
158 cl_qlock_pool_destroy(\r
159         IN cl_qlock_pool_t* const p_pool )\r
160 {\r
161         /*\r
162                 If the pool has already been put into use, grab the lock\r
163                 to sync with other threads before we blow everything away.\r
164         */\r
165         if( cl_is_qpool_inited( &p_pool->pool ) )\r
166         {\r
167                 cl_spinlock_acquire( &p_pool->lock );\r
168                 cl_qpool_destroy( &p_pool->pool );\r
169                 cl_spinlock_release( &p_pool->lock );\r
170         }\r
171         else\r
172                 cl_qpool_destroy( &p_pool->pool );\r
173 \r
174         cl_spinlock_destroy( &p_pool->lock );\r
175 }\r
176 /*\r
177 * PARAMETERS\r
178 *       p_pool\r
179 *               [in] Pointer to a Quick Locking Pool to destroy.\r
180 *\r
181 * RETURN VALUE\r
182 *       This function does not return a value.\r
183 *\r
184 * NOTES\r
185 *       Performs any necessary cleanup of the specified Quick Locking Pool.\r
186 *       Further operations should not be attempted on the destroyed object.\r
187 *       This function should only be called after a call to\r
188 *       cl_qlock_pool_construct or cl_qlock_pool_init.\r
189 *\r
190 * SEE ALSO\r
191 *       Quick Locking Pool, cl_qlock_pool_construct, cl_qlock_pool_init\r
192 *********/\r
193 \r
194 \r
195 /****f* Component Library: Quick Locking Pool/cl_qlock_pool_init\r
196 * NAME\r
197 *       cl_qlock_pool_init\r
198 *\r
199 * DESCRIPTION\r
200 *       The cl_qlock_pool_init function initializes a Quick Locking Pool for use.\r
201 *\r
202 * SYNOPSIS\r
203 */\r
204 static inline cl_status_t\r
205 cl_qlock_pool_init(\r
206         IN cl_qlock_pool_t*                     const p_pool,\r
207         IN      const size_t                    min_size,\r
208         IN      const size_t                    max_size,\r
209         IN      const size_t                    grow_size,\r
210         IN      const size_t                    object_size,\r
211         IN      cl_pfn_qpool_init_t             pfn_initializer OPTIONAL,\r
212         IN      cl_pfn_qpool_dtor_t             pfn_destructor OPTIONAL,\r
213         IN      const void* const               context )\r
214 {\r
215         cl_status_t status;\r
216 \r
217         cl_qlock_pool_construct( p_pool );\r
218 \r
219         status = cl_spinlock_init( &p_pool->lock );\r
220         if( status )\r
221                 return( status );\r
222 \r
223         status = cl_qpool_init( &p_pool->pool, min_size, max_size, grow_size,\r
224                         object_size, pfn_initializer, pfn_destructor, context );\r
225 \r
226         return( status );\r
227 }\r
228 /*\r
229 * PARAMETERS\r
230 *       p_pool\r
231 *               [in] Pointer to an cl_qlock_pool_t object to initialize.\r
232 *\r
233 *       min_size\r
234 *               [in] Minimum number of objects that the pool should support. All\r
235 *               necessary allocations to allow storing the minimum number of items\r
236 *               are performed at initialization time, and all necessary callbacks\r
237 *               successfully invoked.\r
238 *\r
239 *       max_size\r
240 *               [in] Maximum number of objects to which the pool is allowed to grow.\r
241 *               A value of zero specifies no maximum.\r
242 *\r
243 *       grow_size\r
244 *               [in] Number of objects to allocate when incrementally growing the pool.\r
245 *               A value of zero disables automatic growth.\r
246 *\r
247 *       object_size\r
248 *               [in] Size, in bytes, of each object.\r
249 *\r
250 *       pfn_initializer\r
251 *               [in] Initialization callback to invoke for every new object when\r
252 *               growing the pool. This parameter is optional and may be NULL. If NULL,\r
253 *               the pool assumes the cl_pool_item_t structure describing objects is\r
254 *               located at the head of each object. See the cl_pfn_qpool_init_t\r
255 *               function type declaration for details about the callback function.\r
256 *\r
257 *       pfn_destructor\r
258 *               [in] Destructor callback to invoke for every object before memory for\r
259 *               that object is freed. This parameter is optional and may be NULL.\r
260 *               See the cl_pfn_qpool_dtor_t function type declaration for details\r
261 *               about the callback function.\r
262 *\r
263 *       context\r
264 *               [in] Value to pass to the callback functions to provide context.\r
265 *\r
266 * RETURN VALUES\r
267 *       CL_SUCCESS if the quick pool was initialized successfully.\r
268 *\r
269 *       CL_INSUFFICIENT_MEMORY if there was not enough memory to initialize the\r
270 *       quick pool.\r
271 *\r
272 *       CL_INVALID_SETTING if a the maximum size is non-zero and less than the\r
273 *       minimum size.\r
274 *\r
275 *       Other cl_status_t value returned by optional initialization callback function\r
276 *       specified by the pfn_initializer parameter.\r
277 *\r
278 * NOTES\r
279 *       Allows calling other Quick Locking Pool methods.\r
280 *\r
281 * SEE ALSO\r
282 *       Quick Locking Pool, cl_qlock_pool_construct, cl_qlock_pool_destroy\r
283 *********/\r
284 \r
285 \r
286 /****f* Component Library: Quick Locking Pool/cl_qlock_pool_get\r
287 * NAME\r
288 *       cl_qlock_pool_get\r
289 *\r
290 * DESCRIPTION\r
291 *       Gets an object wrapper and wire MAD from the pool.\r
292 *\r
293 * SYNOPSIS\r
294 */\r
295 static inline cl_pool_item_t*\r
296 cl_qlock_pool_get(\r
297         IN cl_qlock_pool_t* const p_pool )\r
298 {\r
299         cl_pool_item_t* p_item;\r
300         cl_spinlock_acquire( &p_pool->lock );\r
301         p_item = cl_qpool_get( &p_pool->pool );\r
302         cl_spinlock_release( &p_pool->lock );\r
303         return( p_item );\r
304 }\r
305 \r
306 /*\r
307 * PARAMETERS\r
308 *       p_pool\r
309 *               [in] Pointer to an cl_qlock_pool_t object.\r
310 *\r
311 * RETURN VALUES\r
312 *       Returns a pointer to a cl_pool_item_t contained in the user object.\r
313 *\r
314 * NOTES\r
315 *       The object must eventually be returned to the pool with a call to\r
316 *       cl_qlock_pool_put.\r
317 *\r
318 *       The cl_qlock_pool_construct or cl_qlock_pool_init must be called before\r
319 *       using this function.\r
320 *\r
321 * SEE ALSO\r
322 *       Quick Locking Pool, cl_qlock_pool_put\r
323 *********/\r
324 \r
325 \r
326 /****f* Component Library: Quick Locking Pool/cl_qlock_pool_put\r
327 * NAME\r
328 *       cl_qlock_pool_put\r
329 *\r
330 * DESCRIPTION\r
331 *       Returns an object to the pool.\r
332 *\r
333 * SYNOPSIS\r
334 */\r
335 static inline void\r
336 cl_qlock_pool_put(\r
337         IN cl_qlock_pool_t* const p_pool,\r
338         IN cl_pool_item_t* const p_item )\r
339 {\r
340         cl_spinlock_acquire( &p_pool->lock );\r
341         cl_qpool_put( &p_pool->pool, p_item );\r
342         cl_spinlock_release( &p_pool->lock );\r
343 }\r
344 /*\r
345 * PARAMETERS\r
346 *       p_pool\r
347 *               [in] Pointer to an cl_qlock_pool_t object.\r
348 *\r
349 *       p_item\r
350 *               [in] Pointer to the cl_pool_item_t in an object that was previously\r
351 *               retrieved from the pool.\r
352 *\r
353 * RETURN VALUES\r
354 *       This function does not return a value.\r
355 *\r
356 * NOTES\r
357 *       The cl_qlock_pool_construct or cl_qlock_pool_init must be called before\r
358 *       using this function.\r
359 *\r
360 * SEE ALSO\r
361 *       Quick Locking Pool, cl_qlock_pool_get\r
362 *********/\r
363 \r
364 \r
365 #ifdef __cplusplus\r
366 }       /* extern "C" */\r
367 #endif\r
368 \r
369 #endif  /* _CL_QLOCKPOOL_H_ */\r