src/include/gnunet_datastore_plugin.h

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