logic/QueryCallbacks.h

   1 #ifndef QueryCallbacks_H
   2 #define QueryCallbacks_H
   3
   4 #include <BindingTable.h>
   5
   6 typedef struct Query Query; // forward
   7
   8 enum NextState {
   9     /**
  10      * This state tells the "next" function that it should capture the
  11      * incoming BindingTable state and provide the initial Binding of
  12      * a new sucession of bindings.
  13      */
  14     initial,
  15     /**
  16      * This state tells the "next" function that it should update the
  17      * bidning table with a subsequent Binding in the current
  18      * succession of bindings.
  19      */
  20     subsequent,
  21     /**
  22      * This state tells the "next" function that it should just
  23      * restore the Binding table to its incoming state.
  24      */
  25     restore
  26 };
  27
  28 /**
  29  * A struct Query_callbacks record defines the callbacks for a
  30  * specific Query type.
  31  */
  32 typedef struct QueryCallbacks {
  33     /**
  34      * \brief Callback function to reclaim the Query memory for a
  35      * given Query.
  36      *
  37      * \param this is the specific \ref Query concerned.
  38      *
  39      * Ground queries recalim their own state memory. Composite
  40      * queries first propagate the reclaim call to its components, and
  41      * thereafter reclaim their local state memory.
  42      */
  43     void (*reclaim)(Query *this);
  44
  45     /**
  46      * \brief Callback function to update the Binding table with a
  47      * succession of alternative bindings.
  48      *
  49      * \param this is the specific \ref Query concerned.
  50      *
  51      * \param bt is the Binding table to set bindings in.
  52      *
  53      * \param s is the call "sub-command" for the function.
  54      *
  55      * \returns 1 if a new Binding is provided and 0 otherwise.
  56      *
  57      * This function is called repeatedly for successively obtaining
  58      * the alternative bindings that satisfy the Query. The "initial"
  59      * state sub-command tells the function to capture the incoming
  60      * BindingTable state so that the function can later restore it
  61      * upon the "restore" sub-command. Upon the "initial" command, the
  62      * function also sets up the Binding table with its first Binding
  63      * alternative. This is followed by a series of "subsequent"
  64      * sub-command calls for the function to change the BindingTable
  65      * for its succession of Binding alternatives. The function should
  66      * return 1 after any successful Binding setup, and return 0 when
  67      * it cannot setup any (more) Binding.
  68      */
  69     int (*next)(Query *this,BindingTable *bt,enum NextState state);
  70
  71     /**
  72      * \brief This callback function adds its binding names to the
  73      * hashvector.
  74      */
  75     void (*variables)(Query *this,HashVector *hv);
  76 } QueryCallbacks;
  77
  78 #endif