1 /*
2  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
3  *
4  * This Source Code Form is subject to the terms of the Mozilla Public
5  * License, v. 2.0. If a copy of the MPL was not distributed with this
6  * file, you can obtain one at https://mozilla.org/MPL/2.0/.
7  *
8  * See the COPYRIGHT file distributed with this work for additional
9  * information regarding copyright ownership.
10  */
11 
12 #ifndef ISC_OBJPOOL_H
13 #define ISC_OBJPOOL_H 1
14 
15 /*****
16 ***** Module Info
17 *****/
18 
19 /*! \file isc/pool.h
20  * \brief An object pool is a mechanism for sharing a small pool of
21  * fungible objects among a large number of objects that depend on them.
22  *
23  * This is useful, for example, when it causes performance problems for
24  * large number of zones to share a single memory context or task object,
25  * but it would create a different set of problems for them each to have an
26  * independent task or memory context.
27  */
28 
29 /***
30  *** Imports.
31  ***/
32 
33 #include <isc/lang.h>
34 #include <isc/mem.h>
35 #include <isc/types.h>
36 
37 ISC_LANG_BEGINDECLS
38 
39 /*****
40 ***** Types.
41 *****/
42 
43 typedef void (*isc_pooldeallocator_t)(void **object);
44 
45 typedef isc_result_t (*isc_poolinitializer_t)(void **target, void *arg);
46 
47 typedef struct isc_pool isc_pool_t;
48 
49 /*****
50 ***** Functions.
51 *****/
52 
53 isc_result_t
54 isc_pool_create(isc_mem_t *mctx, unsigned int count, isc_pooldeallocator_t free,
55 		isc_poolinitializer_t init, void *initarg, isc_pool_t **poolp);
56 /*%<
57  * Create a pool of "count" object pointers. If 'free' is not NULL,
58  * it points to a function that will detach the objects.  'init'
59  * points to a function that will initialize the arguments, and
60  * 'arg' to an argument to be passed into that function (for example,
61  * a relevant manager or context object).
62  *
63  * Requires:
64  *
65  *\li	'mctx' is a valid memory context.
66  *
67  *\li	init != NULL
68  *
69  *\li	poolp != NULL && *poolp == NULL
70  *
71  * Ensures:
72  *
73  *\li	On success, '*poolp' points to the new object pool.
74  *
75  * Returns:
76  *
77  *\li	#ISC_R_SUCCESS
78  *\li	#ISC_R_NOMEMORY
79  *\li	#ISC_R_UNEXPECTED
80  */
81 
82 void *
83 isc_pool_get(isc_pool_t *pool);
84 /*%<
85  * Returns a pointer to an object from the pool. Currently the object
86  * is chosen from the pool at random.  (This may be changed in the future
87  * to something that guaratees balance.)
88  */
89 
90 int
91 isc_pool_count(isc_pool_t *pool);
92 /*%<
93  * Returns the number of objcts in the pool 'pool'.
94  */
95 
96 isc_result_t
97 isc_pool_expand(isc_pool_t **sourcep, unsigned int count, isc_pool_t **targetp);
98 
99 /*%<
100  * If 'size' is larger than the number of objects in the pool pointed to by
101  * 'sourcep', then a new pool of size 'count' is allocated, the existing
102  * objects are copied into it, additional ones created to bring the
103  * total number up to 'count', and the resulting pool is attached to
104  * 'targetp'.
105  *
106  * If 'count' is less than or equal to the number of objects in 'source', then
107  * 'sourcep' is attached to 'targetp' without any other action being taken.
108  *
109  * In either case, 'sourcep' is detached.
110  *
111  * Requires:
112  *
113  * \li	'sourcep' is not NULL and '*source' is not NULL
114  * \li	'targetp' is not NULL and '*source' is NULL
115  *
116  * Ensures:
117  *
118  * \li	On success, '*targetp' points to a valid task pool.
119  * \li	On success, '*sourcep' points to NULL.
120  *
121  * Returns:
122  *
123  * \li	#ISC_R_SUCCESS
124  * \li	#ISC_R_NOMEMORY
125  */
126 
127 void
128 isc_pool_destroy(isc_pool_t **poolp);
129 /*%<
130  * Destroy a task pool.  The tasks in the pool are detached but not
131  * shut down.
132  *
133  * Requires:
134  * \li	'*poolp' is a valid task pool.
135  */
136 
137 ISC_LANG_ENDDECLS
138 
139 #endif /* ISC_OBJPOOL_H */
140