Merge branch 'master' of gnunet.org:gnunet

[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 a3f8b5f3be5638125bab6e028259ee6aa05eca13..36a3fbec2c9893e445f5018da26221915c59988f 100644 (file)
--- a/src/include/gnunet_datastore_plugin.h
+++ b/src/include/gnunet_datastore_plugin.h
@@ -1,10 +1,10 @@
 /*
      This file is part of GNUnet
 /*
      This file is part of GNUnet

-     (C) 2009, 2011 Christian Grothoff (and other contributing authors)
+     Copyright (C) 2009, 2011 GNUnet e.V.

 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published

-     by the Free Software Foundation; either version 2, or (at your
+     by the Free Software Foundation; either version 3, or (at your

      option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but
      option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but


@@ -14,14 +14,19 @@
 
      You should have received a copy of the GNU General Public License
      along with GNUnet; see the file COPYING.  If not, write to the
 
      You should have received a copy of the GNU General Public License
      along with GNUnet; see the file COPYING.  If not, write to the

-     Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-     Boston, MA 02111-1307, USA.
+     Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+     Boston, MA 02110-1301, USA.

 */
 
 /**
 */
 
 /**

- * @file include/gnunet_datastore_plugin.h
- * @brief API for the database backend plugins.

  * @author Christian Grothoff
  * @author Christian Grothoff

+ *
+ * @file
+ * API for the database backend plugins.
+ *
+ * @defgroup datastore-plugin  Data Store service plugin API
+ * API for the database backend plugins.
+ * @{

  */
 #ifndef PLUGIN_DATASTORE_H
 #define PLUGIN_DATASTORE_H
  */
 #ifndef PLUGIN_DATASTORE_H
 #define PLUGIN_DATASTORE_H


@@ -45,11 +50,12 @@
  * changes.
  *
  * @param cls closure
  * changes.
  *
  * @param cls closure

- * @param delta change in disk utilization, 
+ * @param delta change in disk utilization,

  *        0 for "reset to empty"
  */
  *        0 for "reset to empty"
  */

-typedef void (*DiskUtilizationChange)(void *cls,
-                                     int delta);
+typedef void
+(*GNUNET_DATASTORE_DiskUtilizationChange) (void *cls,
+                                          int delta);

 
 
 /**
 
 
 /**


@@ -67,7 +73,7 @@ struct GNUNET_DATASTORE_PluginEnvironment
   /**
    * Function to call on disk utilization change.
    */
   /**
    * Function to call on disk utilization change.
    */

-  DiskUtilizationChange duc;
+  GNUNET_DATASTORE_DiskUtilizationChange duc;

 
   /**
    * Closure.
 
   /**
    * Closure.


@@ -78,60 +84,66 @@ struct GNUNET_DATASTORE_PluginEnvironment
 
 
 /**
 
 
 /**

- * Function invoked on behalf of a "PluginIterator"
- * asking the database plugin to call the iterator
- * with the next item.
- *
- * @param next_cls whatever argument was given
- *        to the PluginIterator as "next_cls".
- * @param end_it set to GNUNET_YES if we
- *        should terminate the iteration early
- *        (iterator should be still called once more
- *         to signal the end of the iteration).
- */
-typedef void (*PluginNextRequest)(void *next_cls,
-                                 int end_it);
-
-
-/**
- * An iterator over a set of items stored in the datastore.
+ * An processor over a set of items stored in the datastore.

  *
  * @param cls closure
  *
  * @param cls closure

- * @param next_cls closure to pass to the "next" function.

  * @param key key for the content
  * @param size number of bytes in data
  * @param data content stored
  * @param type type of the content
  * @param priority priority of the content
  * @param anonymity anonymity-level for the content
  * @param key key for the content
  * @param size number of bytes in data
  * @param data content stored
  * @param type type of the content
  * @param priority priority of the content
  * @param anonymity anonymity-level for the content

+ * @param replication replication-level for the content

  * @param expiration expiration time for the content
  * @param expiration expiration time for the content

- * @param uid unique identifier for the datum;
- *        maybe 0 if no unique identifier is available
- *
- * @return GNUNET_SYSERR to abort the iteration, GNUNET_OK to continue
- *         (continue on call to "next", of course),
- *         GNUNET_NO to delete the item and continue (if supported)
+ * @param uid unique identifier for the datum
+ * @return #GNUNET_OK to keep the item
+ *         #GNUNET_NO to delete the item

  */
  */

-typedef int (*PluginIterator) (void *cls,
-                              void *next_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 struct 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,
+                         uint64_t uid);
+

 
 /**
  * Get an estimate of how much space the database is
  * currently using.
  *
 
 /**
  * Get an estimate of how much space the database is
  * currently using.
  *

+ * NB: estimate is an output parameter because emscripten cannot handle
+ * returning 64-bit integers from dynamically loaded modules.
+ *

  * @param cls closure
  * @param cls closure

+ * @param estimate location to store estimate

  * @return number of bytes used on disk
  */
  * @return number of bytes used on disk
  */

-typedef unsigned long long (*PluginGetSize) (void *cls);
+typedef void
+(*PluginEstimateSize) (void *cls,
+                      unsigned long long *estimate);
+
+
+/**
+ * Put continuation.
+ *
+ * @param cls closure
+ * @param key key for the item stored
+ * @param size size of the item stored
+ * @param status #GNUNET_OK if inserted, #GNUNET_NO if updated,
+ *        or #GNUNET_SYSERROR if error
+ * @param msg error message on error
+ */
+typedef void
+(*PluginPutCont) (void *cls,
+                 const struct GNUNET_HashCode *key,
+                 uint32_t size,
+                 int status,
+                 const char *msg);

 
 
 /**
 
 
 /**


@@ -141,123 +153,151 @@ typedef unsigned long long (*PluginGetSize) (void *cls);
  *
  * @param cls closure
  * @param key key for the item
  *
  * @param cls closure
  * @param key key for the item

- * @param size number of bytes in data
+ * @param absent true if the key was not found in the bloom filter
+ * @param size number of bytes in @a data

  * @param data content stored
  * @param type type of the content
  * @param priority priority of the content
  * @param anonymity anonymity-level for the content
  * @param replication replication-level for the content
  * @param expiration expiration time for the content
  * @param data content stored
  * @param type type of the content
  * @param priority priority of the content
  * @param anonymity anonymity-level for the content
  * @param replication replication-level for the content
  * @param expiration expiration time for the content

- * @param msg set to an error message (on failure)
- * @return GNUNET_OK on success,
- *         GNUNET_SYSERR on failure
+ * @param cont continuation called with success or failure status
+ * @param cont_cls continuation closure for @a cont
+ */
+typedef void
+(*PluginPut) (void *cls,
+              const struct GNUNET_HashCode *key,
+              bool absent,
+              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,
+              PluginPutCont cont,
+              void *cont_cls);
+
+
+/**
+ * An processor over a set of keys stored in the datastore.
+ *
+ * @param cls closure
+ * @param key key in the data store, if NULL iteration is finished
+ * @param count how many values are stored under this key in the datastore
+ */
+typedef void
+(*PluginKeyProcessor) (void *cls,
+                      const struct GNUNET_HashCode *key,
+                      unsigned int count);
+
+
+/**
+ * Get all of the keys in the datastore.
+ *
+ * @param cls closure
+ * @param proc function to call on each key
+ * @param proc_cls closure for @a proc

  */
  */

-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 void
+(*PluginGetKeys) (void *cls,
+                 PluginKeyProcessor proc,
+                  void *proc_cls);

 
 
 /**
 
 
 /**

- * Iterate over the results for a particular key
- * in the datastore.
+ * Get one of the results for a particular key in the datastore.

  *
  * @param cls closure
  *
  * @param cls closure

+ * @param next_uid return the result with lowest uid >= next_uid
+ * @param random if true, return a random result instead of using next_uid

  * @param key maybe NULL (to match all entries)
  * @param key maybe NULL (to match all entries)

- * @param vhash hash of the value, maybe NULL (to
- *        match all values that have the right key).
- *        Note that for DBlocks there is no difference
- *        betwen key and vhash, but for other blocks
- *        there may be!

  * @param type entries of which type are relevant?
  *     Use 0 for any type.
  * @param type entries of which type are relevant?
  *     Use 0 for any type.

- * @param iter function to call on each matching value; however,
- *        after the first call to "iter", the plugin must wait
- *        until "NextRequest" was called before giving the iterator
- *        the next item; finally, the "iter" should be called once
- *        once with a NULL value at the end ("next_cls" should be NULL
- *        for that last call)
- * @param iter_cls closure for iter
+ * @param proc function to call on the matching value;
+ *        will be called with NULL if nothing matches
+ * @param proc_cls closure for @a proc

  */
  */

-typedef void (*PluginGet) (void *cls,
-                          const GNUNET_HashCode *key,
-                          const GNUNET_HashCode *vhash,
-                          enum GNUNET_BLOCK_Type type,
-                          PluginIterator iter, void *iter_cls);
-
+typedef void
+(*PluginGetKey) (void *cls,
+                 uint64_t next_uid,
+                 bool random,
+                 const struct GNUNET_HashCode *key,
+                 enum GNUNET_BLOCK_Type type,
+                 PluginDatumProcessor proc,
+                 void *proc_cls);

 
 
 /**
 
 
 /**

- * 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.
+ * Remove continuation.

  *
  * @param cls closure
  *
  * @param cls closure

- * @param iter function to call the value (once only).
- * @param iter_cls closure for iter
+ * @param key key for the content removed
+ * @param size number of bytes removed
+ * @param status #GNUNET_OK if removed, #GNUNET_NO if not found,
+ *        or #GNUNET_SYSERROR if error
+ * @param msg error message on error

  */
  */

-typedef void (*PluginRandomGet) (void *cls,
-                                PluginIterator iter, void *iter_cls);
+typedef void
+(*PluginRemoveCont) (void *cls,
+                     const struct GNUNET_HashCode *key,
+                     uint32_t size,
+                     int status,
+                     const char *msg);

 
 
 /**
 
 
 /**

- * Update the priority for a particular key in the datastore.  If
- * the expiration time in value is different than the time found in
- * the datastore, the higher value should be kept.  For the
- * anonymity level, the lower value is to be used.  The specified
- * priority should be added to the existing priority, ignoring the
- * priority in value.
+ * Remove a particular key in the datastore.

  *
  *

- * Note that it is possible for multiple values to match this put.
- * In that case, all of the respective values are updated.
+ * @param cls closure
+ * @param key key for the content
+ * @param size number of bytes in data
+ * @param data content stored
+ * @param cont continuation called with success or failure status
+ * @param cont_cls continuation closure for @a cont
+ */
+typedef void
+(*PluginRemoveKey) (void *cls,
+                    const struct GNUNET_HashCode *key,
+                    uint32_t size,
+                    const void *data,
+                    PluginRemoveCont cont,
+                    void *cont_cls);
+
+
+/**
+ * Get a random item (additional constraints may apply depending on
+ * the specific implementation).  Calls @a proc with all values ZERO or
+ * NULL if no item applies, otherwise @a proc is called once and only
+ * once with an item.

  *
  * @param cls closure
  *
  * @param cls closure

- * @param uid unique identifier of the datum
- * @param delta by how much should the priority
- *     change?  If priority + delta < 0 the
- *     priority should be set to 0 (never go
- *     negative).
- * @param expire new expiration time should be the
- *     MAX of any existing expiration time and
- *     this value
- * @param msg set to an error message (on error)
- * @return GNUNET_OK on success
+ * @param proc function to call the value (once only).
+ * @param proc_cls closure for @a proc

  */
  */

-typedef int (*PluginUpdate) (void *cls,
-                            uint64_t uid,
-                            int delta, 
-                            struct GNUNET_TIME_Absolute expire,
-                            char **msg);
+typedef void
+(*PluginGetRandom) (void *cls,
+                   PluginDatumProcessor proc,
+                   void *proc_cls);

 
 
 /**
 
 
 /**

- * 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'.
+ * Select a single item from the datastore (among those applicable).

  *
  * @param cls closure
  *
  * @param cls closure

+ * @param next_uid return the result with lowest uid >= next_uid

  * @param type entries of which type should be considered?
  * @param type entries of which type should be considered?

- *        Use 0 for any type.
- * @param iter function to call on each matching value; however,
- *        after the first call to "iter", the plugin must wait
- *        until "NextRequest" was called before giving the iterator
- *        the next item; finally, the "iter" should be called once
- *        once with a NULL value at the end ("next_cls" should be NULL
- *        for that last call)
- * @param iter_cls closure for iter
+ *        Must not be zero (ANY).
+ * @param proc function to call on the matching value;
+ *        will be called with NULL if no value matches
+ * @param proc_cls closure for @a proc

  */
  */

-typedef void (*PluginSelector) (void *cls,
-                                enum GNUNET_BLOCK_Type type,
-                                PluginIterator iter,
-                                void *iter_cls);
+typedef void
+(*PluginGetType) (void *cls,
+                  uint64_t next_uid,
+                  enum GNUNET_BLOCK_Type type,
+                  PluginDatumProcessor proc,
+                  void *proc_cls);

 
 
 /**
 
 
 /**


@@ -265,8 +305,8 @@ typedef void (*PluginSelector) (void *cls,
  *
  * @param cls closure
  */
  *
  * @param cls closure
  */

-typedef void (*PluginDrop) (void *cls);
-
+typedef void
+(*PluginDrop) (void *cls);

 
 
 /**
 
 
 /**


@@ -283,10 +323,10 @@ struct GNUNET_DATASTORE_PluginFunctions
   void *cls;
 
   /**
   void *cls;
 
   /**

-   * Get the current on-disk size of the SQ store.  Estimates are
-   * fine, if that's the only thing available.
+   * Calculate the current on-disk size of the SQ store.  Estimates
+   * are fine, if that's the only thing available.

    */
    */

-  PluginGetSize get_size;
+  PluginEstimateSize estimate_size;

 
   /**
    * Function to store an item in the datastore.
 
   /**
    * Function to store an item in the datastore.


@@ -294,64 +334,48 @@ struct GNUNET_DATASTORE_PluginFunctions
   PluginPut put;
 
   /**
   PluginPut put;
 
   /**

-   * Function called by iterators whenever they want the next value;
-   * note that unlike all of the other callbacks, this one does get a
-   * the "next_cls" closure which is usually different from the "cls"
-   * member of this struct!
+   * Get a particular datum matching a given hash from the datastore.

    */
    */

-  PluginNextRequest next_request;
+  PluginGetKey get_key;

 
   /**
 
   /**

-   * Function to iterate over the results for a particular key
-   * in the datastore.
+   * Get datum (of the specified type) with anonymity level zero.

    */
    */

-  PluginGet get;
+  PluginGetType get_zero_anonymity;

 
   /**
    * Function to get a random item with high replication score from
    * the database, lowering the item's replication score.  Returns a
 
   /**
    * Function to get a random item with high replication score from
    * 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.
+   * single 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;
+  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).

    */
    */

-  PluginRandomGet expiration_get;
+  PluginGetRandom get_expiration;

 
   /**
 
   /**

-   * Update the priority for a particular key in the datastore.  If
-   * the expiration time in value is different than the time found in
-   * the datastore, the higher value should be kept.  For the
-   * anonymity level, the lower value is to be used.  The specified
-   * priority should be added to the existing priority, ignoring the
-   * priority in value.
+   * Delete the database.  The next operation is
+   * guaranteed to be unloading of the module.

    */
    */

-  PluginUpdate update;
+  PluginDrop drop;

 
   /**
 
   /**

-   * Iterate over content with anonymity level zero.
+   * Iterate over all keys in the database.

    */
    */

-  PluginSelector iter_zero_anonymity;
+  PluginGetKeys get_keys;

 
   /**
 
   /**

-   * Iterate over all the items in the datastore
-   * as fast as possible in a single transaction
-   * (can lock datastore while this happens, focus
-   * is on doing it fast).
+   * Function to remove an item from the database.

    */
    */

-  PluginSelector iter_all_now;
-
-  /**
-   * Delete the database.  The next operation is
-   * guaranteed to be unloading of the module.
-   */
-  PluginDrop drop;
-
+  PluginRemoveKey remove_key;

 };
 
 };
 

-

 #endif
 #endif

+
+/** @} */  /* end of group */