2 This file is part of GNUnet
3 Copyright (C) 2012 GNUnet e.V.
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.
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.
17 * @author Florian Dold
20 * Multi-peer set reconciliation
22 * @defgroup consensus Consensus service
23 * Multi-peer set reconciliation
27 #ifndef GNUNET_CONSENSUS_SERVICE_H
28 #define GNUNET_CONSENSUS_SERVICE_H
33 #if 0 /* keep Emacsens' auto-indent happy */
38 #include "gnunet_common.h"
39 #include "gnunet_time_lib.h"
40 #include "gnunet_configuration_lib.h"
41 #include "gnunet_set_service.h"
45 * Elements inserted into the consensus set by the client
46 * may not be larger than this constant, since types in
47 * the upper range are used by CONSENSUS internally.
49 #define GNUNET_CONSENSUS_ELEMENT_TYPE_USER_MAX 0xFFF0
53 * Called when a new element was received from another peer, or an error occured.
54 * May deliver duplicate values.
55 * Elements given to a consensus operation by the local peer are NOT given
59 * @param element new element, NULL on error
61 typedef void (*GNUNET_CONSENSUS_ElementCallback) (void *cls,
62 const struct GNUNET_SET_Element *element);
67 * Opaque handle for the consensus service.
69 struct GNUNET_CONSENSUS_Handle;
73 * Create a consensus session. The set being reconciled is initially
78 * @param peers array of peers participating in this consensus session
79 * Inclusion of the local peer is optional.
80 * @param session_id session identifier
81 * Allows a group of peers to have more than consensus session.
82 * @param start start time of the consensus, conclude should be called before
84 * @param deadline time when the consensus should have concluded
85 * @param new_element_cb callback, called when a new element is added to the set by
86 * another peer. Also called when an error occurs.
87 * @param new_element_cls closure for new_element
88 * @return handle to use, NULL on error
90 struct GNUNET_CONSENSUS_Handle *
91 GNUNET_CONSENSUS_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
92 unsigned int num_peers,
93 const struct GNUNET_PeerIdentity *peers,
94 const struct GNUNET_HashCode *session_id,
95 struct GNUNET_TIME_Absolute start,
96 struct GNUNET_TIME_Absolute deadline,
97 GNUNET_CONSENSUS_ElementCallback new_element_cb,
98 void *new_element_cls);
102 * Called when an insertion (transmission to consensus service, which
103 * does not imply fully consensus on this element with all other
104 * peers) was successful. May not call GNUNET_CONSENSUS_destroy();
105 * schedule a task to call GNUNET_CONSENSUS_destroy() instead (if
109 * @param success #GNUNET_OK on success, #GNUNET_SYSERR if
110 * the insertion and thus the consensus failed for good
112 typedef void (*GNUNET_CONSENSUS_InsertDoneCallback) (void *cls,
117 * Insert an element in the set being reconsiled. Only transmit changes to
118 * other peers if GNUNET_CONSENSUS_begin() has been called.
119 * Must not be called after GNUNET_CONSENSUS_conclude().
120 * May not call GNUNET_CONSENSUS_destroy(); schedule a task to call
121 * GNUNET_CONSENSUS_destroy() instead (if needed).
123 * @param consensus handle for the consensus session
124 * @param element the element to be inserted
125 * @param idc function called when we are done with this element and it
126 * is thus allowed to call GNUNET_CONSENSUS_insert() again
127 * @param idc_cls closure for @a idc
130 GNUNET_CONSENSUS_insert (struct GNUNET_CONSENSUS_Handle *consensus,
131 const struct GNUNET_SET_Element *element,
132 GNUNET_CONSENSUS_InsertDoneCallback idc,
138 * Called when a conclusion was successful.
142 typedef void (*GNUNET_CONSENSUS_ConcludeCallback) (void *cls);
146 * We are finished inserting new elements into the consensus;
147 * try to conclude the consensus within a given time window.
149 * @param consensus consensus session
150 * @param conclude called when the conclusion was successful
151 * @param conclude_cls closure for the conclude callback
154 GNUNET_CONSENSUS_conclude (struct GNUNET_CONSENSUS_Handle *consensus,
155 GNUNET_CONSENSUS_ConcludeCallback conclude,
160 * Destroy a consensus handle (free all state associated with
161 * it, no longer call any of the callbacks).
163 * @param consensus handle to destroy
166 GNUNET_CONSENSUS_destroy (struct GNUNET_CONSENSUS_Handle *consensus);
169 #if 0 /* keep Emacsens' auto-indent happy */
178 /** @} */ /* end of group */