src/datastore/plugin_datastore.h

   1 /*
   2      This file is part of GNUnet
   3      (C) 2009 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 2, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file datastore/plugin_datastore.h
  23  * @brief API for the database backend plugins.
  24  * @author Christian Grothoff
  25  *
  26  * TODO:
  27  * - consider defining enumeration or at least typedef
  28  *   for the type of "type" (instead of using uint32_t)
  29  */
  30 #ifndef PLUGIN_DATASTORE_H
  31 #define PLUGIN_DATASTORE_H
  32
  33 #include "gnunet_configuration_lib.h"
  34 #include "gnunet_scheduler_lib.h"
  35 #include "gnunet_datastore_service.h"
  36
  37 /**
  38  * The datastore service will pass a pointer to a struct
  39  * of this type as the first and only argument to the
  40  * entry point of each datastore plugin.
  41  */
  42 struct GNUNET_DATASTORE_PluginEnvironment
  43 {
  44   /**
  45    * Configuration to use.
  46    */
  47   struct GNUNET_CONFIGURATION_Handle *cfg;
  48
  49   /**
  50    * Scheduler to use.
  51    */
  52   struct GNUNET_SCHEDULER_Handle *sched;
  53
  54 };
  55
  56
  57 /**
  58  * Get an estimate of how much space the database is
  59  * currently using.
  60  * @return number of bytes used on disk
  61  */
  62 typedef unsigned long long (*GNUNET_DATASTORE_GetSize) (void *cls);
  63
  64
  65 /**
  66  * Store an item in the datastore.
  67  *
  68  * @param cls closure
  69  * @param key key for the item
  70  * @param size number of bytes in data
  71  * @param data content stored
  72  * @param type type of the content
  73  * @param priority priority of the content
  74  * @param anonymity anonymity-level for the content
  75  * @param expiration expiration time for the content
  76  * @param msg set to an error message (on failure)
  77  * @return GNUNET_OK on success, GNUNET_SYSERR on failure
  78  */
  79 typedef int
  80   (*GNUNET_DATASTORE_Put) (void *cls,
  81                            const GNUNET_HashCode * key,
  82                            uint32_t size,
  83                            const void *data,
  84                            uint32_t type,
  85                            uint32_t priority,
  86                            uint32_t anonymity,
  87                            struct GNUNET_TIME_Absolute expiration,
  88                            char **msg);
  89
  90
  91 /**
  92  * Iterate over the results for a particular key
  93  * in the datastore.
  94  *
  95  * @param cls closure
  96  * @param key maybe NULL (to match all entries)
  97  * @param vhash hash of the value, maybe NULL (to
  98  *        match all values that have the right key).
  99  *        Note that for DBlocks there is no difference
 100  *        betwen key and vhash, but for other blocks
 101  *        there may be!
 102  * @param type entries of which type are relevant?
 103  *     Use 0 for any type.
 104  * @param iter function to call on each matching value;
 105  *        will be called once with a NULL value at the end
 106  * @param iter_cls closure for iter
 107  */
 108 typedef void
 109   (*GNUNET_DATASTORE_Get) (void *cls,
 110                            const GNUNET_HashCode * key,
 111                            const GNUNET_HashCode * vhash,
 112                            uint32_t type,
 113                            GNUNET_DATASTORE_Iterator iter, void *iter_cls);
 114
 115
 116 /**
 117  * Update the priority for a particular key in the datastore.  If
 118  * the expiration time in value is different than the time found in
 119  * the datastore, the higher value should be kept.  For the
 120  * anonymity level, the lower value is to be used.  The specified
 121  * priority should be added to the existing priority, ignoring the
 122  * priority in value.
 123  *
 124  * Note that it is possible for multiple values to match this put.
 125  * In that case, all of the respective values are updated.
 126  *
 127  * @param uid unique identifier of the datum
 128  * @param delta by how much should the priority
 129  *     change?  If priority + delta < 0 the
 130  *     priority should be set to 0 (never go
 131  *     negative).
 132  * @param expire new expiration time should be the
 133  *     MAX of any existing expiration time and
 134  *     this value
 135  * @param msg set to an error message (on error)
 136  * @return GNUNET_OK on success
 137  */
 138 typedef int
 139   (*GNUNET_DATASTORE_Update) (void *cls,
 140                               unsigned long long uid,
 141                               int delta, struct GNUNET_TIME_Absolute expire,
 142                               char **msg);
 143
 144
 145 /**
 146  * Select a subset of the items in the datastore and call
 147  * the given iterator for each of them.
 148  *
 149  * @param type entries of which type should be considered?
 150  *        Use 0 for any type.
 151  * @param iter function to call on each matching value;
 152  *        will be called once with a NULL value at the end
 153  * @param iter_cls closure for iter
 154  */
 155 typedef void
 156   (*GNUNET_DATASTORE_Selector) (void *cls,
 157                                 uint32_t type,
 158                                 GNUNET_DATASTORE_Iterator iter,
 159                                 void *iter_cls);
 160
 161 /**
 162  * Drop database.
 163  */
 164 typedef void (*GNUNET_DATASTORE_Drop) (void *cls);
 165
 166
 167
 168 /**
 169  * Each plugin is required to return a pointer to a struct of this
 170  * type as the return value from its entry point.
 171  */
 172 struct GNUNET_DATASTORE_PluginFunctions
 173 {
 174
 175   /**
 176    * Closure to use for all of the following callbacks.
 177    */
 178   void *cls;
 179
 180   /**
 181    * Get the current on-disk size of the SQ store.  Estimates are
 182    * fine, if that's the only thing available.
 183    */
 184   GNUNET_DATASTORE_GetSize get_size;
 185
 186   /**
 187    * Function to store an item in the datastore.
 188    */
 189   GNUNET_DATASTORE_Put put;
 190
 191   /**
 192    * Function to iterate over the results for a particular key
 193    * in the datastore.
 194    */
 195   GNUNET_DATASTORE_Get get;
 196
 197   /**
 198    * Update the priority for a particular key in the datastore.  If
 199    * the expiration time in value is different than the time found in
 200    * the datastore, the higher value should be kept.  For the
 201    * anonymity level, the lower value is to be used.  The specified
 202    * priority should be added to the existing priority, ignoring the
 203    * priority in value.
 204    */
 205   GNUNET_DATASTORE_Update update;
 206
 207   /**
 208    * Iterate over the items in the datastore in ascending
 209    * order of priority.
 210    */
 211   GNUNET_DATASTORE_Selector iter_low_priority;
 212
 213   /**
 214    * Iterate over content with anonymity zero.
 215    */
 216   GNUNET_DATASTORE_Selector iter_zero_anonymity;
 217
 218   /**
 219    * Iterate over the items in the datastore in ascending order of
 220    * expiration time.
 221    */
 222   GNUNET_DATASTORE_Selector iter_ascending_expiration;
 223
 224   /**
 225    * Iterate over the items in the datastore in migration
 226    * order.  Call the given function on the next item only
 227    * (and then signal 'end' with a second call).  This is
 228    * a significant difference from all the other iterators!
 229    */
 230   GNUNET_DATASTORE_Selector iter_migration_order;
 231
 232   /**
 233    * Iterate over all the items in the datastore
 234    * as fast as possible in a single transaction
 235    * (can lock datastore while this happens, focus
 236    * is on doing it fast).
 237    */
 238   GNUNET_DATASTORE_Selector iter_all_now;
 239
 240   /**
 241    * Delete the database.  The next operation is
 242    * guaranteed to be unloading of the module.
 243    */
 244   GNUNET_DATASTORE_Drop drop;
 245
 246 };
 247
 248
 249 #endif