(no commit message)

[oweals/gnunet.git] / src / include / gnunet_datastore_plugin.h

diff --git a/src/include/gnunet_datastore_plugin.h b/src/include/gnunet_datastore_plugin.h
index 4d717996d4f30ce8fd76647c4c6fb5dd7d2bb641..fb1dff51d217b167b4fa36661a72f18b683e1d30 100644 (file)
--- a/src/include/gnunet_datastore_plugin.h
+++ b/src/include/gnunet_datastore_plugin.h
@@ -45,11 +45,10 @@
  * changes.
  *
  * @param cls closure
- * @param delta change in disk utilization, 
+ * @param delta change in disk utilization,
  *        0 for "reset to empty"
  */
-typedef void (*DiskUtilizationChange)(void *cls,
-                                     int delta);
+typedef void (*DiskUtilizationChange) (void *cls, int delta);
 
 
 /**
@@ -93,16 +92,12 @@ struct GNUNET_DATASTORE_PluginEnvironment
  * @return GNUNET_OK to keep the item
  *         GNUNET_NO to delete the item
  */
-typedef int (*PluginDatumProcessor) (void *cls,
-                                    const GNUNET_HashCode * key,
-                                    uint32_t size,
-                                    const void *data,
-                                    enum GNUNET_BLOCK_Type type,
-                                    uint32_t priority,
-                                    uint32_t anonymity,
-                                    struct GNUNET_TIME_Absolute
-                                    expiration, 
-                                    uint64_t uid);
+typedef int (*PluginDatumProcessor) (void *cls, const GNUNET_HashCode * key,
+                                     uint32_t size, const void *data,
+                                     enum GNUNET_BLOCK_Type type,
+                                     uint32_t priority, uint32_t anonymity,
+                                     struct GNUNET_TIME_Absolute expiration,
+                                     uint64_t uid);
 
 /**
  * Get an estimate of how much space the database is
@@ -132,23 +127,18 @@ typedef unsigned long long (*PluginEstimateSize) (void *cls);
  * @return GNUNET_OK on success,
  *         GNUNET_SYSERR on failure
  */
-typedef int (*PluginPut) (void *cls,
-                         const GNUNET_HashCode * key,
-                         uint32_t size,
-                         const void *data,
-                         enum GNUNET_BLOCK_Type type,
-                         uint32_t priority,
-                         uint32_t anonymity,
-                         uint32_t replication,
-                         struct GNUNET_TIME_Absolute expiration,
-                         char **msg);
+typedef int (*PluginPut) (void *cls, const GNUNET_HashCode * key, uint32_t size,
+                          const void *data, enum GNUNET_BLOCK_Type type,
+                          uint32_t priority, uint32_t anonymity,
+                          uint32_t replication,
+                          struct GNUNET_TIME_Absolute expiration, char **msg);
 
 
 /**
  * Get one of the results for a particular key in the datastore.
  *
  * @param cls closure
- * @param offset offset of the result (mod #num-results); 
+ * @param offset offset of the result (modulo num-results);
  *               specific ordering does not matter for the offset
  * @param key key to match, never NULL
  * @param vhash hash of the value, maybe NULL (to
@@ -158,16 +148,15 @@ typedef int (*PluginPut) (void *cls,
  *        there may be!
  * @param type entries of which type are relevant?
  *     Use 0 for any type.
- * @param proc function to call on the matching value; 
+ * @param proc function to call on the matching value;
  *        proc should be called with NULL if there is no result
  * @param proc_cls closure for proc
  */
-typedef void (*PluginGetKey) (void *cls,
-                             uint64_t offset,
-                             const GNUNET_HashCode *key,
-                             const GNUNET_HashCode *vhash,
-                             enum GNUNET_BLOCK_Type type,
-                             PluginDatumProcessor proc, void *proc_cls);
+typedef void (*PluginGetKey) (void *cls, uint64_t offset,
+                              const GNUNET_HashCode * key,
+                              const GNUNET_HashCode * vhash,
+                              enum GNUNET_BLOCK_Type type,
+                              PluginDatumProcessor proc, void *proc_cls);
 
 
 
@@ -175,14 +164,14 @@ typedef void (*PluginGetKey) (void *cls,
  * Get a random item (additional constraints may apply depending on
  * the specific implementation).  Calls 'proc' with all values ZERO or
  * NULL if no item applies, otherwise 'proc' is called once and only
- * once with an item, with the 'next_cls' argument being NULL.
+ * once with an item.
  *
  * @param cls closure
  * @param proc function to call the value (once only).
  * @param proc_cls closure for proc
  */
-typedef void (*PluginGetRandom) (void *cls,
-                                PluginDatumProcessor proc, void *proc_cls);
+typedef void (*PluginGetRandom) (void *cls, PluginDatumProcessor proc,
+                                 void *proc_cls);
 
 
 /**
@@ -208,30 +197,25 @@ typedef void (*PluginGetRandom) (void *cls,
  * @param msg set to an error message (on error)
  * @return GNUNET_OK on success
  */
-typedef int (*PluginUpdate) (void *cls,
-                            uint64_t uid,
-                            int delta, 
-                            struct GNUNET_TIME_Absolute expire,
-                            char **msg);
+typedef int (*PluginUpdate) (void *cls, uint64_t uid, int delta,
+                             struct GNUNET_TIME_Absolute expire, char **msg);
 
 
 /**
  * Select a single item from the datastore at the specified offset
- * (among those applicable). 
+ * (among those applicable).
  *
  * @param cls closure
- * @param offset offset of the result (mod #num-results); 
+ * @param offset offset of the result (modulo num-results);
  *               specific ordering does not matter for the offset
  * @param type entries of which type should be considered?
  *        Must not be zero (ANY).
  * @param proc function to call on the matching value
  * @param proc_cls closure for proc
  */
-typedef void (*PluginGetType) (void *cls,
-                              uint64_t offset,
-                              enum GNUNET_BLOCK_Type type,
-                              PluginDatumProcessor proc,
-                              void *proc_cls);
+typedef void (*PluginGetType) (void *cls, uint64_t offset,
+                               enum GNUNET_BLOCK_Type type,
+                               PluginDatumProcessor proc, void *proc_cls);
 
 
 /**
@@ -284,6 +268,9 @@ struct GNUNET_DATASTORE_PluginFunctions
 
   /**
    * Get datum (of the specified type) with anonymity level zero.
+   * This function is allowed to ignore the 'offset' argument
+   * and instead return a random result (with zero anonymity of
+   * the correct type) if implementing an offset is expensive.
    */
   PluginGetType get_zero_anonymity;
 
@@ -297,8 +284,9 @@ struct GNUNET_DATASTORE_PluginFunctions
   PluginGetRandom get_replication;
 
   /**
-   * Function to get a random expired item or, if none are expired, one
-   * with a low priority.
+   * Function to get a random expired item or, if none are expired,
+   * either the oldest entry or one with a low priority (depending
+   * on what was efficiently implementable).
    */
   PluginGetRandom get_expiration;