improving datastore API --- not working yet

2 files changed, 74 insertions, 78 deletions

diff --git a/src/include/gnunet_datastore_plugin.h b/src/include/gnunet_datastore_plugin.h
index c981ceb1d..34a659163 100644
--- a/src/include/gnunet_datastore_plugin.h
+++ b/src/include/gnunet_datastore_plugin.h
@@ -162,7 +162,7 @@ typedef int (*PluginPut) (void *cls,
                           uint32_t anonymity,
                           uint32_t replication,
                           struct GNUNET_TIME_Absolute expiration,
-                           char **msg);
+                          char **msg);
 
 
 /**
@@ -187,26 +187,25 @@ typedef int (*PluginPut) (void *cls,
  * @param iter_cls closure for iter
  */
 typedef void (*PluginGet) (void *cls,
-                           const GNUNET_HashCode * key,
-                           const GNUNET_HashCode * vhash,
+                           const GNUNET_HashCode *key,
+                           const GNUNET_HashCode *vhash,
                            enum GNUNET_BLOCK_Type type,
                            PluginIterator iter, void *iter_cls);
 
 
 
 /**
- * Get a random item for replication.  Returns a single, 
- * not expired, random item
- * from those with the highest replication counters.  The item's 
- * replication counter is decremented by one IF it was positive before.
- * Call 'iter' with all values ZERO or NULL if the datastore is empty.
+ * Get a random item (additional constraints may apply depending on
+ * the specific implementation).  Calls 'iter' with all values ZERO or
+ * NULL if no item applies, otherwise 'iter' is called once and only
+ * once with an item, with the 'next_cls' argument being NULL.
  *
  * @param cls closure
  * @param iter function to call the value (once only).
  * @param iter_cls closure for iter
  */
-typedef void (*PluginReplicationGet) (void *cls,
-                                      PluginIterator iter, void *iter_cls);
+typedef void (*PluginRandomGet) (void *cls,
+                                 PluginIterator iter, void *iter_cls);
 
 
 /**
@@ -234,13 +233,16 @@ typedef void (*PluginReplicationGet) (void *cls,
  */
 typedef int (*PluginUpdate) (void *cls,
                              uint64_t uid,
-                             int delta, struct GNUNET_TIME_Absolute expire,
+                             int delta, 
+                             struct GNUNET_TIME_Absolute expire,
                              char **msg);
 
 
 /**
- * Select a subset of the items in the datastore and call
- * the given iterator for each of them.
+ * Select a subset of the items in the datastore and call the given
+ * iterator for the first item; then allow getting more items by
+ * calling the 'next_request' callback with the given 'next_cls'
+ * argument passed to 'iter'.
  *
  * @param cls closure
  * @param type entries of which type should be considered?
@@ -258,6 +260,7 @@ typedef void (*PluginSelector) (void *cls,
                                 PluginIterator iter,
                                 void *iter_cls);
 
+
 /**
  * Drop database.
  *
@@ -307,9 +310,18 @@ struct GNUNET_DATASTORE_PluginFunctions
 
   /**
    * Function to get a random item with high replication score from
-   * the database, lowering the item's replication score.
+   * the database, lowering the item's replication score.  Returns a
+   * single, not expired, random item from those with the highest
+   * replication counters.  The item's replication counter is
+   * decremented by one IF it was positive before.
+   */
+  PluginRandomGet replication_get;
+
+  /**
+   * Function to get a random expired item or, if none are expired, one
+   * with a low priority.
    */
-  PluginReplicationGet replication_get;
+  PluginRandomGet expiration_get;
 
   /**
    * Update the priority for a particular key in the datastore.  If
@@ -322,31 +334,11 @@ struct GNUNET_DATASTORE_PluginFunctions
   PluginUpdate update;
 
   /**
-   * Iterate over the items in the datastore in ascending
-   * order of priority.
-   */
-  PluginSelector iter_low_priority;
-
-  /**
-   * Iterate over content with anonymity zero.
+   * Iterate over content with anonymity level zero.
    */
   PluginSelector iter_zero_anonymity;
 
   /**
-   * Iterate over the items in the datastore in ascending order of
-   * expiration time. 
-   */
-  PluginSelector iter_ascending_expiration;
-
-  /**
-   * Iterate over the items in the datastore in migration
-   * order.  Call the given function on the next item only
-   * (and then signal 'end' with a second call).  This is
-   * a significant difference from all the other iterators!
-   */
-  PluginSelector iter_migration_order;
-
-  /**
    * Iterate over all the items in the datastore
    * as fast as possible in a single transaction
    * (can lock datastore while this happens, focus
diff --git a/src/include/gnunet_datastore_service.h b/src/include/gnunet_datastore_service.h
index 1e2e9e050..284d544f5 100644
--- a/src/include/gnunet_datastore_service.h
+++ b/src/include/gnunet_datastore_service.h
@@ -82,11 +82,11 @@ void GNUNET_DATASTORE_disconnect (struct GNUNET_DATASTORE_Handle *h,
  * @param cls closure
  * @param success GNUNET_SYSERR on failure, 
  *                GNUNET_NO on timeout/queue drop
- *                GNUNET_YES on success
+ *                GNUNET_YES (or other positive value) on success
  * @param msg NULL on success, otherwise an error message
  */
 typedef void (*GNUNET_DATASTORE_ContinuationWithStatus)(void *cls,
-                                                        int success,
+                                                        int32_t success,
                                                         const char *msg);
 
 
@@ -148,7 +148,7 @@ GNUNET_DATASTORE_reserve (struct GNUNET_DATASTORE_Handle *h,
  */
 struct GNUNET_DATASTORE_QueueEntry *
 GNUNET_DATASTORE_put (struct GNUNET_DATASTORE_Handle *h,
-                      int rid,
+                      uint32_t rid,
                       const GNUNET_HashCode * key,
                       size_t size,
                       const void *data,
@@ -187,7 +187,7 @@ GNUNET_DATASTORE_put (struct GNUNET_DATASTORE_Handle *h,
  */
 struct GNUNET_DATASTORE_QueueEntry *
 GNUNET_DATASTORE_release_reserve (struct GNUNET_DATASTORE_Handle *h,
-                                  int rid,
+                                  uint32_t rid,
                                   unsigned int queue_priority,
                                   unsigned int max_queue_size,
                                   struct GNUNET_TIME_Relative timeout,
@@ -214,7 +214,7 @@ GNUNET_DATASTORE_release_reserve (struct GNUNET_DATASTORE_Handle *h,
  */
 struct GNUNET_DATASTORE_QueueEntry *
 GNUNET_DATASTORE_update (struct GNUNET_DATASTORE_Handle *h,
-                         unsigned long long uid,
+                         uint64_t uid,
                          uint32_t priority,
                          struct GNUNET_TIME_Absolute expiration,
                          unsigned int queue_priority,
@@ -287,7 +287,7 @@ typedef void (*GNUNET_DATASTORE_Iterator) (void *cls,
  * in the datastore.  The iterator will only be called
  * once initially; if the first call did contain a
  * result, further results can be obtained by calling
- * "GNUNET_DATASTORE_get_next" with the given argument.
+ * "GNUNET_DATASTORE_iterate_get_next" with the given argument.
  *
  * @param h handle to the datastore
  * @param key maybe NULL (to match all entries)
@@ -304,24 +304,54 @@ typedef void (*GNUNET_DATASTORE_Iterator) (void *cls,
  *         (or rather, will already have been invoked)
  */
 struct GNUNET_DATASTORE_QueueEntry *
-GNUNET_DATASTORE_get (struct GNUNET_DATASTORE_Handle *h,
-                      const GNUNET_HashCode * key,
-                      enum GNUNET_BLOCK_Type type,
-                      unsigned int queue_priority,
-                      unsigned int max_queue_size,
-                      struct GNUNET_TIME_Relative timeout,
-                      GNUNET_DATASTORE_Iterator iter, 
-                      void *iter_cls);
+GNUNET_DATASTORE_iterate_key (struct GNUNET_DATASTORE_Handle *h,
+                              const GNUNET_HashCode * key,
+                              enum GNUNET_BLOCK_Type type,
+                              unsigned int queue_priority,
+                              unsigned int max_queue_size,
+                              struct GNUNET_TIME_Relative timeout,
+                              GNUNET_DATASTORE_Iterator iter, 
+                              void *iter_cls);
+
+
+/**
+ * Get all zero-anonymity values from the datastore.
+ *
+ * @param h handle to the datastore
+ * @param queue_priority ranking of this request in the priority queue
+ * @param max_queue_size at what queue size should this request be dropped
+ *        (if other requests of higher priority are in the queue)
+ * @param timeout how long to wait at most for a response
+ * @param type allowed type for the operation (ANY for 'all types')
+ * @param iter function to call on a random value; it
+ *        will be called once with a value (if available)
+ *        and always once with a value of NULL at the end.
+ * @param iter_cls closure for iter
+ * @return NULL if the entry was not queued, otherwise a handle that can be used to
+ *         cancel; note that even if NULL is returned, the callback will be invoked
+ *         (or rather, will already have been invoked)
+ */
+struct GNUNET_DATASTORE_QueueEntry *
+GNUNET_DATASTORE_iterate_zero_anonymity (struct GNUNET_DATASTORE_Handle *h,
+                                         unsigned int queue_priority,
+                                         unsigned int max_queue_size,
+                                         struct GNUNET_TIME_Relative timeout,
+                                         enum GNUNET_BLOCK_Type type,
+                                         GNUNET_DATASTORE_Iterator iter, 
+                                         void *iter_cls);
 
 
 /**
  * Function called to trigger obtaining the next result
- * from the datastore.
+ * from the datastore.  ONLY applies for 'GNUNET_DATASTORE_iterate_*'
+ * calls, not for 'get' calls.  FIXME: how much mixing of iterate
+ * calls with other operations can we permit!?  Should we pass
+ * the 'QueueEntry' instead of the datastore handle here instead?
  * 
  * @param h handle to the datastore
  */
 void
-GNUNET_DATASTORE_get_next (struct GNUNET_DATASTORE_Handle *h);
+GNUNET_DATASTORE_iterate_get_next (struct GNUNET_DATASTORE_Handle *h);
 
 
 /**
@@ -353,32 +383,6 @@ GNUNET_DATASTORE_get_for_replication (struct GNUNET_DATASTORE_Handle *h,
                                       void *iter_cls);
 
 
-/**
- * Get a zero-anonymity value from the datastore.
- *
- * @param h handle to the datastore
- * @param queue_priority ranking of this request in the priority queue
- * @param max_queue_size at what queue size should this request be dropped
- *        (if other requests of higher priority are in the queue)
- * @param timeout how long to wait at most for a response
- * @param type allowed type for the operation
- * @param iter function to call on a random value; it
- *        will be called once with a value (if available)
- *        and always once with a value of NULL.
- * @param iter_cls closure for iter
- * @return NULL if the entry was not queued, otherwise a handle that can be used to
- *         cancel; note that even if NULL is returned, the callback will be invoked
- *         (or rather, will already have been invoked)
- */
-struct GNUNET_DATASTORE_QueueEntry *
-GNUNET_DATASTORE_get_zero_anonymity (struct GNUNET_DATASTORE_Handle *h,
-                                     unsigned int queue_priority,
-                                     unsigned int max_queue_size,
-                                     struct GNUNET_TIME_Relative timeout,
-                                     enum GNUNET_BLOCK_Type type,
-                                     GNUNET_DATASTORE_Iterator iter, 
-                                     void *iter_cls);
-
 
 /**
  * Cancel a datastore operation.  The final callback from the