Resources: Allow res_free(NULL) and res_detach(NULL)

[libucw.git] / ucw / respool.h

diff --git a/ucw/respool.h b/ucw/respool.h
index a12552ab83e1ed3b801ddad8605d9b10bde5c8ea..56955707a2f9fb07d3180a4d0f3f3a5a7818fc0a 100644 (file)
--- a/ucw/respool.h
+++ b/ucw/respool.h
@@ -23,6 +23,7 @@ struct respool {
   const char *name;
   struct mempool *mpool;                               // If set, resources are allocated from the mempool, otherwise by xmalloc()
   struct resource *subpool_of;
+  uns default_res_flags;                               // RES_FLAG_xxx for newly allocated resources
 };
 
 /**
@@ -33,11 +34,17 @@ struct respool {
 struct resource {
   cnode n;
   struct respool *rpool;
+  uns flags;                                           // RES_FLAG_xxx
   const struct res_class *rclass;
   void *priv;                                          // Private to the class
   // More data specific for the particular class can follow
 };
 
+/** Resource flags **/
+enum resource_flags {
+  RES_FLAG_TEMP = 1,                                   // Resource is temporary
+};
+
 /**
  * Creates a new resource pool. If a memory pool is given, meta-data of all resources
  * will be allocated from this pool. Otherwise, they will be malloc'ed.
@@ -46,6 +53,7 @@ struct respool *rp_new(const char *name, struct mempool *mp);
 
 void rp_delete(struct respool *rp);                    /** Deletes a resource pool, freeing all resources. **/
 void rp_detach(struct respool *rp);                    /** Deletes a resource pool, detaching all resources. **/
+void rp_commit(struct respool *rp);                    /** Deletes a resource pool. Temporary resources are freed, stable resources are detached. **/
 void rp_dump(struct respool *rp, uns indent);          /** Prints out a debugging dump of a pool to stdout. **/
 
 /** Returns a pointer to the currently active resource pool or NULL, if none exists. **/
@@ -69,13 +77,36 @@ static inline struct respool *rp_switch(struct respool *rp)
 struct resource *res_alloc(const struct res_class *rc) LIKE_MALLOC;    // Returns NULL if there is no pool active
 
 void res_dump(struct resource *r, uns indent);         /** Prints out a debugging dump of the resource to stdout. **/
-void res_free(struct resource *r);                     /** Frees a resource, unlinking it from its pool. **/
+
+/**
+ * Frees a resource, unlinking it from its pool.
+ * When called with a NULL pointer, it does nothing, but safely.
+ **/
+void res_free(struct resource *r);
+
+/**
+ * Unlinks a resource from a pool and releases its meta-data. However, the resource itself is kept.
+ * When called with a NULL pointer, it does nothing, but safely.
+ **/
+void res_detach(struct resource *r);
+
+/** Marks a resource as temporary (sets @RES_FLAG_TEMP). **/
+static inline void res_temporary(struct resource *r)
+{
+  r->flags |= RES_FLAG_TEMP;
+}
+
+/** Marks a resource as permanent (clears @RES_FLAG_TEMP). **/
+static inline void res_permanent(struct resource *r)
+{
+  r->flags &= RES_FLAG_TEMP;
+}
 
 /***
  * === Resource classes
  *
  * A resource class describes how to handle a particular type of resources.
- * Most importantly, it defines a set of callbacks for performing operations
+ * Most importantly, it defines a set of (optional) callbacks for performing operations
  * on the resources:
  *
  * * dump() should print a description of the resource used for debugging
@@ -99,12 +130,10 @@ struct res_class {
   uns res_size;                                                // Size of the resource structure (0=default)
 };
 
-/** Unlinks a resource from a pool and releases its meta-data. However, the resource itself is kept. **/
-void res_detach(struct resource *r);
-
 /**
  * Unlinks a resource from a pool and releases its meta-data. Unlike @res_detach(),
- * it does not invoke any callbacks.
+ * it does not invoke any callbacks. The caller must make sure that no references to
+ * the meta-data remain, so this is generally safe only inside resource class code.
  **/
 void res_drop(struct resource *r);