refcount.h

   1 /*
   2         Refcount
   3         --------
   4
   5         An object that knows how and when to delete itself, using a reference counter.
   6
   7         Whenever a reference to an object like this is obtained/kept, it needs to be grabbed,
   8                 whenever a reference is discarded, it needs to be dropped.
   9
  10         Made for use with the List/Tree/Map types: refcount_inc, refcount_grb, refcount_drp
  11                 can be used as add, get, del callbacks.
  12 */
  13 #ifndef _DRAGONSTD_REFCOUNT_H_ // include guard
  14 #define _DRAGONSTD_REFCOUNT_H_
  15
  16 #include <pthread.h>       // for pthread_mutex_t
  17 #include "bits/callback.h" // for Transformer
  18
  19 typedef struct {
  20         /* private */
  21         void *obj;
  22         Transformer del;
  23         unsigned short cnt;  // counter
  24         pthread_mutex_t mtx; // lock to protect count
  25 } Refcount;
  26
  27 void refcount_ini(Refcount *refcount, void *obj, Transformer del);
  28 /*
  29         Initializes the refcount.
  30
  31         The refcount should be uninitialized or deleted before passed to this function.
  32         This function should be called before any other function is called on the refcount.
  33 */
  34
  35 void refcount_dst(Refcount *refcount);
  36 /*
  37         Destroy the refcount.
  38
  39         This does NOT mean delete the object that the reference counter is referring to-
  40         This means delete the refcount structure itself (and is usually called from the
  41         delete callback of the referenced object).
  42
  43         The refcount is unusable until reinitialized afterwards.
  44 */
  45
  46 void *refcount_inc(void *refcount);
  47 /*
  48         [Thread Safe]
  49         Grab a reference to the refcount.
  50         This actually takes a Refcount * as argument, however void * is used to make it more
  51                 convenient to use the function as callback.
  52
  53         Returns the refcount.
  54 */
  55
  56 void *refcount_grb(void *refcount);
  57 /*
  58         [Thread Safe]
  59         Does the same as refcount_inc, except it returns the referenced object instead of the
  60                 refcount.
  61 */
  62
  63 void *refcount_drp(void *refcount);
  64 /*
  65         [Thread Safe]
  66         Drop a reference to the object.
  67         This actually takes a Refcount * as argument, however void * is used to make it more
  68                 convenient to use the function as callback.
  69
  70         May delete the object using the del function if the counter gets down to zero.
  71         Returns the return value of the del function if it has been called; returns the object
  72                 otherwise.
  73 */
  74
  75 void *refcount_obj(void *refcount);
  76 /*
  77         [Thread Safe]
  78         Return referenced object.
  79         This actually takes a Refcount * as argument, however void * is used to make it more
  80                 convenient to use the function as callback.
  81 */
  82
  83 #endif // _DRAGONSTD_REFCOUNT_H_