src/include/gnunet_consensus_service.h

   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  * @author Florian Dold
  23  *
  24  * @file
  25  * Multi-peer set reconciliation
  26  *
  27  * @defgroup consensus  Consensus service
  28  * Multi-peer set reconciliation
  29  * @{
  30  */
  31
  32 #ifndef GNUNET_CONSENSUS_SERVICE_H
  33 #define GNUNET_CONSENSUS_SERVICE_H
  34
  35 #ifdef __cplusplus
  36 extern "C"
  37 {
  38 #if 0                           /* keep Emacsens' auto-indent happy */
  39 }
  40 #endif
  41 #endif
  42
  43 #include "gnunet_common.h"
  44 #include "gnunet_time_lib.h"
  45 #include "gnunet_configuration_lib.h"
  46 #include "gnunet_set_service.h"
  47
  48
  49 /**
  50  * Elements inserted into the consensus set by the client
  51  * may not be larger than this constant, since types in
  52  * the upper range are used by CONSENSUS internally.
  53  */
  54 #define GNUNET_CONSENSUS_ELEMENT_TYPE_USER_MAX 0xFFF0
  55
  56
  57 /**
  58  * Called when a new element was received from another peer, or an error occurred.
  59  * May deliver duplicate values.
  60  * Elements given to a consensus operation by the local peer are NOT given
  61  * to this callback.
  62  *
  63  * @param cls closure
  64  * @param element new element, NULL on error
  65  */
  66 typedef void (*GNUNET_CONSENSUS_ElementCallback) (void *cls,
  67                                                   const struct GNUNET_SET_Element *element);
  68
  69
  70
  71 /**
  72  * Opaque handle for the consensus service.
  73  */
  74 struct GNUNET_CONSENSUS_Handle;
  75
  76
  77 /**
  78  * Create a consensus session.  The set being reconciled is initially
  79  * empty.
  80  *
  81  * @param cfg
  82  * @param num_peers
  83  * @param peers array of peers participating in this consensus session
  84  *              Inclusion of the local peer is optional.
  85  * @param session_id session identifier
  86  *                   Allows a group of peers to have more than consensus session.
  87  * @param start start time of the consensus, conclude should be called before
  88  *              the start time.
  89  * @param deadline time when the consensus should have concluded
  90  * @param new_element_cb callback, called when a new element is added to the set by
  91  *                    another peer. Also called when an error occurs.
  92  * @param new_element_cls closure for new_element
  93  * @return handle to use, NULL on error
  94  */
  95 struct GNUNET_CONSENSUS_Handle *
  96 GNUNET_CONSENSUS_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
  97                          unsigned int num_peers,
  98                          const struct GNUNET_PeerIdentity *peers,
  99                          const struct GNUNET_HashCode *session_id,
 100                          struct GNUNET_TIME_Absolute start,
 101                          struct GNUNET_TIME_Absolute deadline,
 102                          GNUNET_CONSENSUS_ElementCallback new_element_cb,
 103                          void *new_element_cls);
 104
 105
 106 /**
 107  * Called when an insertion (transmission to consensus service, which
 108  * does not imply fully consensus on this element with all other
 109  * peers) was successful.  May not call GNUNET_CONSENSUS_destroy();
 110  * schedule a task to call GNUNET_CONSENSUS_destroy() instead (if
 111  * needed).
 112  *
 113  * @param cls
 114  * @param success #GNUNET_OK on success, #GNUNET_SYSERR if
 115  *        the insertion and thus the consensus failed for good
 116  */
 117 typedef void (*GNUNET_CONSENSUS_InsertDoneCallback) (void *cls,
 118                                                      int success);
 119
 120
 121 /**
 122  * Insert an element in the set being reconsiled.  Only transmit changes to
 123  * other peers if GNUNET_CONSENSUS_begin() has been called.
 124  * Must not be called after GNUNET_CONSENSUS_conclude().
 125  * May not call GNUNET_CONSENSUS_destroy(); schedule a task to call
 126  * GNUNET_CONSENSUS_destroy() instead (if needed).
 127  *
 128  * @param consensus handle for the consensus session
 129  * @param element the element to be inserted
 130  * @param idc function called when we are done with this element and it
 131  *            is thus allowed to call GNUNET_CONSENSUS_insert() again
 132  * @param idc_cls closure for @a idc
 133  */
 134 void
 135 GNUNET_CONSENSUS_insert (struct GNUNET_CONSENSUS_Handle *consensus,
 136                          const struct GNUNET_SET_Element *element,
 137                          GNUNET_CONSENSUS_InsertDoneCallback idc,
 138                          void *idc_cls);
 139
 140
 141
 142 /**
 143  * Called when a conclusion was successful.
 144  *
 145  * @param cls
 146  */
 147 typedef void (*GNUNET_CONSENSUS_ConcludeCallback) (void *cls);
 148
 149
 150 /**
 151  * We are finished inserting new elements into the consensus;
 152  * try to conclude the consensus within a given time window.
 153  *
 154  * @param consensus consensus session
 155  * @param conclude called when the conclusion was successful
 156  * @param conclude_cls closure for the conclude callback
 157  */
 158 void
 159 GNUNET_CONSENSUS_conclude (struct GNUNET_CONSENSUS_Handle *consensus,
 160                            GNUNET_CONSENSUS_ConcludeCallback conclude,
 161                            void *conclude_cls);
 162
 163
 164 /**
 165  * Destroy a consensus handle (free all state associated with
 166  * it, no longer call any of the callbacks).
 167  *
 168  * @param consensus handle to destroy
 169  */
 170 void
 171 GNUNET_CONSENSUS_destroy (struct GNUNET_CONSENSUS_Handle *consensus);
 172
 173
 174 #if 0                           /* keep Emacsens' auto-indent happy */
 175 {
 176 #endif
 177 #ifdef __cplusplus
 178 }
 179 #endif
 180
 181 #endif
 182
 183 /** @} */  /* end of group */