/*
This file is part of GNUnet
- (C) 2009 Christian Grothoff (and other contributing authors)
+ (C) 2009, 2011 Christian Grothoff (and other contributing authors)
GNUnet is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published
*/
/**
- * @file datastore/gnunet_datastore_plugin.h
+ * @file include/gnunet_datastore_plugin.h
* @brief API for the database backend plugins.
* @author Christian Grothoff
*/
/**
* Store an item in the datastore. If the item is already present,
- * the priorities are summed up and the higher expiration time and
- * lower anonymity level is used.
+ * the priorities and replication levels are summed up and the higher
+ * expiration time and lower anonymity level is used.
*
* @param cls closure
* @param key key for the item
* @param type type of the content
* @param priority priority of the content
* @param anonymity anonymity-level for the content
+ * @param replication replication-level for the content
* @param expiration expiration time for the content
* @param msg set to an error message (on failure)
- * @return GNUNET_OK on success, GNUNET_NO if the content
- * was already present (and may have been updated);
+ * @return GNUNET_OK on success,
* GNUNET_SYSERR on failure
*/
typedef int (*PluginPut) (void *cls,
enum GNUNET_BLOCK_Type type,
uint32_t priority,
uint32_t anonymity,
+ uint32_t replication,
struct GNUNET_TIME_Absolute expiration,
- char **msg);
+ char **msg);
/**
* in the datastore.
*
* @param cls closure
- * @param key maybe NULL (to match all entries)
+ * @param key key to match, never NULL
* @param vhash hash of the value, maybe NULL (to
* match all values that have the right key).
* Note that for DBlocks there is no difference
* @param iter_cls closure for iter
*/
typedef void (*PluginGet) (void *cls,
- const GNUNET_HashCode * key,
- const GNUNET_HashCode * vhash,
+ const GNUNET_HashCode *key,
+ const GNUNET_HashCode *vhash,
enum GNUNET_BLOCK_Type type,
PluginIterator iter, void *iter_cls);
+
+/**
+ * Get a random item (additional constraints may apply depending on
+ * the specific implementation). Calls 'iter' with all values ZERO or
+ * NULL if no item applies, otherwise 'iter' is called once and only
+ * once with an item, with the 'next_cls' argument being NULL.
+ *
+ * @param cls closure
+ * @param iter function to call the value (once only).
+ * @param iter_cls closure for iter
+ */
+typedef void (*PluginRandomGet) (void *cls,
+ PluginIterator iter, void *iter_cls);
+
+
/**
* Update the priority for a particular key in the datastore. If
* the expiration time in value is different than the time found in
*/
typedef int (*PluginUpdate) (void *cls,
uint64_t uid,
- int delta, struct GNUNET_TIME_Absolute expire,
+ int delta,
+ struct GNUNET_TIME_Absolute expire,
char **msg);
/**
- * Select a subset of the items in the datastore and call
- * the given iterator for each of them.
+ * Select a subset of the items in the datastore and call the given
+ * iterator for the first item; then allow getting more items by
+ * calling the 'next_request' callback with the given 'next_cls'
+ * argument passed to 'iter'.
*
* @param cls closure
* @param type entries of which type should be considered?
- * Use 0 for any type.
+ * Myst not be zero (ANY).
* @param iter function to call on each matching value; however,
* after the first call to "iter", the plugin must wait
* until "NextRequest" was called before giving the iterator
PluginIterator iter,
void *iter_cls);
+
/**
* Drop database.
*
*/
PluginPut put;
- /**
- * Function called by iterators whenever they want the next value;
- * note that unlike all of the other callbacks, this one does get a
- * the "next_cls" closure which is usually different from the "cls"
- * member of this struct!
- */
- PluginNextRequest next_request;
-
- /**
- * Function to iterate over the results for a particular key
- * in the datastore.
- */
- PluginGet get;
-
/**
* Update the priority for a particular key in the datastore. If
* the expiration time in value is different than the time found in
PluginUpdate update;
/**
- * Iterate over the items in the datastore in ascending
- * order of priority.
+ * Function called by iterators whenever they want the next value;
+ * note that unlike all of the other callbacks, this one does get a
+ * the "next_cls" closure which is usually different from the "cls"
+ * member of this struct!
*/
- PluginSelector iter_low_priority;
+ PluginNextRequest next_request;
/**
- * Iterate over content with anonymity zero.
+ * Function to iterate over the results for a particular key
+ * in the datastore.
*/
- PluginSelector iter_zero_anonymity;
+ PluginGet get;
/**
- * Iterate over the items in the datastore in ascending order of
- * expiration time.
+ * Iterate over content with anonymity level zero.
*/
- PluginSelector iter_ascending_expiration;
+ PluginSelector iter_zero_anonymity;
/**
- * Iterate over the items in the datastore in migration
- * order. Call the given function on the next item only
- * (and then signal 'end' with a second call). This is
- * a significant difference from all the other iterators!
+ * Function to get a random item with high replication score from
+ * the database, lowering the item's replication score. Returns a
+ * single random item from those with the highest replication
+ * counters. The item's replication counter is decremented by one
+ * IF it was positive before.
*/
- PluginSelector iter_migration_order;
+ PluginRandomGet replication_get;
/**
- * Iterate over all the items in the datastore
- * as fast as possible in a single transaction
- * (can lock datastore while this happens, focus
- * is on doing it fast).
+ * Function to get a random expired item or, if none are expired, one
+ * with a low priority.
*/
- PluginSelector iter_all_now;
+ PluginRandomGet expiration_get;
/**
* Delete the database. The next operation is
projects / oweals / gnunet.git / blobdiff