X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_consensus_service.h;h=957e88a801c9086ca9baa7800f2d1d29f46327b3;hb=17047b7bcbe3f1756028058a9887416c6afab5d8;hp=232033598f1cec0cd84f0292f46ddb2d5b51b93c;hpb=fb9e3f9dbb17d3a606ff6aac9791b7a7ab436d56;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_consensus_service.h b/src/include/gnunet_consensus_service.h index 232033598..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 * @author Florian Dold + * + * @file + * Multi-peer set reconciliation + * + * @defgroup consensus Consensus service + * Multi-peer set reconciliation + * @{ */ #ifndef GNUNET_CONSENSUS_SERVICE_H @@ -35,49 +40,31 @@ 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 /** * Called when a new element was received from another peer, or an error occured. - * * May deliver duplicate values. - * * Elements given to a consensus operation by the local peer are NOT given * to this callback. * * @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_NewElementCallback) (void *cls, - struct GNUNET_CONSENSUS_Element *element); +typedef void (*GNUNET_CONSENSUS_ElementCallback) (void *cls, + const struct GNUNET_SET_Element *element); @@ -88,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 @@ -98,116 +84,67 @@ 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 */ struct GNUNET_CONSENSUS_Handle * GNUNET_CONSENSUS_create (const struct GNUNET_CONFIGURATION_Handle *cfg, - unsigned int num_peers, - const struct GNUNET_PeerIdentity *peers, + unsigned int num_peers, + const struct GNUNET_PeerIdentity *peers, const struct GNUNET_HashCode *session_id, - GNUNET_CONSENSUS_NewElementCallback new_element_cb, + 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. + * 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, - int success); + int success); /** * 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". + * 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, - GNUNET_CONSENSUS_InsertDoneCallback idc, - void *idc_cls); - - -/** - * Begin reconciling elements with other peers. - * May not be called if an insert operation has not yet finished. - * - * @param consensus handle for the consensus session - */ -void -GNUNET_CONSENSUS_begin (struct GNUNET_CONSENSUS_Handle *consensus); - - - -struct GNUNET_CONSENSUS_DeltaRequest; - -/** - * We are finished inserting new elements into the consensus; - * 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 - */ -struct GNUNET_CONSENSUS_DeltaRequest * -GNUNET_CONSENSUS_get_delta (struct GNUNET_CONSENSUS_Handle *consensus, - uint32_t group_id, - GNUNET_CONSENSUS_NewElementCallback remove_element_cb, - void *remove_element_cb_cls); + const struct GNUNET_SET_Element *element, + GNUNET_CONSENSUS_InsertDoneCallback idc, + void *idc_cls); -void -GNUNET_CONSENSUS_get_delta_cancel (struct GNUNET_CONSENSUS_DeltaRequest *dr); - - -struct GNUNET_CONSENSUS_Group -{ - uint32_t group_id; /* offset into groups? */ - unsigned int num_members; - uint64_t total_elements_in_group; - const struct GNUNET_PeerIdentity **members; -}; - /** * Called when a conclusion was successful. * * @param cls - * @param num_peers_in_consensus - * @param peers_in_consensus */ -typedef void (*GNUNET_CONSENSUS_NewConcludeCallback) (void *cls, - unsigned int consensus_group_count, - const struct GNUNET_CONSENSUS_Group *groups); - - -/** - * Called when a conclusion was successful. - * - * @param cls - * @param num_peers_in_consensus - * @param peers_in_consensus - */ -typedef void (*GNUNET_CONSENSUS_ConcludeCallback) (void *cls, - unsigned int num_peers_in_consensus, - const struct GNUNET_PeerIdentity *peers_in_consensus); +typedef void (*GNUNET_CONSENSUS_ConcludeCallback) (void *cls); /** @@ -215,17 +152,13 @@ typedef void (*GNUNET_CONSENSUS_ConcludeCallback) (void *cls, * 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); + GNUNET_CONSENSUS_ConcludeCallback conclude, + void *conclude_cls); /** @@ -246,3 +179,5 @@ GNUNET_CONSENSUS_destroy (struct GNUNET_CONSENSUS_Handle *consensus); #endif #endif + +/** @} */ /* end of group */