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