X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_datastore_service.h;h=721963bddf194fe412a298915c035a56b7531236;hb=f315953dd3ec50b6cf6482834b6403680238d9da;hp=6f16dad224a74d1a921bd2ee06d43aff448a19da;hpb=aab2f42e7fc3fe7d0ad7b9a4a5e8b4bc42c78505;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_datastore_service.h b/src/include/gnunet_datastore_service.h index 6f16dad22..721963bdd 100644 --- a/src/include/gnunet_datastore_service.h +++ b/src/include/gnunet_datastore_service.h @@ -1,6 +1,6 @@ /* This file is part of GNUnet - (C) 2004, 2005, 2006, 2007, 2009, 2010 Christian Grothoff (and other contributing authors) + (C) 2004, 2005, 2006, 2007, 2009, 2010, 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 @@ -42,26 +42,29 @@ extern "C" #endif #endif +/** + * Entry in the queue. + */ +struct GNUNET_DATASTORE_QueueEntry; /** * Handle to the datastore service. */ struct GNUNET_DATASTORE_Handle; +/** + * Maximum size of a value that can be stored in the datastore. + */ +#define GNUNET_DATASTORE_MAX_VALUE_SIZE 65536 /** * Connect to the datastore service. * * @param cfg configuration to use - * @param sched scheduler to use * @return handle to use to access the service */ -struct GNUNET_DATASTORE_Handle *GNUNET_DATASTORE_connect (const struct - GNUNET_CONFIGURATION_Handle - *cfg, - struct - GNUNET_SCHEDULER_Handle - *sched); +struct GNUNET_DATASTORE_Handle * +GNUNET_DATASTORE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg); /** @@ -71,8 +74,8 @@ struct GNUNET_DATASTORE_Handle *GNUNET_DATASTORE_connect (const struct * @param h handle to the datastore * @param drop set to GNUNET_YES to delete all data in datastore (!) */ -void GNUNET_DATASTORE_disconnect (struct GNUNET_DATASTORE_Handle *h, - int drop); +void +GNUNET_DATASTORE_disconnect (struct GNUNET_DATASTORE_Handle *h, int drop); /** @@ -80,14 +83,18 @@ void GNUNET_DATASTORE_disconnect (struct GNUNET_DATASTORE_Handle *h, * operation. * * @param cls closure - * @param success GNUNET_SYSERR on failure, - * GNUNET_NO on timeout/queue drop - * GNUNET_YES on success + * @param success GNUNET_SYSERR on failure (including timeout/queue drop) + * GNUNET_NO if content was already there + * GNUNET_YES (or other positive value) on success + * @param min_expiration minimum expiration time required for 0-priority content to be stored + * by the datacache at this time, zero for unknown, forever if we have no + * space for 0-priority content * @param msg NULL on success, otherwise an error message */ -typedef void (*GNUNET_DATASTORE_ContinuationWithStatus)(void *cls, - int success, - const char *msg); +typedef void (*GNUNET_DATASTORE_ContinuationWithStatus) (void *cls, + int32_t success, + struct GNUNET_TIME_Absolute min_expiration, + const char *msg); /** @@ -105,22 +112,23 @@ typedef void (*GNUNET_DATASTORE_ContinuationWithStatus)(void *cls, * @param cont continuation to call when done; "success" will be set to * a positive reservation value if space could be reserved. * @param cont_cls closure for cont + * @return NULL if the entry was not queued, otherwise a handle that can be used to + * cancel; note that even if NULL is returned, the callback will be invoked + * (or rather, will already have been invoked) */ -void -GNUNET_DATASTORE_reserve (struct GNUNET_DATASTORE_Handle *h, - uint64_t amount, - uint32_t entries, - unsigned int queue_priority, - unsigned int max_queue_size, - struct GNUNET_TIME_Relative timeout, - GNUNET_DATASTORE_ContinuationWithStatus cont, - void *cont_cls); +struct GNUNET_DATASTORE_QueueEntry * +GNUNET_DATASTORE_reserve (struct GNUNET_DATASTORE_Handle *h, uint64_t amount, + uint32_t entries, unsigned int queue_priority, + unsigned int max_queue_size, + struct GNUNET_TIME_Relative timeout, + GNUNET_DATASTORE_ContinuationWithStatus cont, + void *cont_cls); /** * 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 values are summed up and the higher + * expiration time and lower anonymity level is used. * * @param h handle to the datastore * @param rid reservation ID to use (from "reserve"); use 0 if no @@ -131,6 +139,7 @@ GNUNET_DATASTORE_reserve (struct GNUNET_DATASTORE_Handle *h, * @param type type of the content * @param priority priority of the content * @param anonymity anonymity-level for the content + * @param replication how often should the content be replicated to other peers? * @param expiration expiration time for the content * @param queue_priority ranking of this request in the priority queue * @param max_queue_size at what queue size should this request be dropped @@ -138,22 +147,21 @@ GNUNET_DATASTORE_reserve (struct GNUNET_DATASTORE_Handle *h, * @param timeout timeout for the operation * @param cont continuation to call when done * @param cont_cls closure for cont + * @return NULL if the entry was not queued, otherwise a handle that can be used to + * cancel; note that even if NULL is returned, the callback will be invoked + * (or rather, will already have been invoked) */ -void -GNUNET_DATASTORE_put (struct GNUNET_DATASTORE_Handle *h, - int rid, - const GNUNET_HashCode * key, - uint32_t size, - const void *data, - enum GNUNET_BLOCK_Type type, - uint32_t priority, - uint32_t anonymity, +struct GNUNET_DATASTORE_QueueEntry * +GNUNET_DATASTORE_put (struct GNUNET_DATASTORE_Handle *h, uint32_t rid, + const struct GNUNET_HashCode * key, size_t size, + const void *data, enum GNUNET_BLOCK_Type type, + uint32_t priority, uint32_t anonymity, + uint32_t replication, struct GNUNET_TIME_Absolute expiration, - unsigned int queue_priority, - unsigned int max_queue_size, + unsigned int queue_priority, unsigned int max_queue_size, struct GNUNET_TIME_Relative timeout, - GNUNET_DATASTORE_ContinuationWithStatus cont, - void *cont_cls); + GNUNET_DATASTORE_ContinuationWithStatus cont, + void *cont_cls); /** @@ -173,15 +181,17 @@ GNUNET_DATASTORE_put (struct GNUNET_DATASTORE_Handle *h, * @param timeout how long to wait at most for a response * @param cont continuation to call when done * @param cont_cls closure for cont + * @return NULL if the entry was not queued, otherwise a handle that can be used to + * cancel; note that even if NULL is returned, the callback will be invoked + * (or rather, will already have been invoked) */ -void +struct GNUNET_DATASTORE_QueueEntry * GNUNET_DATASTORE_release_reserve (struct GNUNET_DATASTORE_Handle *h, - int rid, - unsigned int queue_priority, - unsigned int max_queue_size, - struct GNUNET_TIME_Relative timeout, - GNUNET_DATASTORE_ContinuationWithStatus cont, - void *cont_cls); + uint32_t rid, unsigned int queue_priority, + unsigned int max_queue_size, + struct GNUNET_TIME_Relative timeout, + GNUNET_DATASTORE_ContinuationWithStatus cont, + void *cont_cls); /** @@ -197,21 +207,54 @@ GNUNET_DATASTORE_release_reserve (struct GNUNET_DATASTORE_Handle *h, * @param timeout how long to wait at most for a response * @param cont continuation to call when done * @param cont_cls closure for cont + * @return NULL if the entry was not queued, otherwise a handle that can be used to + * cancel; note that even if NULL is returned, the callback will be invoked + * (or rather, will already have been invoked) */ -void -GNUNET_DATASTORE_update (struct GNUNET_DATASTORE_Handle *h, - unsigned long long uid, - uint32_t priority, - struct GNUNET_TIME_Absolute expiration, - unsigned int queue_priority, - unsigned int max_queue_size, - struct GNUNET_TIME_Relative timeout, - GNUNET_DATASTORE_ContinuationWithStatus cont, - void *cont_cls); +struct GNUNET_DATASTORE_QueueEntry * +GNUNET_DATASTORE_update (struct GNUNET_DATASTORE_Handle *h, uint64_t uid, + uint32_t priority, + struct GNUNET_TIME_Absolute expiration, + unsigned int queue_priority, + unsigned int max_queue_size, + struct GNUNET_TIME_Relative timeout, + GNUNET_DATASTORE_ContinuationWithStatus cont, + void *cont_cls); + + +/** + * Explicitly remove some content from the database. + * The "cont"inuation will be called with status + * "GNUNET_OK" if content was removed, "GNUNET_NO" + * if no matching entry was found and "GNUNET_SYSERR" + * on all other types of errors. + * + * @param h handle to the datastore + * @param key key for the value + * @param size number of bytes in data + * @param data content stored + * @param queue_priority ranking of this request in the priority queue + * @param max_queue_size at what queue size should this request be dropped + * (if other requests of higher priority are in the queue) + * @param timeout how long to wait at most for a response + * @param cont continuation to call when done + * @param cont_cls closure for cont + * @return NULL if the entry was not queued, otherwise a handle that can be used to + * cancel; note that even if NULL is returned, the callback will be invoked + * (or rather, will already have been invoked) + */ +struct GNUNET_DATASTORE_QueueEntry * +GNUNET_DATASTORE_remove (struct GNUNET_DATASTORE_Handle *h, + const struct GNUNET_HashCode * key, size_t size, + const void *data, unsigned int queue_priority, + unsigned int max_queue_size, + struct GNUNET_TIME_Relative timeout, + GNUNET_DATASTORE_ContinuationWithStatus cont, + void *cont_cls); /** - * An iterator over a set of items stored in the datastore. + * Process a datum that was stored in the datastore. * * @param cls closure * @param key key for the content @@ -224,109 +267,119 @@ GNUNET_DATASTORE_update (struct GNUNET_DATASTORE_Handle *h, * @param uid unique identifier for the datum; * maybe 0 if no unique identifier is available */ -typedef void (*GNUNET_DATASTORE_Iterator) (void *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 void (*GNUNET_DATASTORE_DatumProcessor) (void *cls, + const struct GNUNET_HashCode * key, + size_t size, const void *data, + enum GNUNET_BLOCK_Type type, + uint32_t priority, + uint32_t anonymity, + struct GNUNET_TIME_Absolute + expiration, uint64_t uid); /** - * Iterate over the results for a particular key - * in the datastore. The iterator will only be called - * once initially; if the first call did contain a - * result, further results can be obtained by calling - * "GNUNET_DATASTORE_get_next" with the given argument. + * Get a result for a particular key from the datastore. The processor + * will only be called once. * * @param h handle to the datastore + * @param offset offset of the result (modulo num-results); set to + * a random 64-bit value initially; then increment by + * one each time; detect that all results have been found by uid + * being again the first uid ever returned. * @param key maybe NULL (to match all entries) * @param type desired type, 0 for any * @param queue_priority ranking of this request in the priority queue * @param max_queue_size at what queue size should this request be dropped * (if other requests of higher priority are in the queue) * @param timeout how long to wait at most for a response - * @param iter function to call on each matching value; - * will be called once with a NULL value at the end - * @param iter_cls closure for iter + * @param proc function to call on a matching value; + * or with a NULL value if no datum matches + * @param proc_cls closure for proc + * @return NULL if the entry was not queued, otherwise a handle that can be used to + * cancel */ -void -GNUNET_DATASTORE_get (struct GNUNET_DATASTORE_Handle *h, - const GNUNET_HashCode * key, - enum GNUNET_BLOCK_Type type, - unsigned int queue_priority, - unsigned int max_queue_size, - struct GNUNET_TIME_Relative timeout, - GNUNET_DATASTORE_Iterator iter, - void *iter_cls); +struct GNUNET_DATASTORE_QueueEntry * +GNUNET_DATASTORE_get_key (struct GNUNET_DATASTORE_Handle *h, uint64_t offset, + const struct GNUNET_HashCode * key, + enum GNUNET_BLOCK_Type type, + unsigned int queue_priority, + unsigned int max_queue_size, + struct GNUNET_TIME_Relative timeout, + GNUNET_DATASTORE_DatumProcessor proc, void *proc_cls); /** - * Function called to trigger obtaining the next result - * from the datastore. - * + * Get a single zero-anonymity value from the datastore. + * Note that some implementations can ignore the 'offset' and + * instead return a random zero-anonymity value. In that case, + * detecting the wrap-around based on a repeating UID is at best + * probabilistic. + * * @param h handle to the datastore - * @param more GNUNET_YES to get moxre results, GNUNET_NO to abort - * iteration (with a final call to "iter" with key/data == NULL). + * @param offset offset of the result (modulo num-results); set to + * a random 64-bit value initially; then increment by + * one each time; detect that all results have been found by uid + * being again the first uid ever returned. + * @param queue_priority ranking of this request in the priority queue + * @param max_queue_size at what queue size should this request be dropped + * (if other requests of higher priority are in the queue) + * @param timeout how long to wait at most for a response + * @param type allowed type for the operation (never zero) + * @param proc function to call on a random value; it + * will be called once with a value (if available) + * or with NULL if none value exists. + * @param proc_cls closure for proc + * @return NULL if the entry was not queued, otherwise a handle that can be used to + * cancel */ -void -GNUNET_DATASTORE_get_next (struct GNUNET_DATASTORE_Handle *h, - int more); +struct GNUNET_DATASTORE_QueueEntry * +GNUNET_DATASTORE_get_zero_anonymity (struct GNUNET_DATASTORE_Handle *h, + uint64_t offset, + unsigned int queue_priority, + unsigned int max_queue_size, + struct GNUNET_TIME_Relative timeout, + enum GNUNET_BLOCK_Type type, + GNUNET_DATASTORE_DatumProcessor proc, + void *proc_cls); /** - * Get a random value from the datastore. + * Get a random value from the datastore for content replication. + * Returns a single, random value among those with the highest + * replication score, lowering positive replication scores by one for + * the chosen value (if only content with a replication score exists, + * a random value is returned and replication scores are not changed). * * @param h handle to the datastore * @param queue_priority ranking of this request in the priority queue * @param max_queue_size at what queue size should this request be dropped * (if other requests of higher priority are in the queue) * @param timeout how long to wait at most for a response - * @param iter function to call on a random value; it + * @param proc function to call on a random value; it * will be called once with a value (if available) * and always once with a value of NULL. - * @param iter_cls closure for iter + * @param proc_cls closure for proc + * @return NULL if the entry was not queued, otherwise a handle that can be used to + * cancel */ -void -GNUNET_DATASTORE_get_random (struct GNUNET_DATASTORE_Handle *h, - unsigned int queue_priority, - unsigned int max_queue_size, - struct GNUNET_TIME_Relative timeout, - GNUNET_DATASTORE_Iterator iter, - void *iter_cls); +struct GNUNET_DATASTORE_QueueEntry * +GNUNET_DATASTORE_get_for_replication (struct GNUNET_DATASTORE_Handle *h, + unsigned int queue_priority, + unsigned int max_queue_size, + struct GNUNET_TIME_Relative timeout, + GNUNET_DATASTORE_DatumProcessor proc, + void *proc_cls); + /** - * Explicitly remove some content from the database. - * The "cont"inuation will be called with status - * "GNUNET_OK" if content was removed, "GNUNET_NO" - * if no matching entry was found and "GNUNET_SYSERR" - * on all other types of errors. + * Cancel a datastore operation. The final callback from the + * operation must not have been done yet. * - * @param h handle to the datastore - * @param key key for the value - * @param size number of bytes in data - * @param data content stored - * @param queue_priority ranking of this request in the priority queue - * @param max_queue_size at what queue size should this request be dropped - * (if other requests of higher priority are in the queue) - * @param timeout how long to wait at most for a response - * @param cont continuation to call when done - * @param cont_cls closure for cont + * @param qe operation to cancel */ void -GNUNET_DATASTORE_remove (struct GNUNET_DATASTORE_Handle *h, - const GNUNET_HashCode *key, - uint32_t size, - const void *data, - unsigned int queue_priority, - unsigned int max_queue_size, - struct GNUNET_TIME_Relative timeout, - GNUNET_DATASTORE_ContinuationWithStatus cont, - void *cont_cls); +GNUNET_DATASTORE_cancel (struct GNUNET_DATASTORE_QueueEntry *qe); #if 0 /* keep Emacsens' auto-indent happy */