ucw/trans.h

   1 /*
   2  *      The UCW Library -- Transactions
   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_TRANS_H
  11 #define _UCW_TRANS_H
  12
  13 #include <ucw/mempool.h>
  14
  15 #include <setjmp.h>
  16
  17 /** A structure describing a transaction. All fields are for internal use only. **/
  18 struct trans {
  19   struct trans *prev_trans;
  20   struct mempool_state *trans_pool_state;
  21   struct respool *rpool;
  22   struct respool *prev_rpool;
  23   struct exception *thrown_exc;
  24   jmp_buf jmp;
  25 };
  26
  27 void trans_init(void);          /** Initializes the transaction system for the current thread. Called automatically as needed. **/
  28 void trans_cleanup(void);       /** Frees memory occupied by the transaction system pools for the current thread. **/
  29
  30 struct trans *trans_open(void); /** Creates a new transaction. Used inside `TRANS_TRY`. **/
  31 struct trans *trans_get_current(void);  /** Get a pointer to the currently running transaction, or NULL if there is none. **/
  32 void trans_commit(void);        /** Commits the current transaction. **/
  33 void trans_rollback(void);      /** Rolls back the current transaction. **/
  34 void trans_fold(void);          /** Folds the current transaction to its parent. **/
  35 void trans_dump(void);          /** Prints out a debugging dump of the transaction stack to stdout. **/
  36
  37 struct mempool *trans_get_pool(void);
  38
  39 /**
  40  * Data associated with an exception. Usually, this structure is created
  41  * by calling @trans_throw(), but if you want to pass more data, you can
  42  * create your own exception and throw it using @trans_throw_exc().
  43  **/
  44 struct exception {
  45   const char *id;               // Hierarchical identifier of the exception
  46   const char *msg;              // Error message to present to the user
  47   void *object;                 // Object on which the exception happened
  48   // More data specific for the particular `id' can follow
  49 };
  50
  51 /** Creates an exception and throws it. The error message can contain `printf`-like formatting. **/
  52 void trans_throw(const char *id, void *object, const char *fmt, ...) FORMAT_CHECK(printf,3,4) NONRET;
  53
  54 /** A `va_list` variant of @trans_throw(). **/
  55 void trans_vthrow(const char *id, void *object, const char *fmt, va_list args) NONRET;
  56
  57 /** Throw an already constructed exception (or re-throw an exception you have caught). **/
  58 void trans_throw_exc(struct exception *x) NONRET;
  59
  60 /** Declare the current exception caught and roll back the current transaction. Called from `TRANS_END`. **/
  61 void trans_caught(void);
  62
  63 struct exception *trans_current_exc(void);      /** Return the exception in flight, or NULL if there is none. **/
  64
  65 #define TRANS_TRY do {                          \
  66   struct trans *_t = trans_open();              \
  67   if (!setjmp(_t->jmp))                         \
  68     {
  69
  70 #define TRANS_CATCH(x)                          \
  71       trans_commit();                           \
  72     }                                           \
  73   else                                          \
  74     {                                           \
  75       struct exception *x UNUSED = trans_current_exc();
  76
  77 #define TRANS_END                               \
  78       trans_caught();                           \
  79     }                                           \
  80   } while(0)
  81
  82 #endif