gnunet_consensus_service.h (6007B)
1 /* 2 This file is part of GNUnet 3 Copyright (C) 2012 GNUnet e.V. 4 5 GNUnet is free software: you can redistribute it and/or modify it 6 under the terms of the GNU Affero General Public License as published 7 by the Free Software Foundation, either version 3 of the License, 8 or (at your option) any later version. 9 10 GNUnet is distributed in the hope that it will be useful, but 11 WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Affero General Public License for more details. 14 15 You should have received a copy of the GNU Affero General Public License 16 along with this program. If not, see <http://www.gnu.org/licenses/>. 17 18 SPDX-License-Identifier: AGPL3.0-or-later 19 */ 20 21 /** 22 * @addtogroup Sets 23 * @{ 24 * 25 * @author Florian Dold 26 * 27 * @file 28 * Multi-peer set reconciliation 29 * 30 * @defgroup consensus Consensus service 31 * Multi-peer set reconciliation 32 * @{ 33 */ 34 35 #ifndef GNUNET_CONSENSUS_SERVICE_H 36 #define GNUNET_CONSENSUS_SERVICE_H 37 38 #ifdef __cplusplus 39 extern "C" 40 { 41 #if 0 /* keep Emacsens' auto-indent happy */ 42 } 43 #endif 44 #endif 45 46 47 #include "gnunet_common.h" 48 #include "gnunet_time_lib.h" 49 #include "gnunet_configuration_lib.h" 50 #include "gnunet_set_service.h" 51 52 53 /** 54 * Elements inserted into the consensus set by the client 55 * may not be larger than this constant, since types in 56 * the upper range are used by CONSENSUS internally. 57 */ 58 #define GNUNET_CONSENSUS_ELEMENT_TYPE_USER_MAX 0xFFF0 59 60 61 /** 62 * Called when a new element was received from another peer, or an error occurred. 63 * May deliver duplicate values. 64 * Elements given to a consensus operation by the local peer are NOT given 65 * to this callback. 66 * 67 * @param cls closure 68 * @param element new element, NULL on error 69 */ 70 typedef void (*GNUNET_CONSENSUS_ElementCallback) (void *cls, 71 const struct 72 GNUNET_SET_Element *element); 73 74 75 /** 76 * Opaque handle for the consensus service. 77 */ 78 struct GNUNET_CONSENSUS_Handle; 79 80 81 /** 82 * Create a consensus session. The set being reconciled is initially 83 * empty. 84 * 85 * @param cfg configuration to use for connecting to the consensus service 86 * @param num_peers number of peers in the peers array 87 * @param peers array of peers participating in this consensus session 88 * Inclusion of the local peer is optional. 89 * @param session_id session identifier 90 * Allows a group of peers to have more than consensus session. 91 * @param start start time of the consensus, conclude should be called before 92 * the start time. 93 * @param deadline time when the consensus should have concluded 94 * @param new_element_cb callback, called when a new element is added to the set by 95 * another peer. Also called when an error occurs. 96 * @param new_element_cls closure for new_element 97 * @return handle to use, NULL on error 98 */ 99 struct GNUNET_CONSENSUS_Handle * 100 GNUNET_CONSENSUS_create (const struct GNUNET_CONFIGURATION_Handle *cfg, 101 unsigned int num_peers, 102 const struct GNUNET_PeerIdentity *peers, 103 const struct GNUNET_HashCode *session_id, 104 struct GNUNET_TIME_Absolute start, 105 struct GNUNET_TIME_Absolute deadline, 106 GNUNET_CONSENSUS_ElementCallback new_element_cb, 107 void *new_element_cls); 108 109 110 /** 111 * Called when an insertion (transmission to consensus service, which 112 * does not imply fully consensus on this element with all other 113 * peers) was successful. May not call GNUNET_CONSENSUS_destroy(); 114 * schedule a task to call GNUNET_CONSENSUS_destroy() instead (if 115 * needed). 116 * 117 * @param cls 118 * @param success #GNUNET_OK on success, #GNUNET_SYSERR if 119 * the insertion and thus the consensus failed for good 120 */ 121 typedef void (*GNUNET_CONSENSUS_InsertDoneCallback) (void *cls, 122 int success); 123 124 125 /** 126 * Insert an element in the set being reconsiled. Only transmit changes to 127 * other peers if GNUNET_CONSENSUS_begin() has been called. 128 * Must not be called after GNUNET_CONSENSUS_conclude(). 129 * May not call GNUNET_CONSENSUS_destroy(); schedule a task to call 130 * GNUNET_CONSENSUS_destroy() instead (if needed). 131 * 132 * @param consensus handle for the consensus session 133 * @param element the element to be inserted 134 * @param idc function called when we are done with this element and it 135 * is thus allowed to call GNUNET_CONSENSUS_insert() again 136 * @param idc_cls closure for @a idc 137 */ 138 void 139 GNUNET_CONSENSUS_insert (struct GNUNET_CONSENSUS_Handle *consensus, 140 const struct GNUNET_SET_Element *element, 141 GNUNET_CONSENSUS_InsertDoneCallback idc, 142 void *idc_cls); 143 144 145 /** 146 * Called when a conclusion was successful. 147 * 148 * @param cls 149 */ 150 typedef void (*GNUNET_CONSENSUS_ConcludeCallback) (void *cls); 151 152 153 /** 154 * We are finished inserting new elements into the consensus; 155 * try to conclude the consensus within a given time window. 156 * 157 * @param consensus consensus session 158 * @param conclude called when the conclusion was successful 159 * @param conclude_cls closure for the conclude callback 160 */ 161 void 162 GNUNET_CONSENSUS_conclude (struct GNUNET_CONSENSUS_Handle *consensus, 163 GNUNET_CONSENSUS_ConcludeCallback conclude, 164 void *conclude_cls); 165 166 167 /** 168 * Destroy a consensus handle (free all state associated with 169 * it, no longer call any of the callbacks). 170 * 171 * @param consensus handle to destroy 172 */ 173 void 174 GNUNET_CONSENSUS_destroy (struct GNUNET_CONSENSUS_Handle *consensus); 175 176 177 #if 0 /* keep Emacsens' auto-indent happy */ 178 { 179 #endif 180 #ifdef __cplusplus 181 } 182 #endif 183 184 #endif 185 186 /** @} */ /* end of group */ 187 188 /** @} */ /* end of group addition */