GNUnet 0.21.1
Consensus service

Multi-peer set reconciliation. More...

Collaboration diagram for Consensus service:

Macros

#define GNUNET_CONSENSUS_ELEMENT_TYPE_USER_MAX   0xFFF0
 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. More...
 

Typedefs

typedef void(* GNUNET_CONSENSUS_ElementCallback) (void *cls, const struct GNUNET_SET_Element *element)
 Called when a new element was received from another peer, or an error occurred. More...
 
typedef void(* GNUNET_CONSENSUS_InsertDoneCallback) (void *cls, int success)
 Called when an insertion (transmission to consensus service, which does not imply fully consensus on this element with all other peers) was successful. More...
 
typedef void(* GNUNET_CONSENSUS_ConcludeCallback) (void *cls)
 Called when a conclusion was successful. More...
 

Functions

struct GNUNET_CONSENSUS_HandleGNUNET_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)
 Create a consensus session. More...
 
void GNUNET_CONSENSUS_insert (struct GNUNET_CONSENSUS_Handle *consensus, const struct GNUNET_SET_Element *element, GNUNET_CONSENSUS_InsertDoneCallback idc, void *idc_cls)
 Insert an element in the set being reconsiled. More...
 
void GNUNET_CONSENSUS_conclude (struct GNUNET_CONSENSUS_Handle *consensus, GNUNET_CONSENSUS_ConcludeCallback conclude, void *conclude_cls)
 We are finished inserting new elements into the consensus; try to conclude the consensus within a given time window. More...
 
void GNUNET_CONSENSUS_destroy (struct GNUNET_CONSENSUS_Handle *consensus)
 Destroy a consensus handle (free all state associated with it, no longer call any of the callbacks). More...
 

Detailed Description

Multi-peer set reconciliation.

Macro Definition Documentation

◆ GNUNET_CONSENSUS_ELEMENT_TYPE_USER_MAX

#define GNUNET_CONSENSUS_ELEMENT_TYPE_USER_MAX   0xFFF0

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.

Definition at line 58 of file gnunet_consensus_service.h.

Typedef Documentation

◆ GNUNET_CONSENSUS_ElementCallback

typedef void(* GNUNET_CONSENSUS_ElementCallback) (void *cls, const struct GNUNET_SET_Element *element)

Called when a new element was received from another peer, or an error occurred.

May deliver duplicate values. Elements given to a consensus operation by the local peer are NOT given to this callback.

Parameters
clsclosure
elementnew element, NULL on error

Definition at line 70 of file gnunet_consensus_service.h.

◆ GNUNET_CONSENSUS_InsertDoneCallback

typedef void(* GNUNET_CONSENSUS_InsertDoneCallback) (void *cls, int success)

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).

Parameters
cls
successGNUNET_OK on success, GNUNET_SYSERR if the insertion and thus the consensus failed for good

Definition at line 121 of file gnunet_consensus_service.h.

◆ GNUNET_CONSENSUS_ConcludeCallback

typedef void(* GNUNET_CONSENSUS_ConcludeCallback) (void *cls)

Called when a conclusion was successful.

Parameters
cls

Definition at line 150 of file gnunet_consensus_service.h.

Function Documentation

◆ GNUNET_CONSENSUS_create()

struct GNUNET_CONSENSUS_Handle * 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 
)

Create a consensus session.

The set being reconciled is initially empty.

Parameters
cfgconfiguration to use for connecting to the consensus service
num_peersnumber of peers in the peers array
peersarray of peers participating in this consensus session Inclusion of the local peer is optional.
session_idsession identifier Allows a group of peers to have more than consensus session.
startstart time of the consensus, conclude should be called before the start time.
deadlinetime when the consensus should have concluded
new_element_cbcallback, called when a new element is added to the set by another peer. Also called when an error occurs.
new_element_clsclosure for new_element
Returns
handle to use, NULL on error
Parameters
cfgconfiguration to use for connecting to the consensus service
num_peersnumber of peers in the peers array
peersarray of peers participating in this consensus session Inclusion of the local peer is optional.
session_idsession identifier Allows a group of peers to have more than consensus session.
startstart time of the consensus, conclude should be called before the start time.
deadlinetime when the consensus should have concluded
new_element_cbcallback, called when a new element is added to the set by another peer
new_element_clsclosure for new_element
Returns
handle to use, NULL on error

Definition at line 196 of file consensus_api.c.

204{
205 struct GNUNET_CONSENSUS_Handle *consensus
207 struct GNUNET_MQ_MessageHandler mq_handlers[] = {
208 GNUNET_MQ_hd_var_size (new_element,
211 consensus),
212 GNUNET_MQ_hd_fixed_size (conclude_done,
215 consensus),
217 };
218 struct GNUNET_CONSENSUS_JoinMessage *join_msg;
219 struct GNUNET_MQ_Envelope *ev;
220
221 consensus->cfg = cfg;
222 consensus->new_element_cb = new_element_cb;
223 consensus->new_element_cls = new_element_cls;
224 consensus->session_id = *session_id;
225 consensus->mq = GNUNET_CLIENT_connect (cfg,
226 "consensus",
227 mq_handlers,
229 consensus);
230 if (NULL == consensus->mq)
231 {
232 GNUNET_free (consensus);
233 return NULL;
234 }
235 ev = GNUNET_MQ_msg_extra (join_msg,
236 (num_peers * sizeof(struct GNUNET_PeerIdentity)),
238
239 join_msg->session_id = consensus->session_id;
241 join_msg->deadline = GNUNET_TIME_absolute_hton (deadline);
242 join_msg->num_peers = htonl (num_peers);
243 GNUNET_memcpy (&join_msg[1],
244 peers,
245 num_peers * sizeof(struct GNUNET_PeerIdentity));
246
247 GNUNET_MQ_send (consensus->mq, ev);
248 return consensus;
249}
static void mq_error_handler(void *cls, enum GNUNET_MQ_Error error)
Generic error handler, called with the appropriate error code and the same closure specified at the c...
static int start
Set if we are to start default services (including ARM).
Definition: gnunet-arm.c:39
static struct GNUNET_CONFIGURATION_Handle * cfg
Our configuration.
Definition: gnunet-arm.c:109
struct GNUNET_CONTAINER_MultiPeerMap * peers
Map from PIDs to struct CadetPeer entries.
static unsigned int num_peers
Number of peers.
struct GNUNET_MQ_Handle * GNUNET_CLIENT_connect(const struct GNUNET_CONFIGURATION_Handle *cfg, const char *service_name, const struct GNUNET_MQ_MessageHandler *handlers, GNUNET_MQ_ErrorHandler error_handler, void *error_handler_cls)
Create a message queue to connect to a GNUnet service.
Definition: client.c:1057
#define GNUNET_memcpy(dst, src, n)
Call memcpy() but check for n being 0 first.
#define GNUNET_new(type)
Allocate a struct or union of the given type.
#define GNUNET_free(ptr)
Wrapper around free.
void GNUNET_MQ_send(struct GNUNET_MQ_Handle *mq, struct GNUNET_MQ_Envelope *ev)
Send a message with the given message queue.
Definition: mq.c:304
#define GNUNET_MQ_handler_end()
End-marker for the handlers array.
#define GNUNET_MQ_msg_extra(mvar, esize, type)
Allocate an envelope, with extra space allocated after the space needed by the message struct.
Definition: gnunet_mq_lib.h:63
#define GNUNET_MQ_hd_var_size(name, code, str, ctx)
#define GNUNET_MQ_hd_fixed_size(name, code, str, ctx)
#define GNUNET_MESSAGE_TYPE_CONSENSUS_CLIENT_JOIN
Join a consensus session.
#define GNUNET_MESSAGE_TYPE_CONSENSUS_CLIENT_CONCLUDE_DONE
Sent by service to client in order to signal a completed consensus conclusion.
#define GNUNET_MESSAGE_TYPE_CONSENSUS_CLIENT_RECEIVED_ELEMENT
Sent by service when a new element is added.
struct GNUNET_TIME_AbsoluteNBO GNUNET_TIME_absolute_hton(struct GNUNET_TIME_Absolute a)
Convert absolute time to network byte order.
Definition: time.c:638
Message with an element.
Definition: consensus.h:73
Handle for the service.
Definition: consensus_api.c:40
void * new_element_cls
Closure for new_element_cb.
Definition: consensus_api.c:54
GNUNET_CONSENSUS_ElementCallback new_element_cb
Callback for new elements.
Definition: consensus_api.c:49
struct GNUNET_HashCode session_id
The (local) session identifier for the consensus session.
Definition: consensus_api.c:59
struct GNUNET_MQ_Handle * mq
Message queue for the client.
Definition: consensus_api.c:84
const struct GNUNET_CONFIGURATION_Handle * cfg
Configuration to use.
Definition: consensus_api.c:44
Sent by the client to the service, when the client wants the service to join a consensus session.
Definition: consensus.h:38
struct GNUNET_HashCode session_id
Session id of the consensus.
Definition: consensus.h:53
struct GNUNET_TIME_AbsoluteNBO deadline
Deadline for conclude.
Definition: consensus.h:63
uint32_t num_peers
Number of peers (at the end of this message) that want to participate in the consensus.
Definition: consensus.h:48
struct GNUNET_TIME_AbsoluteNBO start
Start time for the consensus.
Definition: consensus.h:58
Message handler for a specific message type.
Header for all communications.
The identity of the host (wraps the signing key of the peer).

References cfg, GNUNET_CONSENSUS_Handle::cfg, GNUNET_CONSENSUS_JoinMessage::deadline, GNUNET_CLIENT_connect(), GNUNET_free, GNUNET_memcpy, GNUNET_MESSAGE_TYPE_CONSENSUS_CLIENT_CONCLUDE_DONE, GNUNET_MESSAGE_TYPE_CONSENSUS_CLIENT_JOIN, GNUNET_MESSAGE_TYPE_CONSENSUS_CLIENT_RECEIVED_ELEMENT, GNUNET_MQ_handler_end, GNUNET_MQ_hd_fixed_size, GNUNET_MQ_hd_var_size, GNUNET_MQ_msg_extra, GNUNET_MQ_send(), GNUNET_new, GNUNET_TIME_absolute_hton(), GNUNET_CONSENSUS_Handle::mq, mq_error_handler(), GNUNET_CONSENSUS_Handle::new_element_cb, GNUNET_CONSENSUS_Handle::new_element_cls, GNUNET_CONSENSUS_JoinMessage::num_peers, num_peers, peers, GNUNET_CONSENSUS_JoinMessage::session_id, GNUNET_CONSENSUS_Handle::session_id, start, and GNUNET_CONSENSUS_JoinMessage::start.

Referenced by handle_client_decrypt(), handle_client_keygen(), and keygen_round1_conclude().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ GNUNET_CONSENSUS_insert()

void GNUNET_CONSENSUS_insert ( struct GNUNET_CONSENSUS_Handle consensus,
const struct GNUNET_SET_Element element,
GNUNET_CONSENSUS_InsertDoneCallback  idc,
void *  idc_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 (if needed).

Parameters
consensushandle for the consensus session
elementthe element to be inserted
idcfunction called when we are done with this element and it is thus allowed to call GNUNET_CONSENSUS_insert() again
idc_clsclosure for idc

Must not be called after "GNUNET_CONSENSUS_conclude".

Parameters
consensushandle for the consensus session
elementthe element to be inserted
idcfunction called when we are done with this element and it is thus allowed to call GNUNET_CONSENSUS_insert again
idc_clsclosure for 'idc'

Definition at line 273 of file consensus_api.c.

277{
278 struct GNUNET_CONSENSUS_ElementMessage *element_msg;
279 struct GNUNET_MQ_Envelope *ev;
280 struct InsertDoneInfo *i;
281
282 LOG (GNUNET_ERROR_TYPE_DEBUG, "inserting, size=%u\n", element->size);
283
284 ev = GNUNET_MQ_msg_extra (element_msg, element->size,
286
287 GNUNET_memcpy (&element_msg[1], element->data, element->size);
288
289 if (NULL != idc)
290 {
291 i = GNUNET_new (struct InsertDoneInfo);
292 i->idc = idc;
293 i->cls = idc_cls;
295 }
296 GNUNET_MQ_send (consensus->mq, ev);
297}
static void idc_adapter(void *cls)
#define LOG(kind,...)
Definition: consensus_api.c:33
@ GNUNET_ERROR_TYPE_DEBUG
void GNUNET_MQ_notify_sent(struct GNUNET_MQ_Envelope *ev, GNUNET_SCHEDULER_TaskCallback cb, void *cb_cls)
Call a callback once the envelope has been sent, that is, sending it can not be canceled anymore.
Definition: mq.c:638
#define GNUNET_MESSAGE_TYPE_CONSENSUS_CLIENT_INSERT
Insert an element.
uint16_t size
Number of bytes in the buffer pointed to by data.
const void * data
Actual data of the element.
FIXME: this should not bee necessary when the API issue has been fixed.
Definition: consensus_api.c:93
GNUNET_CONSENSUS_InsertDoneCallback idc
Definition: consensus_api.c:94

References InsertDoneInfo::cls, GNUNET_SET_Element::data, GNUNET_ERROR_TYPE_DEBUG, GNUNET_memcpy, GNUNET_MESSAGE_TYPE_CONSENSUS_CLIENT_INSERT, GNUNET_MQ_msg_extra, GNUNET_MQ_notify_sent(), GNUNET_MQ_send(), GNUNET_new, InsertDoneInfo::idc, idc_adapter(), LOG, GNUNET_CONSENSUS_Handle::mq, and GNUNET_SET_Element::size.

Referenced by insert_decrypt_element(), insert_round1_element(), and insert_round2_element().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ GNUNET_CONSENSUS_conclude()

void GNUNET_CONSENSUS_conclude ( struct GNUNET_CONSENSUS_Handle consensus,
GNUNET_CONSENSUS_ConcludeCallback  conclude,
void *  conclude_cls 
)

We are finished inserting new elements into the consensus; try to conclude the consensus within a given time window.

Parameters
consensusconsensus session
concludecalled when the conclusion was successful
conclude_clsclosure for the conclude callback

We are finished inserting new elements into the consensus; try to conclude the consensus within a given time window.

After conclude has been called, no further elements may be inserted by the client.

Parameters
consensusconsensus session
concludecalled when the conclusion was successful
conclude_clsclosure for the conclude callback

Definition at line 311 of file consensus_api.c.

314{
315 struct GNUNET_MQ_Envelope *ev;
316
317 GNUNET_assert (NULL != conclude);
318 GNUNET_assert (NULL == consensus->conclude_cb);
319
320 consensus->conclude_cls = conclude_cls;
321 consensus->conclude_cb = conclude;
322
324 GNUNET_MQ_send (consensus->mq, ev);
325}
#define GNUNET_assert(cond)
Use this for fatal errors that cannot be handled.
#define GNUNET_MQ_msg_header(type)
Allocate a GNUNET_MQ_Envelope, where the message only consists of a header.
Definition: gnunet_mq_lib.h:87
#define GNUNET_MESSAGE_TYPE_CONSENSUS_CLIENT_CONCLUDE
Sent by client to service in order to start the consensus conclusion.
GNUNET_CONSENSUS_ConcludeCallback conclude_cb
Called when the conclude operation finishes or fails.
Definition: consensus_api.c:69
void * conclude_cls
Closure for the conclude_cb callback.
Definition: consensus_api.c:74

References GNUNET_CONSENSUS_Handle::conclude_cb, GNUNET_CONSENSUS_Handle::conclude_cls, GNUNET_assert, GNUNET_MESSAGE_TYPE_CONSENSUS_CLIENT_CONCLUDE, GNUNET_MQ_msg_header, GNUNET_MQ_send(), and GNUNET_CONSENSUS_Handle::mq.

Referenced by handle_client_decrypt(), handle_client_keygen(), and keygen_round1_conclude().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ GNUNET_CONSENSUS_destroy()

void GNUNET_CONSENSUS_destroy ( struct GNUNET_CONSENSUS_Handle consensus)

Destroy a consensus handle (free all state associated with it, no longer call any of the callbacks).

Parameters
consensushandle to destroy

Definition at line 335 of file consensus_api.c.

336{
337 if (NULL != consensus->mq)
338 {
339 GNUNET_MQ_destroy (consensus->mq);
340 consensus->mq = NULL;
341 }
342 GNUNET_free (consensus);
343}
void GNUNET_MQ_destroy(struct GNUNET_MQ_Handle *mq)
Destroy the message queue.
Definition: mq.c:683

References GNUNET_free, GNUNET_MQ_destroy(), and GNUNET_CONSENSUS_Handle::mq.

Referenced by decrypt_conclude(), decrypt_session_destroy(), keygen_round1_conclude(), keygen_round2_conclude(), and keygen_session_destroy().

Here is the call graph for this function:
Here is the caller graph for this function: