chiark / gitweb /
Add global unihash table; use universal hashing instead of CRC.
[mLib] / pool.h
1 /* -*-c-*-
2  *
3  * $Id: pool.h,v 1.1 2000/07/16 12:28:48 mdw Exp $
4  *
5  * Resource pool handling
6  *
7  * (c) 2000 Straylight/Edgeware
8  */
9
10 /*----- Licensing notice --------------------------------------------------* 
11  *
12  * This file is part of the mLib utilities library.
13  *
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.
18  * 
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.
23  * 
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,
27  * MA 02111-1307, USA.
28  */
29
30 /*----- Revision history --------------------------------------------------* 
31  *
32  * $Log: pool.h,v $
33  * Revision 1.1  2000/07/16 12:28:48  mdw
34  * Support for resource pools, based on the Apache model.
35  *
36  */
37
38 #ifndef MLIB_POOL_H
39 #define MLIB_POOL_H
40
41 #ifdef __cplusplus
42   extern "C" {
43 #endif
44
45 /*----- Header files ------------------------------------------------------*/
46
47 #include <stdio.h>
48
49 #ifndef MLIB_ARENA_H
50 #  include "arena.h"
51 #endif
52
53 #ifndef MLIB_SUB_H
54 #  include "sub.h"
55 #endif
56
57 /*----- Data structures ---------------------------------------------------*/
58
59 #define POOL_CHUNKSZ 65536
60
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 */
65 } pool_chunk;
66
67 typedef struct pool_resource {
68   struct pool_resource *next;           /* Next resource in the chain */
69   void (*destroy)(struct pool_resource */*r*/); /* Destruction function */
70 } pool_resource;
71
72 typedef struct pool {
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 */
77 } pool;
78
79 typedef struct pool_file {
80   pool_resource r;                      /* A pool resource record */
81   FILE *fp;                             /* The actual file handle */
82 } pool_file;
83
84 /*----- Basic pool management ---------------------------------------------*/
85
86 /* --- @pool_alloc@ --- *
87  *
88  * Arguments:   @pool *p@ = pool to allocate from
89  *              @size_t sz@ = size of block wanted
90  *
91  * Returns:     Pointer to the requested block.
92  *
93  * Use:         Allocates memory from a resource pool.  Memory is never freed
94  *              from pools: it is released when the pool is destroyed.
95  */
96
97 extern void *pool_alloc(pool */*p*/, size_t /*sz*/);
98
99 /* --- @pool_strdup@ --- *
100  *
101  * Arguments:   @pool *p@ = pool to allocate from
102  *              @const char *s@ = pointer to string
103  *
104  * Returns:     A pointer to a copy of the string.
105  *
106  * Use:         Allocates a copy of a string.
107  */
108
109 extern char *pool_strdup(pool */*p*/, const char */*s*/);
110
111 /* --- @pool_create@ --- *
112  *
113  * Arguments:   @arena *a@ = pointer to an arena to allocate memory from
114  *
115  * Returns:     A newly created resource pool.
116  *
117  * Use:         Creates a resource pool which is not a child of any other
118  *              resource pool.
119  */
120
121 extern pool *pool_create(arena */*a*/);
122
123 /* --- @pool_destroy@ --- *
124  *
125  * Arguments:   @pool *p@ = pointer to pool to destroy
126  *
127  * Returns:     ---
128  *
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.
132  */
133
134 extern void pool_destroy(pool */*p*/);
135
136 /* --- @pool_sub@ --- *
137  *
138  * Arguments:   @pool *p@ = pointer to parent pool
139  *
140  * Returns:     A new child pool of the parent.
141  *
142  * Use:         Creates a subpool.  The subpool can either be destroyed on
143  *              its own, or will be automatically destroyed at the same time
144  *              as the parent.
145  */
146
147 extern pool *pool_sub(pool */*p*/);
148
149 /* --- @pool_add@ --- *
150  *
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
154  *
155  * Returns:     ---
156  *
157  * Use:         Adds a resource to a pool.
158  */
159
160 #define POOL_ADD(p, rr, dfn) do {                                       \
161   pool *_p = (p);                                                       \
162   pool_resource *_r = (rr);                                             \
163   _r->next = _p->r;                                                     \
164   _r->destroy = dfn;                                                    \
165   _p->r = _r;                                                           \
166 } while (0)
167
168 extern void pool_add(pool */*p*/, pool_resource */*r*/,
169                      void (*/*dfn*/)(pool_resource */*r*/));
170
171 /*----- Various simple resource types -------------------------------------*/
172
173 /* --- @pool_fopen@ --- *
174  *
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
178  *
179  * Returns:     A pointer to a pool resource containing an open file handle,
180  *              or null if the file open filed.
181  *
182  * Use:         Opens a file so that it will be freed again when a pool is
183  *              destroyed.
184  */
185
186 extern pool_file *pool_fopen(pool */*p*/,
187                              const char */*file*/, const char */*how*/);
188
189 /* --- @pool_fclose@ --- *
190  *
191  * Arguments:   @pool_file *pf@ = pointer to a file resource
192  *
193  * Returns:     The response from the @fclose@ function.
194  *
195  * Use:         Closes a file.  It is not an error to close a file multiple
196  *              times.
197  */
198
199 extern int pool_fclose(pool_file */*pf*/);
200
201 /* --- @pool_subarena@ --- *
202  *
203  * Arguments:   @pool *p@ = pointer to the pool
204  *
205  * Returns:     A subarena built from the pool's memory allocator.
206  *
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
209  *              destroyed.
210  */
211
212 extern subarena *pool_subarena(pool */*p*/);
213
214 /*----- That's all, folks -------------------------------------------------*/
215
216 #ifdef __cplusplus
217   }
218 #endif
219
220 #endif