X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_consensus_service.h;h=957e88a801c9086ca9baa7800f2d1d29f46327b3;hb=17047b7bcbe3f1756028058a9887416c6afab5d8;hp=66d48e0e200a4a87950fd9777b8bee817744a21c;hpb=022002438e4047d235a688cfd9da7b63ab990103;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_consensus_service.h b/src/include/gnunet_consensus_service.h index 66d48e0e2..957e88a80 100644 --- a/src/include/gnunet_consensus_service.h +++ b/src/include/gnunet_consensus_service.h @@ -1,6 +1,6 @@ /* 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 @@ -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 /** @@ -73,7 +64,7 @@ struct GNUNET_CONSENSUS_Element * @param element new element, NULL on error */ typedef void (*GNUNET_CONSENSUS_ElementCallback) (void *cls, - const struct GNUNET_CONSENSUS_Element *element); + const struct GNUNET_SET_Element *element); @@ -85,8 +76,7 @@ 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. + * empty. * * @param cfg * @param num_peers @@ -94,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 */ @@ -104,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, @@ -125,20 +120,20 @@ 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); @@ -157,14 +152,11 @@ 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, GNUNET_CONSENSUS_ConcludeCallback conclude, void *conclude_cls); @@ -187,3 +179,5 @@ GNUNET_CONSENSUS_destroy (struct GNUNET_CONSENSUS_Handle *consensus); #endif #endif + +/** @} */ /* end of group */