src/include/gnunet_datastore_plugin.h

   1 /*
   2      This file is part of GNUnet
   3      (C) 2009, 2011 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 include/gnunet_datastore_plugin.h
  23  * @brief API for the database backend plugins.
  24  * @author Christian Grothoff
  25  */
  26 #ifndef PLUGIN_DATASTORE_H
  27 #define PLUGIN_DATASTORE_H
  28
  29 #include "gnunet_block_lib.h"
  30 #include "gnunet_configuration_lib.h"
  31 #include "gnunet_datastore_service.h"
  32 #include "gnunet_statistics_service.h"
  33 #include "gnunet_scheduler_lib.h"
  34
  35
  36 /**
  37  * How many bytes of overhead will we assume per entry
  38  * in any DB (for reservations)?
  39  */
  40 #define GNUNET_DATASTORE_ENTRY_OVERHEAD 256
  41
  42
  43 /**
  44  * Function invoked to notify service of disk utilization
  45  * changes.
  46  *
  47  * @param cls closure
  48  * @param delta change in disk utilization,
  49  *        0 for "reset to empty"
  50  */
  51 typedef void (*DiskUtilizationChange) (void *cls, int delta);
  52
  53
  54 /**
  55  * The datastore service will pass a pointer to a struct
  56  * of this type as the first and only argument to the
  57  * entry point of each datastore plugin.
  58  */
  59 struct GNUNET_DATASTORE_PluginEnvironment
  60 {
  61   /**
  62    * Configuration to use.
  63    */
  64   const struct GNUNET_CONFIGURATION_Handle *cfg;
  65
  66   /**
  67    * Function to call on disk utilization change.
  68    */
  69   DiskUtilizationChange duc;
  70
  71   /**
  72    * Closure.
  73    */
  74   void *cls;
  75
  76 };
  77
  78
  79 /**
  80  * An processor over a set of items stored in the datastore.
  81  *
  82  * @param cls closure
  83  * @param key key for the content
  84  * @param size number of bytes in data
  85  * @param data content stored
  86  * @param type type of the content
  87  * @param priority priority of the content
  88  * @param anonymity anonymity-level for the content
  89  * @param expiration expiration time for the content
  90  * @param uid unique identifier for the datum
  91  *
  92  * @return GNUNET_OK to keep the item
  93  *         GNUNET_NO to delete the item
  94  */
  95 typedef int (*PluginDatumProcessor) (void *cls,
  96                                      const GNUNET_HashCode * key,
  97                                      uint32_t size,
  98                                      const void *data,
  99                                      enum GNUNET_BLOCK_Type type,
 100                                      uint32_t priority,
 101                                      uint32_t anonymity,
 102                                      struct GNUNET_TIME_Absolute
 103                                      expiration, uint64_t uid);
 104
 105 /**
 106  * Get an estimate of how much space the database is
 107  * currently using.
 108  *
 109  * @param cls closure
 110  * @return number of bytes used on disk
 111  */
 112 typedef unsigned long long (*PluginEstimateSize) (void *cls);
 113
 114
 115 /**
 116  * Store an item in the datastore.  If the item is already present,
 117  * the priorities and replication levels are summed up and the higher
 118  * expiration time and lower anonymity level is used.
 119  *
 120  * @param cls closure
 121  * @param key key for the item
 122  * @param size number of bytes in data
 123  * @param data content stored
 124  * @param type type of the content
 125  * @param priority priority of the content
 126  * @param anonymity anonymity-level for the content
 127  * @param replication replication-level for the content
 128  * @param expiration expiration time for the content
 129  * @param msg set to an error message (on failure)
 130  * @return GNUNET_OK on success,
 131  *         GNUNET_SYSERR on failure
 132  */
 133 typedef int (*PluginPut) (void *cls,
 134                           const GNUNET_HashCode * key,
 135                           uint32_t size,
 136                           const void *data,
 137                           enum GNUNET_BLOCK_Type type,
 138                           uint32_t priority,
 139                           uint32_t anonymity,
 140                           uint32_t replication,
 141                           struct GNUNET_TIME_Absolute expiration, char **msg);
 142
 143
 144 /**
 145  * Get one of the results for a particular key in the datastore.
 146  *
 147  * @param cls closure
 148  * @param offset offset of the result (modulo num-results);
 149  *               specific ordering does not matter for the offset
 150  * @param key key to match, never NULL
 151  * @param vhash hash of the value, maybe NULL (to
 152  *        match all values that have the right key).
 153  *        Note that for DBlocks there is no difference
 154  *        betwen key and vhash, but for other blocks
 155  *        there may be!
 156  * @param type entries of which type are relevant?
 157  *     Use 0 for any type.
 158  * @param proc function to call on the matching value;
 159  *        proc should be called with NULL if there is no result
 160  * @param proc_cls closure for proc
 161  */
 162 typedef void (*PluginGetKey) (void *cls,
 163                               uint64_t offset,
 164                               const GNUNET_HashCode * key,
 165                               const GNUNET_HashCode * vhash,
 166                               enum GNUNET_BLOCK_Type type,
 167                               PluginDatumProcessor proc, void *proc_cls);
 168
 169
 170
 171 /**
 172  * Get a random item (additional constraints may apply depending on
 173  * the specific implementation).  Calls 'proc' with all values ZERO or
 174  * NULL if no item applies, otherwise 'proc' is called once and only
 175  * once with an item.
 176  *
 177  * @param cls closure
 178  * @param proc function to call the value (once only).
 179  * @param proc_cls closure for proc
 180  */
 181 typedef void (*PluginGetRandom) (void *cls,
 182                                  PluginDatumProcessor proc, void *proc_cls);
 183
 184
 185 /**
 186  * Update the priority for a particular key in the datastore.  If
 187  * the expiration time in value is different than the time found in
 188  * the datastore, the higher value should be kept.  For the
 189  * anonymity level, the lower value is to be used.  The specified
 190  * priority should be added to the existing priority, ignoring the
 191  * priority in value.
 192  *
 193  * Note that it is possible for multiple values to match this put.
 194  * In that case, all of the respective values are updated.
 195  *
 196  * @param cls closure
 197  * @param uid unique identifier of the datum
 198  * @param delta by how much should the priority
 199  *     change?  If priority + delta < 0 the
 200  *     priority should be set to 0 (never go
 201  *     negative).
 202  * @param expire new expiration time should be the
 203  *     MAX of any existing expiration time and
 204  *     this value
 205  * @param msg set to an error message (on error)
 206  * @return GNUNET_OK on success
 207  */
 208 typedef int (*PluginUpdate) (void *cls,
 209                              uint64_t uid,
 210                              int delta,
 211                              struct GNUNET_TIME_Absolute expire, char **msg);
 212
 213
 214 /**
 215  * Select a single item from the datastore at the specified offset
 216  * (among those applicable).
 217  *
 218  * @param cls closure
 219  * @param offset offset of the result (modulo num-results);
 220  *               specific ordering does not matter for the offset
 221  * @param type entries of which type should be considered?
 222  *        Must not be zero (ANY).
 223  * @param proc function to call on the matching value
 224  * @param proc_cls closure for proc
 225  */
 226 typedef void (*PluginGetType) (void *cls,
 227                                uint64_t offset,
 228                                enum GNUNET_BLOCK_Type type,
 229                                PluginDatumProcessor proc, void *proc_cls);
 230
 231
 232 /**
 233  * Drop database.
 234  *
 235  * @param cls closure
 236  */
 237 typedef void (*PluginDrop) (void *cls);
 238
 239
 240
 241 /**
 242  * Each plugin is required to return a pointer to a struct of this
 243  * type as the return value from its entry point.
 244  */
 245 struct GNUNET_DATASTORE_PluginFunctions
 246 {
 247
 248   /**
 249    * Closure to use for all of the following callbacks
 250    * (except "next_request").
 251    */
 252   void *cls;
 253
 254   /**
 255    * Calculate the current on-disk size of the SQ store.  Estimates
 256    * are fine, if that's the only thing available.
 257    */
 258   PluginEstimateSize estimate_size;
 259
 260   /**
 261    * Function to store an item in the datastore.
 262    */
 263   PluginPut put;
 264
 265   /**
 266    * Update the priority for a particular key in the datastore.  If
 267    * the expiration time in value is different than the time found in
 268    * the datastore, the higher value should be kept.  For the
 269    * anonymity level, the lower value is to be used.  The specified
 270    * priority should be added to the existing priority, ignoring the
 271    * priority in value.
 272    */
 273   PluginUpdate update;
 274
 275   /**
 276    * Get a particular datum matching a given hash from the datastore.
 277    */
 278   PluginGetKey get_key;
 279
 280   /**
 281    * Get datum (of the specified type) with anonymity level zero.
 282    * This function is allowed to ignore the 'offset' argument
 283    * and instead return a random result (with zero anonymity of
 284    * the correct type) if implementing an offset is expensive.
 285    */
 286   PluginGetType get_zero_anonymity;
 287
 288   /**
 289    * Function to get a random item with high replication score from
 290    * the database, lowering the item's replication score.  Returns a
 291    * single random item from those with the highest replication
 292    * counters.  The item's replication counter is decremented by one
 293    * IF it was positive before.
 294    */
 295   PluginGetRandom get_replication;
 296
 297   /**
 298    * Function to get a random expired item or, if none are expired,
 299    * either the oldest entry or one with a low priority (depending
 300    * on what was efficiently implementable).
 301    */
 302   PluginGetRandom get_expiration;
 303
 304   /**
 305    * Delete the database.  The next operation is
 306    * guaranteed to be unloading of the module.
 307    */
 308   PluginDrop drop;
 309
 310 };
 311
 312
 313 #endif