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;
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.
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
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.
45 struct respool *rp_new(const char *name, struct mempool *mp);
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. **/
51 /** Returns a pointer to the currently active resource pool or NULL, if none exists. **/
52 static inline struct respool *rp_current(void)
54 return ucwlib_thread_context()->current_respool;
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.
61 static inline struct respool *rp_switch(struct respool *rp)
63 struct ucwlib_context *ctx = ucwlib_thread_context();
64 struct respool *orp = ctx->current_respool;
65 ctx->current_respool = rp;
69 struct resource *res_alloc(const struct res_class *rc) LIKE_MALLOC; // Returns NULL if there is no pool active
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. **/
75 * === Resource classes
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
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
90 * The following functions are intended for use by the resource classes only.
93 /** The structure describing a resource 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)
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);
106 * Unlinks a resource from a pool and releases its meta-data. Unlike @res_detach(),
107 * it does not invoke any callbacks.
109 void res_drop(struct resource *r);
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.
115 static inline struct resource *res_new(const struct res_class *rc, void *priv)
117 struct resource *r = res_alloc(rc);
127 * === Pre-defined resource classes
130 struct resource *res_for_fd(int fd); /** Creates a resource that closes a given file descriptor. **/
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(). **/
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.
141 struct resource *res_subpool(struct respool *rp);