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