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