chiark / gitweb /
Expunge revision histories in files.
[mLib] / pool.h
CommitLineData
d94be366 1/* -*-c-*-
2 *
8656dc50 3 * $Id: pool.h,v 1.2 2004/04/08 01:36:13 mdw Exp $
d94be366 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
d94be366 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
53typedef 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
59typedef 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
64typedef 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
71typedef 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
89extern 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
101extern 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
113extern 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
126extern 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
139extern 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
160extern 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
178extern 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
191extern 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
204extern subarena *pool_subarena(pool */*p*/);
205
206/*----- That's all, folks -------------------------------------------------*/
207
208#ifdef __cplusplus
209 }
210#endif
211
212#endif