1/*
2 * Copyright (C) 2013  Internet Systems Consortium, Inc. ("ISC")
3 *
4 * Permission to use, copy, modify, and/or distribute this software for any
5 * purpose with or without fee is hereby granted, provided that the above
6 * copyright notice and this permission notice appear in all copies.
7 *
8 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
9 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
10 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
11 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
12 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
13 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
14 * PERFORMANCE OF THIS SOFTWARE.
15 */
16
17#ifndef ISC_OBJPOOL_H
18#define ISC_OBJPOOL_H 1
19
20/*****
21 ***** Module Info
22 *****/
23
24/*! \file isc/pool.h
25 * \brief An object pool is a mechanism for sharing a small pool of
26 * fungible objects among a large number of objects that depend on them.
27 *
28 * This is useful, for example, when it causes performance problems for
29 * large number of zones to share a single memory context or task object,
30 * but it would create a different set of problems for them each to have an
31 * independent task or memory context.
32 */
33
34
35/***
36 *** Imports.
37 ***/
38
39#include <isc/lang.h>
40#include <isc/mem.h>
41#include <isc/types.h>
42
43ISC_LANG_BEGINDECLS
44
45/*****
46 ***** Types.
47 *****/
48
49typedef void
50(*isc_pooldeallocator_t)(void **object);
51
52typedef isc_result_t
53(*isc_poolinitializer_t)(void **target, void *arg);
54
55typedef struct isc_pool isc_pool_t;
56
57/*****
58 ***** Functions.
59 *****/
60
61isc_result_t
62isc_pool_create(isc_mem_t *mctx, unsigned int count,
63		isc_pooldeallocator_t free,
64		isc_poolinitializer_t init, void *initarg,
65		isc_pool_t **poolp);
66/*%<
67 * Create a pool of "count" object pointers. If 'free' is not NULL,
68 * it points to a function that will detach the objects.  'init'
69 * points to a function that will initialize the arguments, and
70 * 'arg' to an argument to be passed into that function (for example,
71 * a relevant manager or context object).
72 *
73 * Requires:
74 *
75 *\li	'mctx' is a valid memory context.
76 *
77 *\li	init != NULL
78 *
79 *\li	poolp != NULL && *poolp == NULL
80 *
81 * Ensures:
82 *
83 *\li	On success, '*poolp' points to the new object pool.
84 *
85 * Returns:
86 *
87 *\li	#ISC_R_SUCCESS
88 *\li	#ISC_R_NOMEMORY
89 *\li	#ISC_R_UNEXPECTED
90 */
91
92void *
93isc_pool_get(isc_pool_t *pool);
94/*%<
95 * Returns a pointer to an object from the pool. Currently the object
96 * is chosen from the pool at random.  (This may be changed in the future
97 * to something that guaratees balance.)
98 */
99
100int
101isc_pool_count(isc_pool_t *pool);
102/*%<
103 * Returns the number of objcts in the pool 'pool'.
104 */
105
106isc_result_t
107isc_pool_expand(isc_pool_t **sourcep, unsigned int count, isc_pool_t **targetp);
108
109/*%<
110 * If 'size' is larger than the number of objects in the pool pointed to by
111 * 'sourcep', then a new pool of size 'count' is allocated, the existing
112 * objects are copied into it, additional ones created to bring the
113 * total number up to 'count', and the resulting pool is attached to
114 * 'targetp'.
115 *
116 * If 'count' is less than or equal to the number of objects in 'source', then
117 * 'sourcep' is attached to 'targetp' without any other action being taken.
118 *
119 * In either case, 'sourcep' is detached.
120 *
121 * Requires:
122 *
123 * \li	'sourcep' is not NULL and '*source' is not NULL
124 * \li	'targetp' is not NULL and '*source' is NULL
125 *
126 * Ensures:
127 *
128 * \li	On success, '*targetp' points to a valid task pool.
129 * \li	On success, '*sourcep' points to NULL.
130 *
131 * Returns:
132 *
133 * \li	#ISC_R_SUCCESS
134 * \li	#ISC_R_NOMEMORY
135 */
136
137void
138isc_pool_destroy(isc_pool_t **poolp);
139/*%<
140 * Destroy a task pool.  The tasks in the pool are detached but not
141 * shut down.
142 *
143 * Requires:
144 * \li	'*poolp' is a valid task pool.
145 */
146
147ISC_LANG_ENDDECLS
148
149#endif /* ISC_OBJPOOL_H */
150