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