veil_datatypes.h

Go to the documentation of this file.
00001 /**
00002  * @file   veil_datatypes.h
00003  * \code
00004  *     Author:       Marc Munro
00005  *     Copyright (c) 2005 - 2011 Marc Munro
00006  *     License:      BSD
00007  * 
00008  * \endcode
00009  * @brief  
00010  * Define all Veil public datatypes 
00011  * 
00012  */
00013 
00014 #ifndef VEIL_DATATYPES
00015 /** 
00016  * Prevent this header from being included multiple times.
00017  */
00018 #define VEIL_DATATYPES 1
00019 
00020 #ifndef VEIL_DEBUG
00021 /**
00022  * Enables various debugging constructs, such as canaries, in code and
00023  * data structures.  If such debugging is required, define VEIL_DEBUG in
00024  * the make invocation, eg: "make VEIL_DEBUG=1".
00025  */
00026 // TODO: REMOVE THE FOLLOWING DEFINITION
00027 #define VEIL_DEBUG 1
00028 #endif 
00029 
00030 #if VEIL_DEBUG == 1
00031 /** 
00032  * Value to be set in sacrificial "canary" fields.  If this value is not
00033  * as expected, the canary has been killed by something inappropriately 
00034  * stomping on memory.
00035  */
00036 #define DBG_CANARY 0xca96ca96
00037 
00038 /** 
00039  * Defines a canary element in a data structure.
00040  */
00041 #define DBG_CANARY_ENTRY int32 canary;
00042 
00043 /** 
00044  * Field to record the size of an array so that its canary element can
00045  * be found.
00046  */
00047 #define DBG_ELEMS_ENTRY  int32 dbgelems;
00048 
00049 /** 
00050  * Code to records the size of an array so that its canary element can
00051  * be found.
00052  */
00053 #define DBG_SET_ELEMS(x,y) (x).dbgelems = y
00054 
00055 /** 
00056  * Code to initialise a canary.
00057  */
00058 #define DBG_SET_CANARY(x) (x).canary = DBG_CANARY
00059 
00060 /** 
00061  * Code to test for a canary having been overwritten.
00062  */
00063 #define DBG_TEST_CANARY(x) if ((x).canary != DBG_CANARY) {\
00064         elog(ERROR, "canary fault"); }
00065 
00066 /** 
00067  * Base size for an array containing a canary.  This is zero if
00068  * VEIL_DEBUG is not defined, when this is defined arrays will be one
00069  * element longer to allow a canary to be placed at the end of the array.
00070  */
00071 #define EMPTY 1
00072 
00073 /**
00074  * Set a trailing canary in an array.
00075  */
00076 #define DBG_SET_TRAILER(x, y) (x).y[(x).dbgelems] = DBG_CANARY;
00077 /**
00078  * Set a trailing canary in an array (using a void pointer).
00079  */
00080 #define DBG_SET_TRAILERP(x, y) (x).y[(x).dbgelems] = (void *) DBG_CANARY;
00081 
00082 /**
00083  * Test the trailing canary in an array.
00084  */
00085 #define DBG_TEST_TRAILER(x, y)                          \
00086     if ((int) (x).y[(x).dbgelems] != DBG_CANARY) {      \
00087         elog(ERROR, "trailing canary fault"); }
00088 
00089 /**
00090  * Check whether an array index is in bounds.
00091  */
00092 #define DBG_CHECK_INDEX(x,i) if (i >= (x).dbgelems) {\
00093         elog(ERROR, "Element index out of range %d", i); }
00094 
00095 #else
00096 #define DBG_CANARY_ENTRY 
00097 #define DBG_ELEMS_ENTRY 
00098 #define DBG_SET_ELEMS(x,y)
00099 #define DBG_SET_CANARY(x) 
00100 #define DBG_TEST_CANARY(x)
00101 #define EMPTY 0
00102 #define DBG_SET_TRAILER(x,Y)
00103 #define DBG_TEST_TRAILER(x,Y)
00104 #define DBG_CHECK_INDEX(x,i)
00105 #endif
00106 
00107 #include "utils/hsearch.h"
00108 #include "storage/lwlock.h"
00109 
00110 /** 
00111  * Chunks provide a linked list of dynamically allocated shared memory
00112  * segments, with the most recently allocated chunk at the tail.
00113  * Shmalloc allocates space from this list of chunks, creating new
00114  * chunks as needed up to MAX_ALLOWED_SHMEM.
00115  */
00116 typedef struct MemChunk {
00117     struct MemChunk *next_chunk;  /**< Pointer to next allocated chunk */
00118     size_t  next;                 /**< Offset, within this chunk, of 1st
00119                                    * free byte */
00120     size_t  limit;                /**< Offset, of 1st byte beyond chunk */
00121     void   *memory[0];            /**< The rest of the chunk, from which
00122                                    * memory is allocated */
00123 } MemChunk;
00124 
00125 
00126 
00127 /**
00128  * The key length for veil hash types.
00129  */
00130 #define HASH_KEYLEN           60
00131 
00132 
00133 /**
00134  * Describes the type of an Object record or one of its subtypes.
00135  */
00136 typedef enum { 
00137     OBJ_UNDEFINED = 0,
00138     OBJ_SHMEMCTL,
00139     OBJ_INT4,
00140     OBJ_RANGE,
00141     OBJ_BITMAP,
00142     OBJ_BITMAP_ARRAY,
00143     OBJ_BITMAP_HASH,
00144     OBJ_BITMAP_REF,
00145     OBJ_INT4_ARRAY
00146 } ObjType;
00147 
00148 /** 
00149  * General purpose object-type.  All veil variables are effectively
00150  * sub-types of this.
00151  */
00152 typedef struct Object {
00153     ObjType type;                 /**< Identifies the type of the object. */
00154 } Object;
00155 
00156 /** 
00157  * The ShmemCtl structure is the first object allocated from the first
00158  * chunk of shared memory in context 0.  This object describes and
00159  * manages shared memory allocated by shmalloc()
00160  */
00161 typedef struct ShmemCtl {
00162     ObjType type;                 /**< This must have the value OBJ_SHMEMCTL */
00163     bool      initialised;        /**< Set to true once struct is setup */
00164     LWLockId  veil_lwlock;        /**< dynamically allocated LWLock */
00165     int       current_context;    /**< Index of the current context (0
00166                                    * or 1) */
00167     size_t    total_allocated[2]; /**< Total shared memory allocated in
00168                                    * chunks in each context */ 
00169     bool      switching;          /**< Whether a context-switch is in
00170                                    * progress */
00171     MemChunk *context[2];         /**< The first chunks of each context */
00172     TransactionId xid[2];         /**< The transaction id of the
00173                                    * transaction that initialised each
00174                                    * context: this is used to determine
00175                                    * whether there are transactions
00176                                    * still runnning that may be using an
00177                                    * earlier context. */
00178 } ShmemCtl;
00179 
00180 /**
00181  * Subtype of Object for storing simple int4 values.  These values are
00182  * allowed to be null.
00183  */
00184 typedef struct Int4Var {
00185     ObjType type;       /**< This must have the value OBJ_INT4 */
00186     bool    isnull;     /**< if true, the value is null */
00187     int32   value;      /**< the integer value of the variable */
00188 } Int4Var;
00189 
00190 /**
00191  * Subtype of Object for storing range values.  A range has an upper and
00192  * lower bound, both stored as int4s.  Nulls are not allowed.
00193  */
00194 typedef struct Range {
00195     ObjType type;       /**< This must have the value OBJ_RANGE */
00196     int32   min;        /**< Lower limit for range. */
00197     int32   max;        /**< Upper limit for range. */
00198 } Range;
00199 
00200 
00201 
00202 /**
00203  * Gives the bitmask index for the bitzero value of a Bitmap.  This is
00204  * part of the "normalisation" process for bitmap ranges.  This process
00205  * allows unlike bitmaps to be more easily compared by forcing bitmap
00206  * indexes to be normalised around 32-bit word boundaries.  Eg, 2 bitmaps
00207  * with domains 1 to 50 and 3 to 55, will have identical bit patterns
00208  * for bits 3 to 50.
00209  * 
00210  * @param x The bitzero value of a bitmap
00211  * 
00212  * @return The bitmask index representing x.
00213  */
00214 #define BITZERO(x) (x & 0xffffffe0)
00215 
00216 /**
00217  * Gives the bitmask index for the bitmax value of a bitmap.  See
00218  * BITZERO() for more information.
00219  *
00220  * @param x The bitmax value of a bitmap
00221  *
00222  * @return The bitmask index representing x.
00223  */
00224 #define BITMAX(x) (x | 0x1f)
00225 
00226 /**
00227  * Gives the index of a bit within the array of 32-bit words that
00228  * comprise the bitmap.
00229  *
00230  * @param x The bit in question
00231  *
00232  * @return The array index of the bit.
00233  */
00234 #define BITSET_ELEM(x) (x >> 5)
00235 
00236 /**
00237  * Gives the index into ::bitmasks for the bit specified in x.
00238  *
00239  * @param x The bit in question
00240  *
00241  * @return The bitmask index
00242  */
00243 #define BITSET_BIT(x) (x & 0x1f)
00244 
00245 /**
00246  * Gives the number of array elements in a ::Bitmap that runs from
00247  * element min to element max.
00248  *
00249  * @param min
00250  * @param max
00251  *
00252  * @return The number of elements in the bitmap.
00253  */
00254 #define ARRAYELEMS(min,max) (((max - BITZERO(min)) >> 5) + 1)
00255 
00256 
00257 /**
00258  * Return the smaller of a or b.  Note that expressions a and b may be
00259  * evaluated more than once.
00260  *
00261  * @param a
00262  * @param b
00263  *
00264  * @return The smaller value of a or b.
00265  */
00266 #define MIN(a,b) ((a < b)? a: b)
00267 
00268 
00269 /**
00270  * Subtype of Object for storing bitmaps.  A bitmap is stored as an
00271  * array of int4 values.  See veil_bitmap.c for more information.  Note
00272  * that the size of a Bitmap structure is determined dynamically at run
00273  * time as the size of the array is only known then.
00274  */
00275 typedef struct Bitmap {
00276     ObjType type;       /**< This must have the value OBJ_BITMAP */
00277     DBG_CANARY_ENTRY    /**< Debugging entry */
00278     DBG_ELEMS_ENTRY     /**< Debugging entry */
00279     int32   bitzero;    /**< The index of the lowest bit the bitmap can
00280                          * store */
00281     int32   bitmax;     /**< The index of the highest bit the bitmap can
00282                          * store */
00283     uint32   bitset[EMPTY]; /**< Element zero of the array of int4 values
00284                          * comprising the bitmap. */
00285 } Bitmap;
00286 
00287 /**
00288  * Subtype of Object for storing bitmap refs.  A bitmapref is like a
00289  * bitmap but instead of containing a bitmap it contains a reference to
00290  * one.  This reference may be set during a transaction and then
00291  * referenced only from within the setting transaction.
00292  */
00293 typedef struct BitmapRef {
00294     ObjType        type;    /**< This must have the value OBJ_BITMAP_REF */
00295     TransactionId  xid;     /**< The xid for which this variable is
00296                              * valid */
00297     Bitmap        *bitmap;  /**< Pointer to the referenced bitmap */
00298 } BitmapRef;
00299 
00300 /**
00301  * Subtype of Object for storing bitmap arrays.  A bitmap array is
00302  * simply an array of pointers to dynamically allocated Bitmaps.  Note
00303  * that the size of a Bitmap structure is determined dynamically at run
00304  * time as the size of the array is only known then.
00305  */
00306 typedef struct BitmapArray {    // subtype of Object
00307     ObjType type;       /**< This must have the value OBJ_BITMAP_ARRAY */
00308     DBG_CANARY_ENTRY    /**< Debugging entry */
00309     DBG_ELEMS_ENTRY     /**< Debugging entry */
00310     int32   bitzero;    /**< The index of the lowest bit each bitmap can
00311                          * store */
00312     int32   bitmax;     /**< The index of the highest bit each bitmap can
00313                          * store */
00314     int32   arrayzero;  /**< The index of array element zero: the
00315                          * index of the lowest numbered bitmap in the
00316                          * array */
00317     int32   arraymax;   /**< The index of the lowest numbered bitmap in
00318                          * the array */
00319     Bitmap *bitmap[EMPTY];  /**< Element zero of the array of Bitmap pointers
00320                          * comprising the array. */
00321 } BitmapArray;
00322 
00323 /** 
00324  * Subtype of Object for storing bitmap hashes.  A bitmap hash is a hash
00325  * of dynamically allocated bitmaps, keyed by strings.  Note that these
00326  * cannot be created as shared variables.
00327  */
00328 typedef struct BitmapHash {
00329     ObjType type;       /**< This must have the value OBJ_BITMAP_HASH */
00330     int32   bitzero;    /**< The index of the lowest bit each bitmap can
00331                          * store */
00332     int32   bitmax;     /**< The index of the highest bit each bitmap can
00333                          * store */
00334     HTAB   *hash;       /**< Pointer to the (Postgresql dynahash) hash
00335                          * table */ 
00336 } BitmapHash;
00337 
00338 
00339 /** 
00340  * Subtype of Object for storing arrays of integers.
00341  */
00342 typedef struct Int4Array {
00343     ObjType type;       /**< This must have the value OBJ_INT4_ARRAY */
00344     int32   arrayzero;  /**< The index of array element zero: the
00345                          * index of the lowest numbered bitmap in the
00346                          * array */
00347     int32   arraymax;   /**< The index of the lowest numbered bitmap in
00348                          * the array */
00349     int32   array[0];   /**< Element zero of the array of integers */
00350 } Int4Array;
00351 
00352 
00353 /**
00354  * A Veil variable.  These may be session or shared variables, and may
00355  * contain any Veil variable type.  They are created and accessed by
00356  * vl_lookup_shared_variable() and vl_lookup_variable(), and are stored
00357  * in either the shared hash or one of the session hashes.  See
00358  * veil_shmem.c and veil_variables.c for more details.
00359  */
00360 typedef struct VarEntry {
00361     char  key[HASH_KEYLEN]; /**< String containing variable name */
00362     bool  shared;           /**< Whether this is a shared variable */
00363     Object *obj;            /**< Pointer to the contents of the variable */
00364 } VarEntry;
00365 
00366 
00367 /**
00368  * Describes a veil shared or session variable.  This matches the SQL
00369  * veil_variable_t which is defined as:
00370 \verbatim
00371 create type veil_variable_t as (
00372     name    text,
00373     type    text,
00374     shared  bool,
00375 );
00376 \endverbatim
00377  */
00378 typedef struct veil_variable_t {
00379     char *name;         /**< The name of the variable */
00380     char *type;         /**< The type of the variable (eg "Bitmap") */
00381     bool shared;        /**< Whether this is a shared variable (as
00382                            opposed to a session variable) */
00383 } veil_variable_t;
00384 
00385 
00386 #endif
00387 

Generated on Mon Sep 12 15:26:45 2011 for Veil by  doxygen 1.5.6