3 * $Id: pool.h,v 1.2 2004/04/08 01:36:13 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,
37 /*----- Header files ------------------------------------------------------*/
49 /*----- Data structures ---------------------------------------------------*/
51 #define POOL_CHUNKSZ 65536
53 typedef struct pool_chunk {
54 struct pool_chunk *next; /* Next memory chunk in the chain */
55 char *p; /* Free area in this chunk */
56 size_t left; /* Amount of memory left */
59 typedef struct pool_resource {
60 struct pool_resource *next; /* Next resource in the chain */
61 void (*destroy)(struct pool_resource */*r*/); /* Destruction function */
65 arena a; /* The arena for allocating memory */
66 pool_chunk *c; /* Pointer to memory chunk list */
67 pool_resource *r; /* Pointer to resource list */
68 arena *pa; /* Arena for real allocation */
71 typedef struct pool_file {
72 pool_resource r; /* A pool resource record */
73 FILE *fp; /* The actual file handle */
76 /*----- Basic pool management ---------------------------------------------*/
78 /* --- @pool_alloc@ --- *
80 * Arguments: @pool *p@ = pool to allocate from
81 * @size_t sz@ = size of block wanted
83 * Returns: Pointer to the requested block.
85 * Use: Allocates memory from a resource pool. Memory is never freed
86 * from pools: it is released when the pool is destroyed.
89 extern void *pool_alloc(pool */*p*/, size_t /*sz*/);
91 /* --- @pool_strdup@ --- *
93 * Arguments: @pool *p@ = pool to allocate from
94 * @const char *s@ = pointer to string
96 * Returns: A pointer to a copy of the string.
98 * Use: Allocates a copy of a string.
101 extern char *pool_strdup(pool */*p*/, const char */*s*/);
103 /* --- @pool_create@ --- *
105 * Arguments: @arena *a@ = pointer to an arena to allocate memory from
107 * Returns: A newly created resource pool.
109 * Use: Creates a resource pool which is not a child of any other
113 extern pool *pool_create(arena */*a*/);
115 /* --- @pool_destroy@ --- *
117 * Arguments: @pool *p@ = pointer to pool to destroy
121 * Use: Destroys a pool, freeing all of the resources within it. If
122 * this is a root pool, its memory will be deallocated; if it's
123 * a subpool, it is emptied and can be used again.
126 extern void pool_destroy(pool */*p*/);
128 /* --- @pool_sub@ --- *
130 * Arguments: @pool *p@ = pointer to parent pool
132 * Returns: A new child pool of the parent.
134 * Use: Creates a subpool. The subpool can either be destroyed on
135 * its own, or will be automatically destroyed at the same time
139 extern pool *pool_sub(pool */*p*/);
141 /* --- @pool_add@ --- *
143 * Arguments: @pool *p@ = pointer to pool to add the resource to
144 * @pool_resource *r@ = pointer to resource block
145 * @void (*dfn)(pool_resource *r)@ = destruction function
149 * Use: Adds a resource to a pool.
152 #define POOL_ADD(p, rr, dfn) do { \
154 pool_resource *_r = (rr); \
160 extern void pool_add(pool */*p*/, pool_resource */*r*/,
161 void (*/*dfn*/)(pool_resource */*r*/));
163 /*----- Various simple resource types -------------------------------------*/
165 /* --- @pool_fopen@ --- *
167 * Arguments: @pool *p@ = pointer to a pool
168 * @const char *file@ = name of the file to open
169 * @const char *how@ = string specifying opening parameters
171 * Returns: A pointer to a pool resource containing an open file handle,
172 * or null if the file open filed.
174 * Use: Opens a file so that it will be freed again when a pool is
178 extern pool_file *pool_fopen(pool */*p*/,
179 const char */*file*/, const char */*how*/);
181 /* --- @pool_fclose@ --- *
183 * Arguments: @pool_file *pf@ = pointer to a file resource
185 * Returns: The response from the @fclose@ function.
187 * Use: Closes a file. It is not an error to close a file multiple
191 extern int pool_fclose(pool_file */*pf*/);
193 /* --- @pool_subarena@ --- *
195 * Arguments: @pool *p@ = pointer to the pool
197 * Returns: A subarena built from the pool's memory allocator.
199 * Use: Creates a suballocation arena attached to a pool. The arena
200 * and all of its memory will be freed when the pool is
204 extern subarena *pool_subarena(pool */*p*/);
206 /*----- That's all, folks -------------------------------------------------*/