X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_consensus_service.h;h=957e88a801c9086ca9baa7800f2d1d29f46327b3;hb=17047b7bcbe3f1756028058a9887416c6afab5d8;hp=49f18c950e07c47651248ae8b31f600d33332338;hpb=c0ee9a86aba8adf73d03a5b7bfa4650a24028855;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_consensus_service.h b/src/include/gnunet_consensus_service.h index 49f18c950..957e88a80 100644 --- a/src/include/gnunet_consensus_service.h +++ b/src/include/gnunet_consensus_service.h @@ -1,10 +1,10 @@ /* This file is part of GNUnet - (C) 2012 Christian Grothoff (and other contributing authors) + Copyright (C) 2012 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_consensus_service.h - * @brief multi-peer set reconciliation * @author Florian Dold + * + * @file + * Multi-peer set reconciliation + * + * @defgroup consensus Consensus service + * Multi-peer set reconciliation + * @{ */ #ifndef GNUNET_CONSENSUS_SERVICE_H @@ -35,32 +40,18 @@ extern "C" #endif #endif -#include "platform.h" #include "gnunet_common.h" #include "gnunet_time_lib.h" #include "gnunet_configuration_lib.h" +#include "gnunet_set_service.h" /** - * An element of the consensus set. + * Elements inserted into the consensus set by the client + * may not be larger than this constant, since types in + * the upper range are used by CONSENSUS internally. */ -struct GNUNET_CONSENSUS_Element -{ - /** - * The actual data of the element. - */ - const void *data; - - /** - * Size of the element's data. - */ - uint16_t size; - - /** - * Application specific element type - */ - uint16_t type; -}; +#define GNUNET_CONSENSUS_ELEMENT_TYPE_USER_MAX 0xFFF0 /** @@ -71,11 +62,9 @@ struct GNUNET_CONSENSUS_Element * * @param cls closure * @param element new element, NULL on error - * @return GNUNET_OK if the valid is well-formed and should be added to the consensus, - * GNUNET_SYSERR if the element should be ignored and not be propagated */ -typedef int (*GNUNET_CONSENSUS_ElementCallback) (void *cls, - const struct GNUNET_CONSENSUS_Element *element); +typedef void (*GNUNET_CONSENSUS_ElementCallback) (void *cls, + const struct GNUNET_SET_Element *element); @@ -86,9 +75,8 @@ struct GNUNET_CONSENSUS_Handle; /** - * Create a consensus session. - * The set being reconciled is initially empty. Only reconcile with other peers - * after GNUNET_CONSENSUS_reconcile has been called. + * Create a consensus session. The set being reconciled is initially + * empty. * * @param cfg * @param num_peers @@ -96,8 +84,11 @@ struct GNUNET_CONSENSUS_Handle; * Inclusion of the local peer is optional. * @param session_id session identifier * Allows a group of peers to have more than consensus session. + * @param start start time of the consensus, conclude should be called before + * the start time. + * @param deadline time when the consensus should have concluded * @param new_element_cb callback, called when a new element is added to the set by - * another peer + * another peer. Also called when an error occurs. * @param new_element_cls closure for new_element * @return handle to use, NULL on error */ @@ -106,19 +97,21 @@ GNUNET_CONSENSUS_create (const struct GNUNET_CONFIGURATION_Handle *cfg, unsigned int num_peers, const struct GNUNET_PeerIdentity *peers, const struct GNUNET_HashCode *session_id, + struct GNUNET_TIME_Absolute start, + struct GNUNET_TIME_Absolute deadline, GNUNET_CONSENSUS_ElementCallback new_element_cb, void *new_element_cls); /** - * Called when an insertion (transmission to consensus service, - * which does not imply fully consensus on this element with - * all other peers) was successful. - * May not call GNUNET_CONSENSUS_destroy; schedule a task to call - * GNUNET_CONSENSUS_destroy instead. + * Called when an insertion (transmission to consensus service, which + * does not imply fully consensus on this element with all other + * peers) was successful. May not call GNUNET_CONSENSUS_destroy(); + * schedule a task to call GNUNET_CONSENSUS_destroy() instead (if + * needed). * * @param cls - * @param success GNUNET_OK on success, GNUNET_SYSERR if + * @param success #GNUNET_OK on success, #GNUNET_SYSERR if * the insertion and thus the consensus failed for good */ typedef void (*GNUNET_CONSENSUS_InsertDoneCallback) (void *cls, @@ -127,58 +120,31 @@ typedef void (*GNUNET_CONSENSUS_InsertDoneCallback) (void *cls, /** * Insert an element in the set being reconsiled. Only transmit changes to - * other peers if "GNUNET_CONSENSUS_begin" has been called. - * Must not be called after "GNUNET_CONSENSUS_conclude". - * May not call GNUNET_CONSENSUS_destroy; schedule a task to call - * GNUNET_CONSENSUS_destroy instead. + * other peers if GNUNET_CONSENSUS_begin() has been called. + * Must not be called after GNUNET_CONSENSUS_conclude(). + * May not call GNUNET_CONSENSUS_destroy(); schedule a task to call + * GNUNET_CONSENSUS_destroy() instead (if needed). * * @param consensus handle for the consensus session * @param element the element to be inserted - * @param idc function called when we are done with this element and it - * is thus allowed to call GNUNET_CONSENSUS_insert again - * @param idc_cls closure for 'idc' + * @param idc function called when we are done with this element and it + * is thus allowed to call GNUNET_CONSENSUS_insert() again + * @param idc_cls closure for @a idc */ void GNUNET_CONSENSUS_insert (struct GNUNET_CONSENSUS_Handle *consensus, - const struct GNUNET_CONSENSUS_Element *element, + const struct GNUNET_SET_Element *element, GNUNET_CONSENSUS_InsertDoneCallback idc, void *idc_cls); -struct GNUNET_CONSENSUS_DeltaRequest; - -/** - * FIXME - * - * @param consensus consensus session - * @param remove_element_cb callback that receives the removed elements - * @return a handle to cancel the request - */ -struct GNUNET_CONSENSUS_DeltaRequest * -GNUNET_CONSENSUS_get_delta (struct GNUNET_CONSENSUS_Handle *consensus, - GNUNET_CONSENSUS_ElementCallback remove_element_cb, - void *remove_element_cb_cls); - - -void -GNUNET_CONSENSUS_get_delta_cancel (struct GNUNET_CONSENSUS_DeltaRequest *dr); - - -struct GNUNET_CONSENSUS_Group -{ - unsigned int num_members; - uint64_t total_elements_in_group; - const struct GNUNET_PeerIdentity **members; -}; - /** * Called when a conclusion was successful. * * @param cls - * @param group */ -typedef void (*GNUNET_CONSENSUS_ConcludeCallback) (void *cls, const struct GNUNET_CONSENSUS_Group *group); +typedef void (*GNUNET_CONSENSUS_ConcludeCallback) (void *cls); /** @@ -186,15 +152,11 @@ typedef void (*GNUNET_CONSENSUS_ConcludeCallback) (void *cls, const struct GNUNE * try to conclude the consensus within a given time window. * * @param consensus consensus session - * @param timeout timeout after which the conculde callback - * must be called * @param conclude called when the conclusion was successful * @param conclude_cls closure for the conclude callback */ void GNUNET_CONSENSUS_conclude (struct GNUNET_CONSENSUS_Handle *consensus, - struct GNUNET_TIME_Relative timeout, - unsigned int min_group_size_in_consensus, GNUNET_CONSENSUS_ConcludeCallback conclude, void *conclude_cls); @@ -217,3 +179,5 @@ GNUNET_CONSENSUS_destroy (struct GNUNET_CONSENSUS_Handle *consensus); #endif #endif + +/** @} */ /* end of group */