ucw/respool.h

   1 /*
   2  *      The UCW Library -- Resource Pools
   3  *
   4  *      (c) 2008--2011 Martin Mares <mj@ucw.cz>
   5  *
   6  *      This software may be freely distributed and used according to the terms
   7  *      of the GNU Lesser General Public License.
   8  */
   9
  10 #ifndef _UCW_RESPOOL_H
  11 #define _UCW_RESPOOL_H
  12
  13 #include "ucw/clists.h"
  14 #include "ucw/threads.h"
  15
  16 /**
  17  * A resource pool. It contains a name of the pool (which is printed
  18  * in all debugging dumps, otherwise it is not used) and a bunch of
  19  * fields for internal use.
  20  **/
  21 struct respool {
  22   clist resources;
  23   const char *name;
  24   struct mempool *mpool;                                // If set, resources are allocated from the mempool, otherwise by xmalloc()
  25   struct resource *subpool_of;
  26 };
  27
  28 /**
  29  * Each resource is represented by this structure. It is linked to a resource
  30  * pool it belongs to. It contains a pointer to a resource class (which describes how to
  31  * handle the resource) and data private to the resource class.
  32  **/
  33 struct resource {
  34   cnode n;
  35   struct respool *rpool;
  36   const struct res_class *rclass;
  37   void *priv;                                           // Private to the class
  38   // More data specific for the particular class can follow
  39 };
  40
  41 /**
  42  * Creates a new resource pool. If a memory pool is given, meta-data of all resources
  43  * will be allocated from this pool. Otherwise, they will be malloc'ed.
  44  **/
  45 struct respool *rp_new(const char *name, struct mempool *mp);
  46
  47 void rp_delete(struct respool *rp);                     /** Deletes a resource pool, freeing all resources. **/
  48 void rp_detach(struct respool *rp);                     /** Deletes a resource pool, detaching all resources. **/
  49 void rp_dump(struct respool *rp, uns indent);           /** Prints out a debugging dump of a pool to stdout. **/
  50
  51 /** Returns a pointer to the currently active resource pool or NULL, if none exists. **/
  52 static inline struct respool *rp_current(void)
  53 {
  54   return ucwlib_thread_context()->current_respool;
  55 }
  56
  57 /**
  58  * Makes the given resource pool active; returns a pointer to the previously active pool
  59  * or NULL, if there was none. Calling with @rp equal to NULL deactivates the pool.
  60  **/
  61 static inline struct respool *rp_switch(struct respool *rp)
  62 {
  63   struct ucwlib_context *ctx = ucwlib_thread_context();
  64   struct respool *orp = ctx->current_respool;
  65   ctx->current_respool = rp;
  66   return orp;
  67 }
  68
  69 struct resource *res_alloc(const struct res_class *rc) LIKE_MALLOC;     // Returns NULL if there is no pool active
  70
  71 void res_dump(struct resource *r, uns indent);          /** Prints out a debugging dump of the resource to stdout. **/
  72 void res_free(struct resource *r);                      /** Frees a resource, unlinking it from its pool. **/
  73
  74 /***
  75  * === Resource classes
  76  *
  77  * A resource class describes how to handle a particular type of resources.
  78  * Most importantly, it defines a set of callbacks for performing operations
  79  * on the resources:
  80  *
  81  * * dump() should print a description of the resource used for debugging
  82  *   to the standard output. The description should end with a newline character
  83  *   and in case of a multi-line description, the subsequent lines should be
  84  *   indented by @indent spaces.
  85  * * free() frees the resource; the struct resource is freed automatically afterwards.
  86  * * detach() breaks the link between the struct resource and the real resource;
  87  *   the struct resource is freed automatically afterwards, while the resource
  88  *   continues to live.
  89  *
  90  * The following functions are intended for use by the resource classes only.
  91  ***/
  92
  93 /** The structure describing a resource class. **/
  94 struct res_class {
  95   const char *name;                                     // The name of the class (included in debugging dumps)
  96   void (*detach)(struct resource *r);                   // The callbacks
  97   void (*free)(struct resource *r);
  98   void (*dump)(struct resource *r, uns indent);
  99   uns res_size;                                         // Size of the resource structure (0=default)
 100 };
 101
 102 /** Unlinks a resource from a pool and releases its meta-data. However, the resource itself is kept. **/
 103 void res_detach(struct resource *r);
 104
 105 /**
 106  * Unlinks a resource from a pool and releases its meta-data. Unlike @res_detach(),
 107  * it does not invoke any callbacks.
 108  **/
 109 void res_drop(struct resource *r);
 110
 111 /**
 112  * Creates a new resource of the specific class, setting its private data to @priv.
 113  * Returns NULL if there is no resource pool active.
 114  **/
 115 static inline struct resource *res_new(const struct res_class *rc, void *priv)
 116 {
 117   struct resource *r = res_alloc(rc);
 118   if (r)
 119     {
 120       r->rclass = rc;
 121       r->priv = priv;
 122     }
 123   return r;
 124 }
 125
 126 /***
 127  * === Pre-defined resource classes
 128  ***/
 129
 130 struct resource *res_for_fd(int fd);                    /** Creates a resource that closes a given file descriptor. **/
 131
 132 void *res_malloc(size_t size, struct resource **ptr) LIKE_MALLOC;       /** Allocates memory and creates a resource for it. **/
 133 void *res_malloc_zero(size_t size, struct resource **ptr) LIKE_MALLOC;  /** Allocates zero-initialized memory and creates a resource for it. **/
 134 void *res_realloc(struct resource *res, size_t size);                   /** Re-allocates memory obtained by @res_malloc() or @res_malloc_zero(). **/
 135
 136 /**
 137  * Converts the resource pool @rp to a resource inside the current resource pool (i.e., its sub-pool).
 138  * You can delete the sub-pool either by freeing this resource, or by calling
 139  * @rp_delete() on it, which removes the resource automatically.
 140  **/
 141 struct resource *res_subpool(struct respool *rp);
 142
 143 #endif