vector/tupleitem.h

   1 #ifndef tupleitem_H
   2 #define tupleitem_H
   3
   4 #include <itemkeyfun.h>
   5
   6 /**
   7  * A tuple is an array of void*
   8  */
   9 typedef void *tuple[];
  10
  11 /**
  12  * A tupleschema record declares the itemkeyfun functions for tuple
  13  * items together with applicable arity and domain combinations. The
  14  * macro \ref TUPLEITEMINIT may be used to initialize particular
  15  * tupleschema records, which each become tupleitem declaration for
  16  * its particular arity and parts declarations
  17  */
  18 typedef struct {
  19     /**
  20      * These are the itemkeyfun callback functions to support
  21      * hashvector use for tuple items. The functions expects their
  22      * itemkeyfun pointer to be within a tupleschema record so as to
  23      * provide the handling of the tuple columns.
  24      */
  25     itemkeyfun functions;
  26
  27     /**
  28      * This is the number of columns in a tuple.
  29      */
  30     int arity;
  31
  32     /**
  33      * This points to an array of pointers to the tuple item domains
  34      * as represented by their associated itemkeyfun records.
  35      */
  36     itemkeyfun **columns;
  37 } tupleschema;
  38
  39 /**
  40  * This callback function returns the hashcode of a key.
  41  *
  42  * \param this is a pointer to the itemkeyfun record from where this
  43  * callback got invoked
  44  *
  45  * \param key is the key to produce a hascode for
  46  *
  47  * \returns the hashcode which is a vector_index (i.e. unsigned long)
  48  *
  49  * The hashcode is used for indexing into the backing vector for
  50  * finding the an item via its key. The same key must map consistently
  51  * to the same hashcode while the hashtable contains an item with that
  52  * key. Different keys map map to the same hashcode, in which case the
  53  * vector placement is made at the first empty or hole slot following
  54  * the hashcode index.
  55  */
  56 extern unsigned long tupleitem_hashcode(itemkeyfun *this,void *key);
  57
  58 /**
  59  * This callback function determines whether an item has a
  60  * given key or not.
  61  */
  62 extern int tupleitem_haskey(itemkeyfun *this,void *item,void *key);
  63
  64 /**
  65  * This callback function returns the key of an item by considering
  66  * the arity and schema.
  67  */
  68 extern void *tupleitem_itemkey(itemkeyfun *this,void *item);
  69
  70 /**
  71  * This callback function handles a key obtained from the itemkey
  72  * callback function to reclaim temporary allocation.
  73  */
  74 extern void tupleitem_releasekey(itemkeyfun *this,void *key);
  75
  76 /**
  77  * Create a tuples with given values.
  78  */
  79 extern tuple *tuple_create(int arity,...);
  80
  81 /**
  82  * Create a tuples with given values.
  83  */
  84 extern tupleschema *tupleschema_create(int arity,tuple *columns);
  85
  86 /**
  87  * Copy the given tupleschema into a new tupleschema with some columns
  88  * masked. This represents a sub-index type using the unmasked columns
  89  * for indexing.
  90  */
  91 extern tupleschema *tupleschema_mask(tupleschema *schema,...);
  92
  93 /**
  94  * The TUPLEITEMINIT macro is used for initializing a tupleschema
  95  * record appropriately for a given arity and corresponding sequence
  96  * of parts itemkeyfun pointers.
  97  */
  98 #define TUPLEITEMINIT(arity, ... ) {    \
  99         .functions = {                          \
 100             .hashcode = tupleitem_hashcode,     \
 101             .haskey = tupleitem_haskey,         \
 102             .itemkey = tupleitem_itemkey,       \
 103             .releasekey = tupleitem_releasekey  \
 104         },                                      \
 105             .arity = arity,                     \
 106             .schema = { __VA_ARGS__ }           \
 107     }
 108
 109 #endif