GNUnet  0.10.x
Macros | Typedefs | Functions
Consensus service

Multi-peer set reconciliation. More...

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 54 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 66 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 117 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 147 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
cfg
num_peers
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 194 of file consensus_api.c.

References 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, GNUNET_CONSENSUS_JoinMessage::session_id, GNUNET_CONSENSUS_Handle::session_id, and GNUNET_CONSENSUS_JoinMessage::start.

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

202 {
203  struct GNUNET_CONSENSUS_Handle *consensus
205  struct GNUNET_MQ_MessageHandler mq_handlers[] = {
206  GNUNET_MQ_hd_var_size(new_element,
209  consensus),
210  GNUNET_MQ_hd_fixed_size(conclude_done,
212  struct GNUNET_MessageHeader,
213  consensus),
215  };
216  struct GNUNET_CONSENSUS_JoinMessage *join_msg;
217  struct GNUNET_MQ_Envelope *ev;
218 
219  consensus->cfg = cfg;
220  consensus->new_element_cb = new_element_cb;
221  consensus->new_element_cls = new_element_cls;
222  consensus->session_id = *session_id;
223  consensus->mq = GNUNET_CLIENT_connect(cfg,
224  "consensus",
225  mq_handlers,
227  consensus);
228  if (NULL == consensus->mq)
229  {
230  GNUNET_free(consensus);
231  return NULL;
232  }
233  ev = GNUNET_MQ_msg_extra(join_msg,
234  (num_peers * sizeof(struct GNUNET_PeerIdentity)),
236 
237  join_msg->session_id = consensus->session_id;
238  join_msg->start = GNUNET_TIME_absolute_hton(start);
239  join_msg->deadline = GNUNET_TIME_absolute_hton(deadline);
240  join_msg->num_peers = htonl(num_peers);
241  GNUNET_memcpy(&join_msg[1],
242  peers,
243  num_peers * sizeof(struct GNUNET_PeerIdentity));
244 
245  GNUNET_MQ_send(consensus->mq, ev);
246  return consensus;
247 }
void * new_element_cls
Closure for new_element_cb.
Definition: consensus_api.c:54
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:900
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...
#define GNUNET_memcpy(dst, src, n)
Call memcpy() but check for n being 0 first.
#define GNUNET_MQ_hd_fixed_size(name, code, str, ctx)
static struct GNUNET_HashCode session_id
#define GNUNET_new(type)
Allocate a struct or union of the given type.
struct GNUNET_TIME_AbsoluteNBO start
Start time for the consensus.
Definition: consensus.h:57
struct GNUNET_HashCode session_id
The (local) session identifier for the consensus session.
Definition: consensus_api.c:59
struct GNUNET_HashCode session_id
Session id of the consensus.
Definition: consensus.h:52
uint32_t num_peers
Number of peers (at the end of this message) that want to participate in the consensus.
Definition: consensus.h:47
GNUNET_CONSENSUS_ElementCallback new_element_cb
Callback for new elements.
Definition: consensus_api.c:49
#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:52
#define GNUNET_MQ_hd_var_size(name, code, str, ctx)
Message with an element.
Definition: consensus.h:71
Message handler for a specific message type.
static struct GNUNET_CONFIGURATION_Handle * cfg
Our configuration.
Definition: gnunet-arm.c:104
#define GNUNET_MESSAGE_TYPE_CONSENSUS_CLIENT_RECEIVED_ELEMENT
Sent by service when a new element is added.
Sent by the client to the service, when the client wants the service to join a consensus session...
Definition: consensus.h:37
static unsigned int num_peers
The identity of the host (wraps the signing key of the peer).
const struct GNUNET_CONFIGURATION_Handle * cfg
Configuration to use.
Definition: consensus_api.c:44
#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_JOIN
Join a consensus session.
Handle for the service.
Definition: consensus_api.c:40
Header for all communications.
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:351
struct GNUNET_MQ_Handle * mq
Message queue for the client.
Definition: consensus_api.c:84
struct GNUNET_TIME_AbsoluteNBO GNUNET_TIME_absolute_hton(struct GNUNET_TIME_Absolute a)
Convert absolute time to network byte order.
Definition: time.c:655
#define GNUNET_MQ_handler_end()
End-marker for the handlers array.
struct GNUNET_TIME_AbsoluteNBO deadline
Deadline for conclude.
Definition: consensus.h:62
#define GNUNET_free(ptr)
Wrapper around free.
static void new_element_cb(void *cls, const struct GNUNET_SET_Element *element)
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 270 of file consensus_api.c.

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 do_consensus(), insert_decrypt_element(), insert_round1_element(), and insert_round2_element().

274 {
275  struct GNUNET_CONSENSUS_ElementMessage *element_msg;
276  struct GNUNET_MQ_Envelope *ev;
277  struct InsertDoneInfo *i;
278 
279  LOG(GNUNET_ERROR_TYPE_DEBUG, "inserting, size=%llu\n", element->size);
280 
281  ev = GNUNET_MQ_msg_extra(element_msg, element->size,
283 
284  GNUNET_memcpy(&element_msg[1], element->data, element->size);
285 
286  if (NULL != idc)
287  {
288  i = GNUNET_new(struct InsertDoneInfo);
289  i->idc = idc;
290  i->cls = idc_cls;
292  }
293  GNUNET_MQ_send(consensus->mq, ev);
294 }
#define LOG(kind,...)
Definition: consensus_api.c:34
#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.
FIXME: this should not bee necessary when the API issue has been fixed.
Definition: consensus_api.c:92
const void * data
Actual data of the element.
static void idc_adapter(void *cls)
GNUNET_CONSENSUS_InsertDoneCallback idc
Definition: consensus_api.c:93
#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:52
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:772
Message with an element.
Definition: consensus.h:71
#define GNUNET_MESSAGE_TYPE_CONSENSUS_CLIENT_INSERT
Insert an element.
uint16_t size
Number of bytes in the buffer pointed to by data.
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:351
struct GNUNET_MQ_Handle * mq
Message queue for the client.
Definition: consensus_api.c:84
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
deadlinedeadline after which the conculde callback must be called
concludecalled when the conclusion was successful
conclude_clsclosure for the conclude callback

Definition at line 310 of file consensus_api.c.

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 do_consensus(), handle_client_decrypt(), handle_client_keygen(), and keygen_round1_conclude().

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

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

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

335 {
336  if (NULL != consensus->mq)
337  {
338  GNUNET_MQ_destroy(consensus->mq);
339  consensus->mq = NULL;
340  }
341  GNUNET_free(consensus);
342 }
void GNUNET_MQ_destroy(struct GNUNET_MQ_Handle *mq)
Destroy the message queue.
Definition: mq.c:821
struct GNUNET_MQ_Handle * mq
Message queue for the client.
Definition: consensus_api.c:84
#define GNUNET_free(ptr)
Wrapper around free.
Here is the call graph for this function:
Here is the caller graph for this function: