vector/Query.h

   1 #ifndef Query_H
   2 #define Query_H
   3
   4 #include <QueryCallbacks.h>
   5 #include <BindingTable.h>
   6 #include <Relation.h>
   7
   8 /**
   9  * A Query is an implementation of a generic ABI over relations. It's
  10  * more or less a "virtual Relation" representing a logical composite
  11  * access of actual relations, and as such its active part is held in
  12  * a separate \ref Querytype record similar to how \ref ItemKeyFun
  13  * records define valye types.
  14  */
  15 typedef struct Query {
  16     struct QueryCallbacks *def;
  17 } Query;
  18
  19 /**
  20  * \brief Trampoline for the callback function to reclaim the Query
  21  * memory for a given Query.
  22  *
  23  * \param this is the specific \ref Query concerned.
  24  *
  25  * Ground queries recalim their own state memory. Composite
  26  * queries first propagate the reclaim call to its components, and
  27  * thereafter reclaim their local state memory.
  28  */
  29 extern void Query_reclaim(Query *this);
  30
  31 /**
  32  * \brief Trampoline for the callback function to update the Binding
  33  * table with a succession of alternative bindings.
  34  *
  35  * \param this is the specific \ref Query concerned.
  36  *
  37  * \param bt is the Binding table to set bindings in.
  38  *
  39  * \param s is the call "sub-command" for the function.
  40  *
  41  * \returns 1 if a new Binding is provided and 0 otherwise.
  42  *
  43  * This function is called repeatedly for successively obtaining
  44  * the alternative bindings that satisfy the Query. The "initial"
  45  * state sub-command tells the function to capture the incoming
  46  * BindingTable state so that the function can later restore it
  47  * upon the "restore" sub-command. Upon the "initial" command, the
  48  * function also sets up the Binding table with its first Binding
  49  * alternative. This is followed by a series of "subsequent"
  50  * sub-command calls for the function to change the BindingTable
  51  * for its succession of Binding alternatives. The function should
  52  * return 1 after any successful Binding setup, and return 0 when
  53  * it cannot setup any (more) Binding.
  54  */
  55 extern int Query_next(Query *this,BindingTable *bt,enum NextState state);
  56
  57 /**
  58  * \brief Trampoline for the callback function that adds its binding
  59  * names to the hashvector.
  60  *
  61  * \param this is the query concerned.
  62  *
  63  * \param hv is the HashVector for collating names.
  64  */
  65 extern void Query_variables(Query *this,HashVector *hv);
  66
  67
  68
  69
  70 /**
  71  * \brief Creates an assignment Query.
  72  *
  73  * \param arity is the assignment tuple arity.
  74  *
  75  * \param names is the (char*) names to assign.
  76  *
  77  * \param values is the (void*) values to asign.
  78  *
  79  * The two tuples must have the same arity for assigning names[i] to
  80  * values[i]. This Query makes the given names have the given values,
  81  * once for each (*next) call following a (*reset) call.
  82  *
  83  * \related Query
  84  */
  85 extern Query *Query_assign(int arity,Tuple *names,Tuple *values);
  86
  87 /**
  88  * \brief Create a Query record for lookup data in a Relation.
  89  *
  90  * \param r is the relation being queried.
  91  *
  92  * \param names is a same-arity tuple of binding names for the
  93  * columns, using \b 0 for unnamed columns.
  94  *
  95  * \param values is a same--arity tuple of query values, using \b 0 for
  96  * columns to enumerate.
  97  *
  98  * The names and values tuples identify bindings and values to use for
  99  * the search query, and which bindings to set up from the successive
 100  * results. Names that are bound beforhand identify constraining
 101  * values, and the names that are unbound gain successive values from
 102  * the matching tuples.
 103  *
 104  * \related Query
 105  */
 106 extern Query *Query_Relation(Relation *r,Tuple *names,Tuple *values);
 107
 108 /**
 109  * \brief Create a Query record for a conjunction of queries.
 110  *
 111  * \param n is the number of sub queries.
 112  *
 113  * \param ... are the sub queries.
 114  *
 115  * The conjunction query processes the sub queries in order resulting
 116  * in the sequence of their combined bindings.
 117  *
 118  * \related Query
 119  */
 120 extern Query *Query_and(int n,...);
 121
 122 /**
 123  * \brief Create a Query record for a disjunction of queries.
 124  *
 125  * \param n is the number of sub queries.
 126  *
 127  * \param ... are the sub queries.
 128  *
 129  * The disjunction query processed the sub queries in order to find
 130  * all their individual "true" binding combinations. It processes one
 131  * sub query at a time to exhaustion and provide their individudal
 132  * binding sequences separately.
 133  *
 134  * \related Query
 135  */
 136 extern Query *Query_or(int n,...);
 137
 138 /**
 139  * \brief Invoke a consequent callback function for each successful
 140  * binding of a query.
 141  *
 142  * \param q is the antecedent query to process.
 143  *
 144  * \param bt is the binding table to use.
 145  *
 146  * \param consequent is the callback function to invoke for each
 147  * binding.
 148  * \param data is the caller's context data.
 149  *
 150  * This function prrocesses the Query for establishing its binding
 151  * sequence and inokes the consequent callback function for each
 152  * binding as it is provided.
 153  *
 154  * \related Query
 155  */
 156 extern void Query_eval(
 157     Query *q,BindingTable *bt,
 158     int (*consequent)(BindingTable *bt,void *data),
 159     void *data );
 160
 161 /**
 162  * \brief Collect all bindings of query.
 163  *
 164  * \param q is the query to enumerate.
 165  *
 166  * \param names is the binding names to track.
 167  *
 168  * \param results is the result store of bindings for the names.
 169  *
 170  * \returns the number of results.
 171  *
 172  * This function evaluates the query for one round of bindings, and
 173  * stores their value \ref Tuple Tuples in the given vector. The given
 174  * vector is first cleared, and any item is reclaimed with \b free.
 175  * Correspondingly the binding \ref Tuple Tuples are allocated with \b
 176  * malloc for the caller to reclaim (possibly via a successive call to
 177  * this function).
 178  */
 179 //extern int Query_snapshot(Query *q,Tuple *names,Vector *v);
 180
 181 /**
 182  * \brief Creates an NotQuery.
 183  *
 184  * \param query is the query to negate.
 185  *
 186  * \related Query
 187  */
 188 extern Query *Query_not(Query *values);
 189
 190 #endif