3 * $Id: pool.h,v 1.1 2000/07/16 12:28:48 mdw Exp $
5 * Resource pool handling
7 * (c) 2000 Straylight/Edgeware
10 /*----- Licensing notice --------------------------------------------------*
12 * This file is part of the mLib utilities library.
14 * mLib is free software; you can redistribute it and/or modify
15 * it under the terms of the GNU Library General Public License as
16 * published by the Free Software Foundation; either version 2 of the
17 * License, or (at your option) any later version.
19 * mLib is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 * GNU Library General Public License for more details.
24 * You should have received a copy of the GNU Library General Public
25 * License along with mLib; if not, write to the Free
26 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
30 /*----- Revision history --------------------------------------------------*
33 * Revision 1.1 2000/07/16 12:28:48 mdw
34 * Support for resource pools, based on the Apache model.
45 /*----- Header files ------------------------------------------------------*/
57 /*----- Data structures ---------------------------------------------------*/
59 #define POOL_CHUNKSZ 65536
61 typedef struct pool_chunk
{
62 struct pool_chunk
*next
; /* Next memory chunk in the chain */
63 char *p
; /* Free area in this chunk */
64 size_t left
; /* Amount of memory left */
67 typedef struct pool_resource
{
68 struct pool_resource
*next
; /* Next resource in the chain */
69 void (*destroy
)(struct pool_resource */
*r*/
); /* Destruction function */
73 arena a
; /* The arena for allocating memory */
74 pool_chunk
*c
; /* Pointer to memory chunk list */
75 pool_resource
*r
; /* Pointer to resource list */
76 arena
*pa
; /* Arena for real allocation */
79 typedef struct pool_file
{
80 pool_resource r
; /* A pool resource record */
81 FILE *fp
; /* The actual file handle */
84 /*----- Basic pool management ---------------------------------------------*/
86 /* --- @pool_alloc@ --- *
88 * Arguments: @pool *p@ = pool to allocate from
89 * @size_t sz@ = size of block wanted
91 * Returns: Pointer to the requested block.
93 * Use: Allocates memory from a resource pool. Memory is never freed
94 * from pools: it is released when the pool is destroyed.
97 extern void *pool_alloc(pool */
*p*/
, size_t /*sz*/);
99 /* --- @pool_strdup@ --- *
101 * Arguments: @pool *p@ = pool to allocate from
102 * @const char *s@ = pointer to string
104 * Returns: A pointer to a copy of the string.
106 * Use: Allocates a copy of a string.
109 extern char *pool_strdup(pool */
*p*/
, const char */
*s*/
);
111 /* --- @pool_create@ --- *
113 * Arguments: @arena *a@ = pointer to an arena to allocate memory from
115 * Returns: A newly created resource pool.
117 * Use: Creates a resource pool which is not a child of any other
121 extern pool
*pool_create(arena */
*a*/
);
123 /* --- @pool_destroy@ --- *
125 * Arguments: @pool *p@ = pointer to pool to destroy
129 * Use: Destroys a pool, freeing all of the resources within it. If
130 * this is a root pool, its memory will be deallocated; if it's
131 * a subpool, it is emptied and can be used again.
134 extern void pool_destroy(pool */
*p*/
);
136 /* --- @pool_sub@ --- *
138 * Arguments: @pool *p@ = pointer to parent pool
140 * Returns: A new child pool of the parent.
142 * Use: Creates a subpool. The subpool can either be destroyed on
143 * its own, or will be automatically destroyed at the same time
147 extern pool
*pool_sub(pool */
*p*/
);
149 /* --- @pool_add@ --- *
151 * Arguments: @pool *p@ = pointer to pool to add the resource to
152 * @pool_resource *r@ = pointer to resource block
153 * @void (*dfn)(pool_resource *r)@ = destruction function
157 * Use: Adds a resource to a pool.
160 #define POOL_ADD(p, rr, dfn) do { \
162 pool_resource *_r = (rr); \
168 extern void pool_add(pool */
*p*/
, pool_resource */
*r*/
,
169 void (*/
*dfn*/
)(pool_resource */
*r*/
));
171 /*----- Various simple resource types -------------------------------------*/
173 /* --- @pool_fopen@ --- *
175 * Arguments: @pool *p@ = pointer to a pool
176 * @const char *file@ = name of the file to open
177 * @const char *how@ = string specifying opening parameters
179 * Returns: A pointer to a pool resource containing an open file handle,
180 * or null if the file open filed.
182 * Use: Opens a file so that it will be freed again when a pool is
186 extern pool_file
*pool_fopen(pool */
*p*/
,
187 const char */
*file*/
, const char */
*how*/
);
189 /* --- @pool_fclose@ --- *
191 * Arguments: @pool_file *pf@ = pointer to a file resource
193 * Returns: The response from the @fclose@ function.
195 * Use: Closes a file. It is not an error to close a file multiple
199 extern int pool_fclose(pool_file */
*pf*/
);
201 /* --- @pool_subarena@ --- *
203 * Arguments: @pool *p@ = pointer to the pool
205 * Returns: A subarena built from the pool's memory allocator.
207 * Use: Creates a suballocation arena attached to a pool. The arena
208 * and all of its memory will be freed when the pool is
212 extern subarena
*pool_subarena(pool */
*p*/
);
214 /*----- That's all, folks -------------------------------------------------*/