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, 2006 Marc Munro
00006  *     License:      BSD
00007  * $Id: veil_datatypes.h,v 1.5 2007/07/31 22:18:27 bloodnok Exp $
00008  * \endcode
00009  * @brief  
00010  * Define all Veil public datatypes 
00011  * 
00012  */
00013 
00014 #ifndef VEIL_DATATYPES
00015 #define VEIL_DATATYPES 1
00016 
00017 #ifndef VEIL_DEBUG
00018 /**
00019  * Enables various debugging constructs, such as canaries, in code and
00020  * data structures.  If such debugging is required, define VEIL_DEBUG in
00021  * the make invocation, eg: "make VEIL_DEBUG=1".
00022  */
00023 #define VEIL_DEBUG 1
00024 #endif 
00025 
00026 #if VEIL_DEBUG == 1
00027 /** 
00028  * Value to be set in sacrificial "canary" fields.  If this value is not
00029  * as expected, the canaryu has been killed by something inappropriately 
00030  * stomping on memory.
00031  */
00032 #define DBG_CANARY 0xca96ca96
00033 
00034 /** 
00035  * Defines a canary element in a data structure.
00036  */
00037 #define DBG_CANARY_ENTRY int32 canary;
00038 
00039 /** 
00040  * Field to record the size of an array so that its canary element can
00041  * be found.
00042  */
00043 #define DBG_ELEMS_ENTRY  int32 dbgelems;
00044 
00045 /** 
00046  * Code to records the size of an array so that its canary element can
00047  * be found.
00048  */
00049 #define DBG_SET_ELEMS(x,y) (x).dbgelems = y
00050 
00051 /** 
00052  * Code to initialise a canary.
00053  */
00054 #define DBG_SET_CANARY(x) (x).canary = DBG_CANARY
00055 
00056 /** 
00057  * Code to test for a canary having been overwritten.
00058  */
00059 #define DBG_TEST_CANARY(x) if ((x).canary != DBG_CANARY) {\
00060         elog(ERROR, "canary fault"); }
00061 
00062 /** 
00063  * Base size for an array containing a canary.  This is zero if
00064  * VEIL_DEBUG is not defined, iw when this is defined arrays will be one
00065  * element longer to allow a canary to be placed at the end of the array.
00066  */
00067 #define EMPTY 1
00068 
00069 /**
00070  * Set a trailing canary in an array.
00071  */
00072 #define DBG_SET_TRAILER(x, y) (x).y[(x).dbgelems] = DBG_CANARY;
00073 
00074 /**
00075  * Test the trailing canary in an array.
00076  */
00077 #define DBG_TEST_TRAILER(x, y) if ((x).y[(x).dbgelems] != DBG_CANARY) {\
00078         elog(ERROR, "trailing canary fault"); }
00079 
00080 /**
00081  * Check whether an array index is in bounds.
00082  */
00083 #define DBG_CHECK_INDEX(x,i) if (i >= (x).dbgelems) {\
00084         elog(ERROR, "Element index out of range %d", i); }
00085 
00086 #else
00087 #define DBG_CANARY_ENTRY 
00088 #define DBG_ELEMS_ENTRY 
00089 #define DBG_SET_ELEMS(x,y)
00090 #define DBG_SET_CANARY(x) 
00091 #define DBG_TEST_CANARY(x)
00092 #define EMPTY 0
00093 #define DBG_SET_TRAILER(x,Y)
00094 #define DBG_TEST_TRAILER(x,Y)
00095 #define DBG_CHECK_INDEX(x,i)
00096 #endif
00097 
00098 #include "utils/hsearch.h"
00099 #include "storage/lwlock.h"
00100 
00101 /** 
00102  * Chunks provide a linked list of dynamically allocated shared memory
00103  * segments, with the most recently allocated chunk at the tail.
00104  * Shmalloc allocates space from this list of chunks, creating new
00105  * chunks as needed up to MAX_ALLOWED_SHMEM.
00106  */
00107 typedef struct MemChunk {
00108     struct MemChunk *next_chunk;  /**< Pointer to next allocated chunk */
00109     size_t  next;                 /**< Offset, within this chunk, of 1st
00110                                    * free byte */
00111     size_t  limit;                /**< Offset, of 1st byte beyond chunk */
00112     void   *memory[0];            /**< The rest of the chunk, from which
00113                                    * memory is allocated */
00114 } MemChunk;
00115 
00116 
00117 
00118 /**
00119  * The key length for veil hash types.
00120  */
00121 #define HASH_KEYLEN           60
00122 
00123 
00124 /**
00125  * Describes the type of an Object record or one of its subtypes.
00126  */
00127 typedef enum { 
00128     OBJ_UNDEFINED = 0,
00129     OBJ_SHMEMCTL,
00130     OBJ_INT4,
00131     OBJ_RANGE,
00132     OBJ_BITMAP,
00133     OBJ_BITMAP_ARRAY,
00134     OBJ_BITMAP_HASH,
00135     OBJ_BITMAP_REF,
00136     OBJ_INT4_ARRAY
00137 } ObjType;
00138 
00139 /** 
00140  * General purpose object-type.  All veil variables are effectively
00141  * sub-types of this.
00142  */
00143 typedef struct Object {
00144     ObjType type;
00145 } Object;
00146 
00147 /** 
00148  * The ShmemCtl structure is the first object allocated from the first
00149  * chunk of shared memory in context 0.  This object describes and
00150  * manages shared memory allocated by shmalloc()
00151  */
00152 typedef struct ShmemCtl {
00153     ObjType type;                 /**< This must have the value OBJ_SHMEMCTL */
00154     bool      initialised;        /**< Set to true once struct is setup */
00155     LWLockId  veil_lwlock;        /** dynamically allocated LWLock */
00156     int       current_context;    /**< Index of the current context (0
00157                                    * or 1) */
00158     size_t    total_allocated[2]; /**< Total shared memory allocated in
00159                                    * chunks in each context */ 
00160     bool      switching;          /**< Whether a context-switch is in
00161                                    * progress */
00162     MemChunk *context[2];         /**< The first chunks of each context */
00163     TransactionId xid[2];         /**< The transaction id of the
00164                                    * transaction that initialised each
00165                                    * context: this is used to determine
00166                                    * whether there are transactions
00167                                    * still runnning that may be using an
00168                                    * earlier context. */
00169 } ShmemCtl;
00170 
00171 /**
00172  * Subtype of Object for storing simple int4 values.  These values are
00173  * allowed to be null.
00174  */
00175 typedef struct Int4Var {
00176     ObjType type;       /**< This must have the value OBJ_INT4 */
00177     bool    isnull;     /**< if true, the value is null */
00178     int32   value;      /**< the integer value of the variable */
00179 } Int4Var;
00180 
00181 /**
00182  * Subtype of Object for storing range values.  A range has an upper and
00183  * lower bound, both stored as int4s.  Nulls are not allowed.
00184  */
00185 typedef struct Range {
00186     ObjType type;       /**< This must have the value OBJ_RANGE */
00187     int32   min;
00188     int32   max;
00189 } Range;
00190 
00191 /**
00192  * Subtype of Object for storing bitmaps.  A bitmap is stored as an
00193  * array of int4 values.  See veil_bitmap.c for more information.  Note
00194  * that the size of a Bitmap structure is determined dynamically at run
00195  * time as the size of the array is only known then.
00196  */
00197 typedef struct Bitmap {
00198     ObjType type;       /**< This must have the value OBJ_BITMAP */
00199     DBG_CANARY_ENTRY
00200     DBG_ELEMS_ENTRY
00201     int32   bitzero;    /**< The index of the lowest bit the bitmap can
00202                          * store */
00203     int32   bitmax;     /**< The index of the highest bit the bitmap can
00204                          * store */
00205     uint32   bitset[EMPTY]; /**< Element zero of the array of int4 values
00206                          * comprising the bitmap. */
00207 } Bitmap;
00208 
00209 /**
00210  * Subtype of Object for storing bitmap refs.  A bitmapref is like a
00211  * bitmap but instead of containing a bitmap it contains a reference to
00212  * one.  This reference may be set during a transaction and then
00213  * referenced only from within the setting transaction.
00214  */
00215 typedef struct BitmapRef {
00216     ObjType        type;    /**< This must have the value OBJ_BITMAP_REF */
00217     TransactionId  xid;     /**< The xid for which this variable is
00218                              * valid */
00219     Bitmap        *bitmap;
00220 } BitmapRef;
00221 
00222 /**
00223  * Subtype of Object for storing bitmap arrays.  A bitmap array is
00224  * simply an array of pointers to dynamically allocated Bitmaps.  Note
00225  * that the size of a Bitmap structure is determined dynamically at run
00226  * time as the size of the array is only known then.
00227  */
00228 typedef struct BitmapArray {    // subtype of Object
00229     ObjType type;       /**< This must have the value OBJ_BITMAP_ARRAY */
00230     DBG_CANARY_ENTRY
00231     DBG_ELEMS_ENTRY
00232     int32   bitzero;    /**< The index of the lowest bit each bitmap can
00233                          * store */
00234     int32   bitmax;     /**< The index of the highest bit each bitmap can
00235                          * store */
00236     int32   arrayzero;  /**< The index of array element zero: the
00237                          * index of the lowest numbered bitmap in the
00238                          * array */
00239     int32   arraymax;   /**< The index of the lowest numbered bitmap in
00240                          * the array */
00241     Bitmap *bitmap[EMPTY];  /** Element zero of the array of Bitmap pointers
00242                          * comprising the array. */
00243 } BitmapArray;
00244 
00245 /** 
00246  * Subtype of Object for storing bitmap hashes.  A bitmap hash is a hash
00247  * of dynamically allocated bitmaps, keyed by strings.  Note that these
00248  * cannot be created as shared variables.
00249  */
00250 typedef struct BitmapHash {
00251     ObjType type;       /**< This must have the value OBJ_BITMAP_HASH */
00252     int32   bitzero;    /**< The index of the lowest bit each bitmap can
00253                          * store */
00254     int32   bitmax;     /**< The index of the highest bit each bitmap can
00255                          * store */
00256     HTAB   *hash;       /**< Pointer to the (Postgresql dynahash) hash
00257                          * table */ 
00258 } BitmapHash;
00259 
00260 
00261 /** 
00262  * Subtype of Object for storing arrays of integers.
00263  */
00264 typedef struct Int4Array {
00265     ObjType type;       /**< This must have the value OBJ_INT4_ARRAY */
00266     int32   arrayzero;  /**< The index of array element zero: the
00267                          * index of the lowest numbered bitmap in the
00268                          * array */
00269     int32   arraymax;   /**< The index of the lowest numbered bitmap in
00270                          * the array */
00271     int32   array[0];   /** Element zero of the array of integers */
00272 } Int4Array;
00273 
00274 
00275 /**
00276  * A Veil variable.  These may be session or shared variables, and may
00277  * contain any Veil variable type.  They are created and accessed by
00278  * vl_lookup_shared_variable() and vl_lookup_variable(), and are stored
00279  * in either the shared hash or one of the session hashes.  See
00280  * veil_shmem.c and veil_variables.c for more details.
00281  */
00282 typedef struct VarEntry {
00283     char  key[HASH_KEYLEN]; /**< String containing variable name */
00284     bool  shared;           /**< Whether this is a shared variable */
00285     Object *obj;            /**< Pointer to the contents of the variable */
00286 } VarEntry;
00287 
00288 
00289 /**
00290  * Describes a veil shared or session variable.  This matches the SQL
00291  * veil_variable_t which is defined as:
00292 \verbatim
00293 create type veil_variable_t as (
00294     name    text,
00295     type    text,
00296     shared  bool,
00297 );
00298 \endverbatim
00299  */
00300 typedef struct veil_variable_t {
00301     char *name;         /**< The name of the variable */
00302     char *type;         /**< The type of the variable (eg "Bitmap") */
00303     bool shared;        /**< Whether this is a shared variable (as
00304                            opposed to a session variable) */
00305 } veil_variable_t;
00306 
00307 
00308 #endif
00309 

Generated on Tue Mar 11 10:20:03 2008 for Veil by  doxygen 1.5.4