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 - 2010 Marc Munro
00006  *     License:      BSD
00007  * $Id: veil_datatypes.h,v 1.7 2008/07/31 19:34:13 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, 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 
00193 /**
00194  * Gives the bitmask index for the bitzero value of a Bitmap.  This is
00195  * part of the "normalisation" process for bitmap ranges.  This process
00196  * allows unlike bitmaps to be more easily compared by forcing bitmap
00197  * indexes to be normalised around 32-bit word boundaries.  Eg, 2 bitmaps
00198  * with domains 1 to 50 and 3 to 55, will have identical bit patterns
00199  * for bits 3 to 50.
00200  * 
00201  * @param x The bitzero value of a bitmap
00202  * 
00203  * @return The bitmask index representing x.
00204  */
00205 #define BITZERO(x) (x & 0xffffffe0)
00206 
00207 /**
00208  * Gives the bitmask index for the bitmax value of a bitmap.  See
00209  * BITZERO() for more information.
00210  *
00211  * @param x The bitmax value of a bitmap
00212  *
00213  * @return The bitmask index representing x.
00214  */
00215 #define BITMAX(x) (x | 0x1f)
00216 
00217 /**
00218  * Gives the index of a bit within the array of 32-bit words that
00219  * comprise the bitmap.
00220  *
00221  * @param x The bit in question
00222  *
00223  * @return The array index of the bit.
00224  */
00225 #define BITSET_ELEM(x) (x >> 5)
00226 
00227 /**
00228  * Gives the index into ::bitmasks for the bit specified in x.
00229  *
00230  * @param x The bit in question
00231  *
00232  * @return The bitmask index
00233  */
00234 #define BITSET_BIT(x) (x & 0x1f)
00235 
00236 /**
00237  * Gives the number of array elements in a ::Bitmap that runs from
00238  * element min to element max.
00239  *
00240  * @param min
00241  * @param max
00242  *
00243  * @return The number of elements in the bitmap.
00244  */
00245 #define ARRAYELEMS(min,max) (((max - BITZERO(min)) >> 5) + 1)
00246 
00247 
00248 /**
00249  * Return the smaller of a or b.  Note that expressions a and b may be
00250  * evaluated more than once.
00251  *
00252  * @param a
00253  * @param b
00254  *
00255  * @return The smaller value of a or b.
00256  */
00257 #define MIN(a,b) ((a < b)? a: b)
00258 
00259 
00260 /**
00261  * Subtype of Object for storing bitmaps.  A bitmap is stored as an
00262  * array of int4 values.  See veil_bitmap.c for more information.  Note
00263  * that the size of a Bitmap structure is determined dynamically at run
00264  * time as the size of the array is only known then.
00265  */
00266 typedef struct Bitmap {
00267     ObjType type;       /**< This must have the value OBJ_BITMAP */
00268     DBG_CANARY_ENTRY
00269     DBG_ELEMS_ENTRY
00270     int32   bitzero;    /**< The index of the lowest bit the bitmap can
00271                          * store */
00272     int32   bitmax;     /**< The index of the highest bit the bitmap can
00273                          * store */
00274     uint32   bitset[EMPTY]; /**< Element zero of the array of int4 values
00275                          * comprising the bitmap. */
00276 } Bitmap;
00277 
00278 /**
00279  * Subtype of Object for storing bitmap refs.  A bitmapref is like a
00280  * bitmap but instead of containing a bitmap it contains a reference to
00281  * one.  This reference may be set during a transaction and then
00282  * referenced only from within the setting transaction.
00283  */
00284 typedef struct BitmapRef {
00285     ObjType        type;    /**< This must have the value OBJ_BITMAP_REF */
00286     TransactionId  xid;     /**< The xid for which this variable is
00287                              * valid */
00288     Bitmap        *bitmap;
00289 } BitmapRef;
00290 
00291 /**
00292  * Subtype of Object for storing bitmap arrays.  A bitmap array is
00293  * simply an array of pointers to dynamically allocated Bitmaps.  Note
00294  * that the size of a Bitmap structure is determined dynamically at run
00295  * time as the size of the array is only known then.
00296  */
00297 typedef struct BitmapArray {    // subtype of Object
00298     ObjType type;       /**< This must have the value OBJ_BITMAP_ARRAY */
00299     DBG_CANARY_ENTRY
00300     DBG_ELEMS_ENTRY
00301     int32   bitzero;    /**< The index of the lowest bit each bitmap can
00302                          * store */
00303     int32   bitmax;     /**< The index of the highest bit each bitmap can
00304                          * store */
00305     int32   arrayzero;  /**< The index of array element zero: the
00306                          * index of the lowest numbered bitmap in the
00307                          * array */
00308     int32   arraymax;   /**< The index of the lowest numbered bitmap in
00309                          * the array */
00310     Bitmap *bitmap[EMPTY];  /** Element zero of the array of Bitmap pointers
00311                          * comprising the array. */
00312 } BitmapArray;
00313 
00314 /** 
00315  * Subtype of Object for storing bitmap hashes.  A bitmap hash is a hash
00316  * of dynamically allocated bitmaps, keyed by strings.  Note that these
00317  * cannot be created as shared variables.
00318  */
00319 typedef struct BitmapHash {
00320     ObjType type;       /**< This must have the value OBJ_BITMAP_HASH */
00321     int32   bitzero;    /**< The index of the lowest bit each bitmap can
00322                          * store */
00323     int32   bitmax;     /**< The index of the highest bit each bitmap can
00324                          * store */
00325     HTAB   *hash;       /**< Pointer to the (Postgresql dynahash) hash
00326                          * table */ 
00327 } BitmapHash;
00328 
00329 
00330 /** 
00331  * Subtype of Object for storing arrays of integers.
00332  */
00333 typedef struct Int4Array {
00334     ObjType type;       /**< This must have the value OBJ_INT4_ARRAY */
00335     int32   arrayzero;  /**< The index of array element zero: the
00336                          * index of the lowest numbered bitmap in the
00337                          * array */
00338     int32   arraymax;   /**< The index of the lowest numbered bitmap in
00339                          * the array */
00340     int32   array[0];   /** Element zero of the array of integers */
00341 } Int4Array;
00342 
00343 
00344 /**
00345  * A Veil variable.  These may be session or shared variables, and may
00346  * contain any Veil variable type.  They are created and accessed by
00347  * vl_lookup_shared_variable() and vl_lookup_variable(), and are stored
00348  * in either the shared hash or one of the session hashes.  See
00349  * veil_shmem.c and veil_variables.c for more details.
00350  */
00351 typedef struct VarEntry {
00352     char  key[HASH_KEYLEN]; /**< String containing variable name */
00353     bool  shared;           /**< Whether this is a shared variable */
00354     Object *obj;            /**< Pointer to the contents of the variable */
00355 } VarEntry;
00356 
00357 
00358 /**
00359  * Describes a veil shared or session variable.  This matches the SQL
00360  * veil_variable_t which is defined as:
00361 \verbatim
00362 create type veil_variable_t as (
00363     name    text,
00364     type    text,
00365     shared  bool,
00366 );
00367 \endverbatim
00368  */
00369 typedef struct veil_variable_t {
00370     char *name;         /**< The name of the variable */
00371     char *type;         /**< The type of the variable (eg "Bitmap") */
00372     bool shared;        /**< Whether this is a shared variable (as
00373                            opposed to a session variable) */
00374 } veil_variable_t;
00375 
00376 
00377 #endif
00378 

Generated on Fri Mar 12 08:38:37 2010 for Veil by  doxygen 1.5.6