ucw/resource.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   uns default_res_flags;                                // RES_FLAG_xxx for newly allocated resources
  27 };
  28
  29 /**
  30  * Each resource is represented by this structure. It is linked to a resource
  31  * pool it belongs to. It contains a pointer to a resource class (which describes how to
  32  * handle the resource) and data private to the resource class.
  33  **/
  34 struct resource {
  35   cnode n;
  36   struct respool *rpool;
  37   uns flags;                                            // RES_FLAG_xxx
  38   const struct res_class *rclass;
  39   void *priv;                                           // Private to the class
  40   // More data specific for the particular class can follow
  41 };
  42
  43 /** Resource flags **/
  44 enum resource_flags {
  45   RES_FLAG_TEMP = 1,                                    // Resource is temporary
  46 };
  47
  48 /**
  49  * Creates a new resource pool. If a memory pool is given, meta-data of all resources
  50  * will be allocated from this pool. Otherwise, they will be malloc'ed.
  51  **/
  52 struct respool *rp_new(const char *name, struct mempool *mp);
  53
  54 void rp_delete(struct respool *rp);                     /** Deletes a resource pool, freeing all resources. **/
  55 void rp_detach(struct respool *rp);                     /** Deletes a resource pool, detaching all resources. **/
  56 void rp_commit(struct respool *rp);                     /** Deletes a resource pool. Temporary resources are freed, stable resources are detached. **/
  57 void rp_dump(struct respool *rp, uns indent);           /** Prints out a debugging dump of a pool to stdout. **/
  58
  59 /** Returns a pointer to the currently active resource pool or NULL, if none exists. **/
  60 static inline struct respool *rp_current(void)
  61 {
  62   return ucwlib_thread_context()->current_respool;
  63 }
  64
  65 /**
  66  * Makes the given resource pool active; returns a pointer to the previously active pool
  67  * or NULL, if there was none. Calling with @rp equal to NULL deactivates the pool.
  68  **/
  69 static inline struct respool *rp_switch(struct respool *rp)
  70 {
  71   struct ucwlib_context *ctx = ucwlib_thread_context();
  72   struct respool *orp = ctx->current_respool;
  73   ctx->current_respool = rp;
  74   return orp;
  75 }
  76
  77 struct resource *res_alloc(const struct res_class *rc) LIKE_MALLOC;     // Returns NULL if there is no pool active
  78
  79 void res_dump(struct resource *r, uns indent);          /** Prints out a debugging dump of the resource to stdout. **/
  80
  81 /**
  82  * Frees a resource, unlinking it from its pool.
  83  * When called with a NULL pointer, it does nothing, but safely.
  84  **/
  85 void res_free(struct resource *r);
  86
  87 /**
  88  * Unlinks a resource from a pool and releases its meta-data. However, the resource itself is kept.
  89  * When called with a NULL pointer, it does nothing, but safely.
  90  **/
  91 void res_detach(struct resource *r);
  92
  93 /** Marks a resource as temporary (sets @RES_FLAG_TEMP). **/
  94 static inline void res_temporary(struct resource *r)
  95 {
  96   r->flags |= RES_FLAG_TEMP;
  97 }
  98
  99 /** Marks a resource as permanent (clears @RES_FLAG_TEMP). **/
 100 static inline void res_permanent(struct resource *r)
 101 {
 102   r->flags &= RES_FLAG_TEMP;
 103 }
 104
 105 /***
 106  * === Resource classes
 107  *
 108  * A resource class describes how to handle a particular type of resources.
 109  * Most importantly, it defines a set of (optional) callbacks for performing operations
 110  * on the resources:
 111  *
 112  * * dump() should print a description of the resource used for debugging
 113  *   to the standard output. The description should end with a newline character
 114  *   and in case of a multi-line description, the subsequent lines should be
 115  *   indented by @indent spaces.
 116  * * free() frees the resource; the struct resource is freed automatically afterwards.
 117  * * detach() breaks the link between the struct resource and the real resource;
 118  *   the struct resource is freed automatically afterwards, while the resource
 119  *   continues to live.
 120  *
 121  * The following functions are intended for use by the resource classes only.
 122  ***/
 123
 124 /** The structure describing a resource class. **/
 125 struct res_class {
 126   const char *name;                                     // The name of the class (included in debugging dumps)
 127   void (*detach)(struct resource *r);                   // The callbacks
 128   void (*free)(struct resource *r);
 129   void (*dump)(struct resource *r, uns indent);
 130   uns res_size;                                         // Size of the resource structure (0=default)
 131 };
 132
 133 /**
 134  * Unlinks a resource from a pool and releases its meta-data. Unlike @res_detach(),
 135  * it does not invoke any callbacks. The caller must make sure that no references to
 136  * the meta-data remain, so this is generally safe only inside resource class code.
 137  **/
 138 void res_drop(struct resource *r);
 139
 140 /**
 141  * Creates a new resource of the specific class, setting its private data to @priv.
 142  * Dies if no resource pool is active.
 143  **/
 144 static inline struct resource *res_new(const struct res_class *rc, void *priv)
 145 {
 146   struct resource *r = res_alloc(rc);
 147   r->rclass = rc;
 148   r->priv = priv;
 149   return r;
 150 }
 151
 152 /***
 153  * === Pre-defined resource classes
 154  ***/
 155
 156 struct resource *res_for_fd(int fd);                    /** Creates a resource that closes a given file descriptor. **/
 157
 158 void *res_malloc(size_t size, struct resource **ptr) LIKE_MALLOC;       /** Allocates memory and creates a resource for it. **/
 159 void *res_malloc_zero(size_t size, struct resource **ptr) LIKE_MALLOC;  /** Allocates zero-initialized memory and creates a resource for it. **/
 160 void *res_realloc(struct resource *res, size_t size);                   /** Re-allocates memory obtained by @res_malloc() or @res_malloc_zero(). **/
 161
 162 /**
 163  * Converts the resource pool @rp to a resource inside the current resource pool (i.e., its sub-pool).
 164  * You can delete the sub-pool either by freeing this resource, or by calling
 165  * @rp_delete() on it, which removes the resource automatically.
 166  **/
 167 struct resource *res_subpool(struct respool *rp);
 168
 169 struct mempool;
 170 struct resource *res_mempool(struct mempool *mp);                       /** Creates a resource for the specified <<mempool:,memory pool>>. **/
 171
 172 struct eltpool;
 173 struct resource *res_eltpool(struct eltpool *ep);                       /** Creates a resource for the specified <<eltpool:,element pool>>. **/
 174
 175 #endif