chiark / gitweb /
url: Allow `;' to separate key/value pairs in URL-encoded strings.
[mLib] / pool.h
1 /* -*-c-*-
2  *
3  * $Id: pool.h,v 1.2 2004/04/08 01:36:13 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 #ifndef MLIB_POOL_H
31 #define MLIB_POOL_H
32
33 #ifdef __cplusplus
34   extern "C" {
35 #endif
36
37 /*----- Header files ------------------------------------------------------*/
38
39 #include <stdio.h>
40
41 #ifndef MLIB_ARENA_H
42 #  include "arena.h"
43 #endif
44
45 #ifndef MLIB_SUB_H
46 #  include "sub.h"
47 #endif
48
49 /*----- Data structures ---------------------------------------------------*/
50
51 #define POOL_CHUNKSZ 65536
52
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 */
57 } pool_chunk;
58
59 typedef struct pool_resource {
60   struct pool_resource *next;           /* Next resource in the chain */
61   void (*destroy)(struct pool_resource */*r*/); /* Destruction function */
62 } pool_resource;
63
64 typedef struct pool {
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 */
69 } pool;
70
71 typedef struct pool_file {
72   pool_resource r;                      /* A pool resource record */
73   FILE *fp;                             /* The actual file handle */
74 } pool_file;
75
76 /*----- Basic pool management ---------------------------------------------*/
77
78 /* --- @pool_alloc@ --- *
79  *
80  * Arguments:   @pool *p@ = pool to allocate from
81  *              @size_t sz@ = size of block wanted
82  *
83  * Returns:     Pointer to the requested block.
84  *
85  * Use:         Allocates memory from a resource pool.  Memory is never freed
86  *              from pools: it is released when the pool is destroyed.
87  */
88
89 extern void *pool_alloc(pool */*p*/, size_t /*sz*/);
90
91 /* --- @pool_strdup@ --- *
92  *
93  * Arguments:   @pool *p@ = pool to allocate from
94  *              @const char *s@ = pointer to string
95  *
96  * Returns:     A pointer to a copy of the string.
97  *
98  * Use:         Allocates a copy of a string.
99  */
100
101 extern char *pool_strdup(pool */*p*/, const char */*s*/);
102
103 /* --- @pool_create@ --- *
104  *
105  * Arguments:   @arena *a@ = pointer to an arena to allocate memory from
106  *
107  * Returns:     A newly created resource pool.
108  *
109  * Use:         Creates a resource pool which is not a child of any other
110  *              resource pool.
111  */
112
113 extern pool *pool_create(arena */*a*/);
114
115 /* --- @pool_destroy@ --- *
116  *
117  * Arguments:   @pool *p@ = pointer to pool to destroy
118  *
119  * Returns:     ---
120  *
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.
124  */
125
126 extern void pool_destroy(pool */*p*/);
127
128 /* --- @pool_sub@ --- *
129  *
130  * Arguments:   @pool *p@ = pointer to parent pool
131  *
132  * Returns:     A new child pool of the parent.
133  *
134  * Use:         Creates a subpool.  The subpool can either be destroyed on
135  *              its own, or will be automatically destroyed at the same time
136  *              as the parent.
137  */
138
139 extern pool *pool_sub(pool */*p*/);
140
141 /* --- @pool_add@ --- *
142  *
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
146  *
147  * Returns:     ---
148  *
149  * Use:         Adds a resource to a pool.
150  */
151
152 #define POOL_ADD(p, rr, dfn) do {                                       \
153   pool *_p = (p);                                                       \
154   pool_resource *_r = (rr);                                             \
155   _r->next = _p->r;                                                     \
156   _r->destroy = dfn;                                                    \
157   _p->r = _r;                                                           \
158 } while (0)
159
160 extern void pool_add(pool */*p*/, pool_resource */*r*/,
161                      void (*/*dfn*/)(pool_resource */*r*/));
162
163 /*----- Various simple resource types -------------------------------------*/
164
165 /* --- @pool_fopen@ --- *
166  *
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
170  *
171  * Returns:     A pointer to a pool resource containing an open file handle,
172  *              or null if the file open filed.
173  *
174  * Use:         Opens a file so that it will be freed again when a pool is
175  *              destroyed.
176  */
177
178 extern pool_file *pool_fopen(pool */*p*/,
179                              const char */*file*/, const char */*how*/);
180
181 /* --- @pool_fclose@ --- *
182  *
183  * Arguments:   @pool_file *pf@ = pointer to a file resource
184  *
185  * Returns:     The response from the @fclose@ function.
186  *
187  * Use:         Closes a file.  It is not an error to close a file multiple
188  *              times.
189  */
190
191 extern int pool_fclose(pool_file */*pf*/);
192
193 /* --- @pool_subarena@ --- *
194  *
195  * Arguments:   @pool *p@ = pointer to the pool
196  *
197  * Returns:     A subarena built from the pool's memory allocator.
198  *
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
201  *              destroyed.
202  */
203
204 extern subarena *pool_subarena(pool */*p*/);
205
206 /*----- That's all, folks -------------------------------------------------*/
207
208 #ifdef __cplusplus
209   }
210 #endif
211
212 #endif