X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_consensus_service.h;h=957e88a801c9086ca9baa7800f2d1d29f46327b3;hb=17047b7bcbe3f1756028058a9887416c6afab5d8;hp=7b555d4f27a4ada71d82fff78692b3921e213555;hpb=46e7fe13591a6232f7680d048e8a79de21fdd3a7;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_consensus_service.h b/src/include/gnunet_consensus_service.h index 7b555d4f2..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,23 +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" + + +/** + * 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. + */ +#define GNUNET_CONSENSUS_ELEMENT_TYPE_USER_MAX 0xFFF0 /** - * Called when a new element was received from another peer; elements - * given to a consensus operation by the local peer are NOT given + * 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_size will match the size given to GNUNET_CONSENSUS_create - * @param element + * @param element new element, NULL on error */ -typedef void (*GNUNET_CONSENSUS_NewElementCallback) (void *cls, - size_t element_size, - const void *element); +typedef void (*GNUNET_CONSENSUS_ElementCallback) (void *cls, + const struct GNUNET_SET_Element *element); @@ -62,72 +75,76 @@ struct GNUNET_CONSENSUS_Handle; /** - * Create a consensus session. + * Create a consensus session. The set being reconciled is initially + * empty. * * @param cfg * @param num_peers * @param peers array of peers participating in this consensus session + * Inclusion of the local peer is optional. * @param session_id session identifier * Allows a group of peers to have more than consensus session. - * @param element_size size of the elements in the reconciled set in bytes - * @param new_element callback, called when a new element is added to the set by - * another peer - * @param mew_element_cls closure for new_element + * @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. 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, - size_t element_size, - const void **initial_elements, - GNUNET_CONSENSUS_NewElementCallback new_element, + 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. Must not be called after - * "GNUNET_CONSENSUS_conclude". + * 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 (if needed). * * @param consensus handle for the consensus session - * @param element_size must match element size from GNUNET_CONSENSUS_create * @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, - size_t element_size, - const void *element, - GNUNET_CONSENSUS_InsertDoneCallback idc, - void *idc_cls); + const struct GNUNET_SET_Element *element, + GNUNET_CONSENSUS_InsertDoneCallback idc, + void *idc_cls); + /** * 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, - cnost struct GNUNET_PeerIdentity *peers_in_consensus); +typedef void (*GNUNET_CONSENSUS_ConcludeCallback) (void *cls); /** @@ -135,16 +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, - GNUNET_CONSENSUS_ConcludeCallback conclude, - void *conclude_cls); + GNUNET_CONSENSUS_ConcludeCallback conclude, + void *conclude_cls); /** @@ -165,3 +179,5 @@ GNUNET_CONSENSUS_destroy (struct GNUNET_CONSENSUS_Handle *consensus); #endif #endif + +/** @} */ /* end of group */