src/include/gnunet_datastore_plugin.h

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