chiark - git - mdw - mLib/blob - 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