4 #include <QueryCallbacks.h>
5 #include <BindingTable.h>
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.
15 typedef struct Query {
16 struct QueryCallbacks *def;
20 * \brief Trampoline for the callback function to reclaim the Query
21 * memory for a given Query.
23 * \param this is the specific \ref Query concerned.
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.
29 extern void Query_reclaim(Query *this);
32 * \brief Trampoline for the callback function to update the Binding
33 * table with a succession of alternative bindings.
35 * \param this is the specific \ref Query concerned.
37 * \param bt is the Binding table to set bindings in.
39 * \param s is the call "sub-command" for the function.
41 * \returns 1 if a new Binding is provided and 0 otherwise.
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.
55 extern int Query_next(Query *this,BindingTable *bt,enum NextState state);
58 * \brief Trampoline for the callback function that adds its binding
59 * names to the hashvector.
61 * \param this is the query concerned.
63 * \param hv is the HashVector for collating names.
65 extern void Query_variables(Query *this,HashVector *hv);
71 * \brief Creates an assignment Query.
73 * \param arity is the assignment tuple arity.
75 * \param names is the (char*) names to assign.
77 * \param values is the (void*) values to asign.
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.
85 extern Query *Query_assign(int arity,Tuple *names,Tuple *values);
88 * \brief Create a Query record for lookup data in a Relation.
90 * \param r is the relation being queried.
92 * \param names is a same-arity tuple of binding names for the
93 * columns, using \b 0 for unnamed columns.
95 * \param values is a same--arity tuple of query values, using \b 0 for
96 * columns to enumerate.
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.
106 extern Query *Query_Relation(Relation *r,Tuple *names,Tuple *values);
109 * \brief Create a Query record for a conjunction of queries.
111 * \param n is the number of sub queries.
113 * \param ... are the sub queries.
115 * The conjunction query processes the sub queries in order resulting
116 * in the sequence of their combined bindings.
120 extern Query *Query_and(int n,...);
123 * \brief Create a Query record for a disjunction of queries.
125 * \param n is the number of sub queries.
127 * \param ... are the sub queries.
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.
136 extern Query *Query_or(int n,...);
139 * \brief Invoke a consequent callback function for each successful
140 * binding of a query.
142 * \param q is the antecedent query to process.
144 * \param bt is the binding table to use.
146 * \param consequent is the callback function to invoke for each
148 * \param data is the caller's context data.
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.
156 extern void Query_eval(
157 Query *q,BindingTable *bt,
158 int (*consequent)(BindingTable *bt,void *data),
162 * \brief Collect all bindings of query.
164 * \param q is the query to enumerate.
166 * \param names is the binding names to track.
168 * \param results is the result store of bindings for the names.
170 * \returns the number of results.
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
179 //extern int Query_snapshot(Query *q,Tuple *names,Vector *v);
182 * \brief Creates an NotQuery.
184 * \param query is the query to negate.
188 extern Query *Query_not(Query *values);