X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_datastore_plugin.h;h=36a3fbec2c9893e445f5018da26221915c59988f;hb=ca391c48238c36462ca11be9299cc7c9a09e6bbe;hp=a3f8b5f3be5638125bab6e028259ee6aa05eca13;hpb=52384a51f64fdfdb380cb84c705e9f06e9e3ea40;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_datastore_plugin.h b/src/include/gnunet_datastore_plugin.h index a3f8b5f3b..36a3fbec2 100644 --- a/src/include/gnunet_datastore_plugin.h +++ b/src/include/gnunet_datastore_plugin.h @@ -1,10 +1,10 @@ /* This file is part of GNUnet - (C) 2009, 2011 Christian Grothoff (and other contributing authors) + Copyright (C) 2009, 2011 GNUnet e.V. GNUnet is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 2, or (at your + by the Free Software Foundation; either version 3, or (at your option) any later version. GNUnet is distributed in the hope that it will be useful, but @@ -14,14 +14,19 @@ You should have received a copy of the GNU General Public License along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. + Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. */ /** - * @file include/gnunet_datastore_plugin.h - * @brief API for the database backend plugins. * @author Christian Grothoff + * + * @file + * API for the database backend plugins. + * + * @defgroup datastore-plugin Data Store service plugin API + * API for the database backend plugins. + * @{ */ #ifndef PLUGIN_DATASTORE_H #define PLUGIN_DATASTORE_H @@ -45,11 +50,12 @@ * changes. * * @param cls closure - * @param delta change in disk utilization, + * @param delta change in disk utilization, * 0 for "reset to empty" */ -typedef void (*DiskUtilizationChange)(void *cls, - int delta); +typedef void +(*GNUNET_DATASTORE_DiskUtilizationChange) (void *cls, + int delta); /** @@ -67,7 +73,7 @@ struct GNUNET_DATASTORE_PluginEnvironment /** * Function to call on disk utilization change. */ - DiskUtilizationChange duc; + GNUNET_DATASTORE_DiskUtilizationChange duc; /** * Closure. @@ -78,60 +84,66 @@ struct GNUNET_DATASTORE_PluginEnvironment /** - * Function invoked on behalf of a "PluginIterator" - * asking the database plugin to call the iterator - * with the next item. - * - * @param next_cls whatever argument was given - * to the PluginIterator as "next_cls". - * @param end_it set to GNUNET_YES if we - * should terminate the iteration early - * (iterator should be still called once more - * to signal the end of the iteration). - */ -typedef void (*PluginNextRequest)(void *next_cls, - int end_it); - - -/** - * An iterator over a set of items stored in the datastore. + * An processor over a set of items stored in the datastore. * * @param cls closure - * @param next_cls closure to pass to the "next" function. * @param key key for the content * @param size number of bytes in data * @param data content stored * @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 uid unique identifier for the datum; - * maybe 0 if no unique identifier is available - * - * @return GNUNET_SYSERR to abort the iteration, GNUNET_OK to continue - * (continue on call to "next", of course), - * GNUNET_NO to delete the item and continue (if supported) + * @param uid unique identifier for the datum + * @return #GNUNET_OK to keep the item + * #GNUNET_NO to delete the item */ -typedef int (*PluginIterator) (void *cls, - void *next_cls, - const GNUNET_HashCode * key, - uint32_t size, - const void *data, - enum GNUNET_BLOCK_Type type, - uint32_t priority, - uint32_t anonymity, - struct GNUNET_TIME_Absolute - expiration, - uint64_t uid); +typedef int +(*PluginDatumProcessor) (void *cls, + const struct GNUNET_HashCode *key, + uint32_t size, + const void *data, + enum GNUNET_BLOCK_Type type, + uint32_t priority, + uint32_t anonymity, + uint32_t replication, + struct GNUNET_TIME_Absolute expiration, + uint64_t uid); + /** * Get an estimate of how much space the database is * currently using. * + * NB: estimate is an output parameter because emscripten cannot handle + * returning 64-bit integers from dynamically loaded modules. + * * @param cls closure + * @param estimate location to store estimate * @return number of bytes used on disk */ -typedef unsigned long long (*PluginGetSize) (void *cls); +typedef void +(*PluginEstimateSize) (void *cls, + unsigned long long *estimate); + + +/** + * Put continuation. + * + * @param cls closure + * @param key key for the item stored + * @param size size of the item stored + * @param status #GNUNET_OK if inserted, #GNUNET_NO if updated, + * or #GNUNET_SYSERROR if error + * @param msg error message on error + */ +typedef void +(*PluginPutCont) (void *cls, + const struct GNUNET_HashCode *key, + uint32_t size, + int status, + const char *msg); /** @@ -141,123 +153,151 @@ typedef unsigned long long (*PluginGetSize) (void *cls); * * @param cls closure * @param key key for the item - * @param size number of bytes in data + * @param absent true if the key was not found in the bloom filter + * @param size number of bytes in @a data * @param data content stored * @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_SYSERR on failure + * @param cont continuation called with success or failure status + * @param cont_cls continuation closure for @a cont + */ +typedef void +(*PluginPut) (void *cls, + const struct GNUNET_HashCode *key, + bool absent, + uint32_t size, + const void *data, + enum GNUNET_BLOCK_Type type, + uint32_t priority, + uint32_t anonymity, + uint32_t replication, + struct GNUNET_TIME_Absolute expiration, + PluginPutCont cont, + void *cont_cls); + + +/** + * An processor over a set of keys stored in the datastore. + * + * @param cls closure + * @param key key in the data store, if NULL iteration is finished + * @param count how many values are stored under this key in the datastore + */ +typedef void +(*PluginKeyProcessor) (void *cls, + const struct GNUNET_HashCode *key, + unsigned int count); + + +/** + * Get all of the keys in the datastore. + * + * @param cls closure + * @param proc function to call on each key + * @param proc_cls closure for @a proc */ -typedef int (*PluginPut) (void *cls, - const GNUNET_HashCode * key, - uint32_t size, - const void *data, - enum GNUNET_BLOCK_Type type, - uint32_t priority, - uint32_t anonymity, - uint32_t replication, - struct GNUNET_TIME_Absolute expiration, - char **msg); +typedef void +(*PluginGetKeys) (void *cls, + PluginKeyProcessor proc, + void *proc_cls); /** - * Iterate over the results for a particular key - * in the datastore. + * Get one of the results for a particular key in the datastore. * * @param cls closure + * @param next_uid return the result with lowest uid >= next_uid + * @param random if true, return a random result instead of using next_uid * @param key maybe NULL (to match all entries) - * @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 - * betwen key and vhash, but for other blocks - * there may be! * @param type entries of which type are relevant? * Use 0 for any type. - * @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 - * the next item; finally, the "iter" should be called once - * once with a NULL value at the end ("next_cls" should be NULL - * for that last call) - * @param iter_cls closure for iter + * @param proc function to call on the matching value; + * will be called with NULL if nothing matches + * @param proc_cls closure for @a proc */ -typedef void (*PluginGet) (void *cls, - const GNUNET_HashCode *key, - const GNUNET_HashCode *vhash, - enum GNUNET_BLOCK_Type type, - PluginIterator iter, void *iter_cls); - +typedef void +(*PluginGetKey) (void *cls, + uint64_t next_uid, + bool random, + const struct GNUNET_HashCode *key, + enum GNUNET_BLOCK_Type type, + PluginDatumProcessor proc, + void *proc_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. + * Remove continuation. * * @param cls closure - * @param iter function to call the value (once only). - * @param iter_cls closure for iter + * @param key key for the content removed + * @param size number of bytes removed + * @param status #GNUNET_OK if removed, #GNUNET_NO if not found, + * or #GNUNET_SYSERROR if error + * @param msg error message on error */ -typedef void (*PluginRandomGet) (void *cls, - PluginIterator iter, void *iter_cls); +typedef void +(*PluginRemoveCont) (void *cls, + const struct GNUNET_HashCode *key, + uint32_t size, + int status, + const char *msg); /** - * Update the priority for a particular key in the datastore. If - * the expiration time in value is different than the time found in - * the datastore, the higher value should be kept. For the - * anonymity level, the lower value is to be used. The specified - * priority should be added to the existing priority, ignoring the - * priority in value. + * Remove a particular key in the datastore. * - * Note that it is possible for multiple values to match this put. - * In that case, all of the respective values are updated. + * @param cls closure + * @param key key for the content + * @param size number of bytes in data + * @param data content stored + * @param cont continuation called with success or failure status + * @param cont_cls continuation closure for @a cont + */ +typedef void +(*PluginRemoveKey) (void *cls, + const struct GNUNET_HashCode *key, + uint32_t size, + const void *data, + PluginRemoveCont cont, + void *cont_cls); + + +/** + * Get a random item (additional constraints may apply depending on + * the specific implementation). Calls @a proc with all values ZERO or + * NULL if no item applies, otherwise @a proc is called once and only + * once with an item. * * @param cls closure - * @param uid unique identifier of the datum - * @param delta by how much should the priority - * change? If priority + delta < 0 the - * priority should be set to 0 (never go - * negative). - * @param expire new expiration time should be the - * MAX of any existing expiration time and - * this value - * @param msg set to an error message (on error) - * @return GNUNET_OK on success + * @param proc function to call the value (once only). + * @param proc_cls closure for @a proc */ -typedef int (*PluginUpdate) (void *cls, - uint64_t uid, - int delta, - struct GNUNET_TIME_Absolute expire, - char **msg); +typedef void +(*PluginGetRandom) (void *cls, + PluginDatumProcessor proc, + void *proc_cls); /** - * 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'. + * Select a single item from the datastore (among those applicable). * * @param cls closure + * @param next_uid return the result with lowest uid >= next_uid * @param type entries of which type should be considered? - * Use 0 for any type. - * @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 - * the next item; finally, the "iter" should be called once - * once with a NULL value at the end ("next_cls" should be NULL - * for that last call) - * @param iter_cls closure for iter + * Must not be zero (ANY). + * @param proc function to call on the matching value; + * will be called with NULL if no value matches + * @param proc_cls closure for @a proc */ -typedef void (*PluginSelector) (void *cls, - enum GNUNET_BLOCK_Type type, - PluginIterator iter, - void *iter_cls); +typedef void +(*PluginGetType) (void *cls, + uint64_t next_uid, + enum GNUNET_BLOCK_Type type, + PluginDatumProcessor proc, + void *proc_cls); /** @@ -265,8 +305,8 @@ typedef void (*PluginSelector) (void *cls, * * @param cls closure */ -typedef void (*PluginDrop) (void *cls); - +typedef void +(*PluginDrop) (void *cls); /** @@ -283,10 +323,10 @@ struct GNUNET_DATASTORE_PluginFunctions void *cls; /** - * Get the current on-disk size of the SQ store. Estimates are - * fine, if that's the only thing available. + * Calculate the current on-disk size of the SQ store. Estimates + * are fine, if that's the only thing available. */ - PluginGetSize get_size; + PluginEstimateSize estimate_size; /** * Function to store an item in the datastore. @@ -294,64 +334,48 @@ struct GNUNET_DATASTORE_PluginFunctions 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! + * Get a particular datum matching a given hash from the datastore. */ - PluginNextRequest next_request; + PluginGetKey get_key; /** - * Function to iterate over the results for a particular key - * in the datastore. + * Get datum (of the specified type) with anonymity level zero. */ - PluginGet get; + PluginGetType get_zero_anonymity; /** * Function to get a random item with high replication score from * the database, lowering the item's replication score. Returns a - * single, not expired, random item from those with the highest - * replication counters. The item's replication counter is - * decremented by one IF it was positive before. + * single random item from those with the highest replication + * counters. The item's replication counter is decremented by one + * IF it was positive before. */ - PluginRandomGet replication_get; + PluginGetRandom get_replication; /** - * Function to get a random expired item or, if none are expired, one - * with a low priority. + * Function to get a random expired item or, if none are expired, + * either the oldest entry or one with a low priority (depending + * on what was efficiently implementable). */ - PluginRandomGet expiration_get; + PluginGetRandom get_expiration; /** - * Update the priority for a particular key in the datastore. If - * the expiration time in value is different than the time found in - * the datastore, the higher value should be kept. For the - * anonymity level, the lower value is to be used. The specified - * priority should be added to the existing priority, ignoring the - * priority in value. + * Delete the database. The next operation is + * guaranteed to be unloading of the module. */ - PluginUpdate update; + PluginDrop drop; /** - * Iterate over content with anonymity level zero. + * Iterate over all keys in the database. */ - PluginSelector iter_zero_anonymity; + PluginGetKeys get_keys; /** - * 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 remove an item from the database. */ - PluginSelector iter_all_now; - - /** - * Delete the database. The next operation is - * guaranteed to be unloading of the module. - */ - PluginDrop drop; - + PluginRemoveKey remove_key; }; - #endif + +/** @} */ /* end of group */