2 * The UCW Library -- Resource Pools
4 * (c) 2008--2011 Martin Mares <mj@ucw.cz>
6 * This software may be freely distributed and used according to the terms
7 * of the GNU Lesser General Public License.
10 #ifndef _UCW_RESPOOL_H
11 #define _UCW_RESPOOL_H
13 #include "ucw/clists.h"
14 #include "ucw/threads.h"
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.
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
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.
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
43 /** Resource flags **/
45 RES_FLAG_TEMP = 1, // Resource is temporary
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.
52 struct respool *rp_new(const char *name, struct mempool *mp);
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. **/
59 /** Returns a pointer to the currently active resource pool or NULL, if none exists. **/
60 static inline struct respool *rp_current(void)
62 return ucwlib_thread_context()->current_respool;
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.
69 static inline struct respool *rp_switch(struct respool *rp)
71 struct ucwlib_context *ctx = ucwlib_thread_context();
72 struct respool *orp = ctx->current_respool;
73 ctx->current_respool = rp;
77 struct resource *res_alloc(const struct res_class *rc) LIKE_MALLOC; // Returns NULL if there is no pool active
79 void res_dump(struct resource *r, uns indent); /** Prints out a debugging dump of the resource to stdout. **/
80 void res_free(struct resource *r); /** Frees a resource, unlinking it from its pool. **/
82 /** Marks a resource as temporary (sets @RES_FLAG_TEMP). **/
83 static inline void res_temporary(struct resource *r)
85 r->flags |= RES_FLAG_TEMP;
88 /** Marks a resource as permanent (clears @RES_FLAG_TEMP). **/
89 static inline void res_permanent(struct resource *r)
91 r->flags &= RES_FLAG_TEMP;
95 * === Resource classes
97 * A resource class describes how to handle a particular type of resources.
98 * Most importantly, it defines a set of callbacks for performing operations
101 * * dump() should print a description of the resource used for debugging
102 * to the standard output. The description should end with a newline character
103 * and in case of a multi-line description, the subsequent lines should be
104 * indented by @indent spaces.
105 * * free() frees the resource; the struct resource is freed automatically afterwards.
106 * * detach() breaks the link between the struct resource and the real resource;
107 * the struct resource is freed automatically afterwards, while the resource
110 * The following functions are intended for use by the resource classes only.
113 /** The structure describing a resource class. **/
115 const char *name; // The name of the class (included in debugging dumps)
116 void (*detach)(struct resource *r); // The callbacks
117 void (*free)(struct resource *r);
118 void (*dump)(struct resource *r, uns indent);
119 uns res_size; // Size of the resource structure (0=default)
122 /** Unlinks a resource from a pool and releases its meta-data. However, the resource itself is kept. **/
123 void res_detach(struct resource *r);
126 * Unlinks a resource from a pool and releases its meta-data. Unlike @res_detach(),
127 * it does not invoke any callbacks.
129 void res_drop(struct resource *r);
132 * Creates a new resource of the specific class, setting its private data to @priv.
133 * Returns NULL if there is no resource pool active.
135 static inline struct resource *res_new(const struct res_class *rc, void *priv)
137 struct resource *r = res_alloc(rc);
147 * === Pre-defined resource classes
150 struct resource *res_for_fd(int fd); /** Creates a resource that closes a given file descriptor. **/
152 void *res_malloc(size_t size, struct resource **ptr) LIKE_MALLOC; /** Allocates memory and creates a resource for it. **/
153 void *res_malloc_zero(size_t size, struct resource **ptr) LIKE_MALLOC; /** Allocates zero-initialized memory and creates a resource for it. **/
154 void *res_realloc(struct resource *res, size_t size); /** Re-allocates memory obtained by @res_malloc() or @res_malloc_zero(). **/
157 * Converts the resource pool @rp to a resource inside the current resource pool (i.e., its sub-pool).
158 * You can delete the sub-pool either by freeing this resource, or by calling
159 * @rp_delete() on it, which removes the resource automatically.
161 struct resource *res_subpool(struct respool *rp);