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 it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your 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      Affero General Public License for more details.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 */
  18
  19 /**
  20  * @author Christian Grothoff
  21  *
  22  * @file
  23  * API for the database backend plugins.
  24  *
  25  * @defgroup datastore-plugin  Data Store service plugin API
  26  * API for the database backend plugins.
  27  * @{
  28  */
  29 #ifndef PLUGIN_DATASTORE_H
  30 #define PLUGIN_DATASTORE_H
  31
  32 #include "gnunet_block_lib.h"
  33 #include "gnunet_configuration_lib.h"
  34 #include "gnunet_datastore_service.h"
  35 #include "gnunet_statistics_service.h"
  36 #include "gnunet_scheduler_lib.h"
  37
  38
  39 /**
  40  * How many bytes of overhead will we assume per entry
  41  * in any DB (for reservations)?
  42  */
  43 #define GNUNET_DATASTORE_ENTRY_OVERHEAD 256
  44
  45
  46 /**
  47  * Function invoked to notify service of disk utilization
  48  * changes.
  49  *
  50  * @param cls closure
  51  * @param delta change in disk utilization,
  52  *        0 for "reset to empty"
  53  */
  54 typedef void
  55 (*GNUNET_DATASTORE_DiskUtilizationChange) (void *cls,
  56                                            int delta);
  57
  58
  59 /**
  60  * The datastore service will pass a pointer to a struct
  61  * of this type as the first and only argument to the
  62  * entry point of each datastore plugin.
  63  */
  64 struct GNUNET_DATASTORE_PluginEnvironment
  65 {
  66   /**
  67    * Configuration to use.
  68    */
  69   const struct GNUNET_CONFIGURATION_Handle *cfg;
  70
  71   /**
  72    * Function to call on disk utilization change.
  73    */
  74   GNUNET_DATASTORE_DiskUtilizationChange duc;
  75
  76   /**
  77    * Closure.
  78    */
  79   void *cls;
  80
  81 };
  82
  83
  84 /**
  85  * An processor over a set of items stored in the datastore.
  86  *
  87  * @param cls closure
  88  * @param key key for the content
  89  * @param size number of bytes in data
  90  * @param data content stored
  91  * @param type type of the content
  92  * @param priority priority of the content
  93  * @param anonymity anonymity-level for the content
  94  * @param replication replication-level for the content
  95  * @param expiration expiration time for the content
  96  * @param uid unique identifier for the datum
  97  * @return #GNUNET_OK to keep the item
  98  *         #GNUNET_NO to delete the item
  99  */
 100 typedef int
 101 (*PluginDatumProcessor) (void *cls,
 102                          const struct GNUNET_HashCode *key,
 103                          uint32_t size,
 104                          const void *data,
 105                          enum GNUNET_BLOCK_Type type,
 106                          uint32_t priority,
 107                          uint32_t anonymity,
 108                          uint32_t replication,
 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 if inserted, #GNUNET_NO if updated,
 136  *        or #GNUNET_SYSERROR if error
 137  * @param msg error message on error
 138  */
 139 typedef void
 140 (*PluginPutCont) (void *cls,
 141                   const struct GNUNET_HashCode *key,
 142                   uint32_t size,
 143                   int status,
 144                   const char *msg);
 145
 146
 147 /**
 148  * Store an item in the datastore.  If the item is already present,
 149  * the priorities and replication levels are summed up and the higher
 150  * expiration time and lower anonymity level is used.
 151  *
 152  * @param cls closure
 153  * @param key key for the item
 154  * @param absent true if the key was not found in the bloom filter
 155  * @param size number of bytes in @a data
 156  * @param data content stored
 157  * @param type type of the content
 158  * @param priority priority of the content
 159  * @param anonymity anonymity-level for the content
 160  * @param replication replication-level for the content
 161  * @param expiration expiration time for the content
 162  * @param cont continuation called with success or failure status
 163  * @param cont_cls continuation closure for @a cont
 164  */
 165 typedef void
 166 (*PluginPut) (void *cls,
 167               const struct GNUNET_HashCode *key,
 168               bool absent,
 169               uint32_t size,
 170               const void *data,
 171               enum GNUNET_BLOCK_Type type,
 172               uint32_t priority,
 173               uint32_t anonymity,
 174               uint32_t replication,
 175               struct GNUNET_TIME_Absolute expiration,
 176               PluginPutCont cont,
 177               void *cont_cls);
 178
 179
 180 /**
 181  * An processor over a set of keys stored in the datastore.
 182  *
 183  * @param cls closure
 184  * @param key key in the data store, if NULL iteration is finished
 185  * @param count how many values are stored under this key in the datastore
 186  */
 187 typedef void
 188 (*PluginKeyProcessor) (void *cls,
 189                        const struct GNUNET_HashCode *key,
 190                        unsigned int count);
 191
 192
 193 /**
 194  * Get all of the keys in the datastore.
 195  *
 196  * @param cls closure
 197  * @param proc function to call on each key
 198  * @param proc_cls closure for @a proc
 199  */
 200 typedef void
 201 (*PluginGetKeys) (void *cls,
 202                   PluginKeyProcessor proc,
 203                   void *proc_cls);
 204
 205
 206 /**
 207  * Get one of the results for a particular key in the datastore.
 208  *
 209  * @param cls closure
 210  * @param next_uid return the result with lowest uid >= next_uid
 211  * @param random if true, return a random result instead of using next_uid
 212  * @param key maybe NULL (to match all entries)
 213  * @param type entries of which type are relevant?
 214  *     Use 0 for any type.
 215  * @param proc function to call on the matching value;
 216  *        will be called with NULL if nothing matches
 217  * @param proc_cls closure for @a proc
 218  */
 219 typedef void
 220 (*PluginGetKey) (void *cls,
 221                  uint64_t next_uid,
 222                  bool random,
 223                  const struct GNUNET_HashCode *key,
 224                  enum GNUNET_BLOCK_Type type,
 225                  PluginDatumProcessor proc,
 226                  void *proc_cls);
 227
 228
 229 /**
 230  * Remove continuation.
 231  *
 232  * @param cls closure
 233  * @param key key for the content removed
 234  * @param size number of bytes removed
 235  * @param status #GNUNET_OK if removed, #GNUNET_NO if not found,
 236  *        or #GNUNET_SYSERROR if error
 237  * @param msg error message on error
 238  */
 239 typedef void
 240 (*PluginRemoveCont) (void *cls,
 241                      const struct GNUNET_HashCode *key,
 242                      uint32_t size,
 243                      int status,
 244                      const char *msg);
 245
 246
 247 /**
 248  * Remove a particular key in the datastore.
 249  *
 250  * @param cls closure
 251  * @param key key for the content
 252  * @param size number of bytes in data
 253  * @param data content stored
 254  * @param cont continuation called with success or failure status
 255  * @param cont_cls continuation closure for @a cont
 256  */
 257 typedef void
 258 (*PluginRemoveKey) (void *cls,
 259                     const struct GNUNET_HashCode *key,
 260                     uint32_t size,
 261                     const void *data,
 262                     PluginRemoveCont cont,
 263                     void *cont_cls);
 264
 265
 266 /**
 267  * Get a random item (additional constraints may apply depending on
 268  * the specific implementation).  Calls @a proc with all values ZERO or
 269  * NULL if no item applies, otherwise @a proc is called once and only
 270  * once with an item.
 271  *
 272  * @param cls closure
 273  * @param proc function to call the value (once only).
 274  * @param proc_cls closure for @a proc
 275  */
 276 typedef void
 277 (*PluginGetRandom) (void *cls,
 278                     PluginDatumProcessor proc,
 279                     void *proc_cls);
 280
 281
 282 /**
 283  * Select a single item from the datastore (among those applicable).
 284  *
 285  * @param cls closure
 286  * @param next_uid return the result with lowest uid >= next_uid
 287  * @param type entries of which type should be considered?
 288  *        Must not be zero (ANY).
 289  * @param proc function to call on the matching value;
 290  *        will be called with NULL if no value matches
 291  * @param proc_cls closure for @a proc
 292  */
 293 typedef void
 294 (*PluginGetType) (void *cls,
 295                   uint64_t next_uid,
 296                   enum GNUNET_BLOCK_Type type,
 297                   PluginDatumProcessor proc,
 298                   void *proc_cls);
 299
 300
 301 /**
 302  * Drop database.
 303  *
 304  * @param cls closure
 305  */
 306 typedef void
 307 (*PluginDrop) (void *cls);
 308
 309
 310 /**
 311  * Each plugin is required to return a pointer to a struct of this
 312  * type as the return value from its entry point.
 313  */
 314 struct GNUNET_DATASTORE_PluginFunctions
 315 {
 316
 317   /**
 318    * Closure to use for all of the following callbacks
 319    * (except "next_request").
 320    */
 321   void *cls;
 322
 323   /**
 324    * Calculate the current on-disk size of the SQ store.  Estimates
 325    * are fine, if that's the only thing available.
 326    */
 327   PluginEstimateSize estimate_size;
 328
 329   /**
 330    * Function to store an item in the datastore.
 331    */
 332   PluginPut put;
 333
 334   /**
 335    * Get a particular datum matching a given hash from the datastore.
 336    */
 337   PluginGetKey get_key;
 338
 339   /**
 340    * Get datum (of the specified type) with anonymity level zero.
 341    */
 342   PluginGetType get_zero_anonymity;
 343
 344   /**
 345    * Function to get a random item with high replication score from
 346    * the database, lowering the item's replication score.  Returns a
 347    * single random item from those with the highest replication
 348    * counters.  The item's replication counter is decremented by one
 349    * IF it was positive before.
 350    */
 351   PluginGetRandom get_replication;
 352
 353   /**
 354    * Function to get a random expired item or, if none are expired,
 355    * either the oldest entry or one with a low priority (depending
 356    * on what was efficiently implementable).
 357    */
 358   PluginGetRandom get_expiration;
 359
 360   /**
 361    * Delete the database.  The next operation is
 362    * guaranteed to be unloading of the module.
 363    */
 364   PluginDrop drop;
 365
 366   /**
 367    * Iterate over all keys in the database.
 368    */
 369   PluginGetKeys get_keys;
 370
 371   /**
 372    * Function to remove an item from the database.
 373    */
 374   PluginRemoveKey remove_key;
 375 };
 376
 377 #endif
 378
 379 /** @} */  /* end of group */