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