GNUnet  0.11.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 146 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 197 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().

205 {
206  struct GNUNET_CONSENSUS_Handle *consensus
208  struct GNUNET_MQ_MessageHandler mq_handlers[] = {
209  GNUNET_MQ_hd_var_size (new_element,
212  consensus),
213  GNUNET_MQ_hd_fixed_size (conclude_done,
215  struct GNUNET_MessageHeader,
216  consensus),
218  };
219  struct GNUNET_CONSENSUS_JoinMessage *join_msg;
220  struct GNUNET_MQ_Envelope *ev;
221 
222  consensus->cfg = cfg;
223  consensus->new_element_cb = new_element_cb;
224  consensus->new_element_cls = new_element_cls;
225  consensus->session_id = *session_id;
226  consensus->mq = GNUNET_CLIENT_connect (cfg,
227  "consensus",
228  mq_handlers,
230  consensus);
231  if (NULL == consensus->mq)
232  {
233  GNUNET_free (consensus);
234  return NULL;
235  }
236  ev = GNUNET_MQ_msg_extra (join_msg,
237  (num_peers * sizeof(struct GNUNET_PeerIdentity)),
239 
240  join_msg->session_id = consensus->session_id;
241  join_msg->start = GNUNET_TIME_absolute_hton (start);
242  join_msg->deadline = GNUNET_TIME_absolute_hton (deadline);
243  join_msg->num_peers = htonl (num_peers);
244  GNUNET_memcpy (&join_msg[1],
245  peers,
246  num_peers * sizeof(struct GNUNET_PeerIdentity));
247 
248  GNUNET_MQ_send (consensus->mq, ev);
249  return consensus;
250 }
void * new_element_cls
Closure for new_element_cb.
Definition: consensus_api.c:55
static const struct GNUNET_CONFIGURATION_Handle * cfg
Configuration we are using.
Definition: gnunet-abd.c:36
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
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:58
struct GNUNET_HashCode session_id
The (local) session identifier for the consensus session.
Definition: consensus_api.c:60
struct GNUNET_HashCode session_id
Session id of the consensus.
Definition: consensus.h:53
uint32_t num_peers
Number of peers (at the end of this message) that want to participate in the consensus.
Definition: consensus.h:48
GNUNET_CONSENSUS_ElementCallback new_element_cb
Callback for new elements.
Definition: consensus_api.c:50
#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:72
Message handler for a specific message type.
#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:45
#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:353
struct GNUNET_MQ_Handle * mq
Message queue for the client.
Definition: consensus_api.c:85
struct GNUNET_TIME_AbsoluteNBO GNUNET_TIME_absolute_hton(struct GNUNET_TIME_Absolute a)
Convert absolute time to network byte order.
Definition: time.c:657
#define GNUNET_MQ_handler_end()
End-marker for the handlers array.
struct GNUNET_TIME_AbsoluteNBO deadline
Deadline for conclude.
Definition: consensus.h:63
#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 274 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().

278 {
279  struct GNUNET_CONSENSUS_ElementMessage *element_msg;
280  struct GNUNET_MQ_Envelope *ev;
281  struct InsertDoneInfo *i;
282 
283  LOG (GNUNET_ERROR_TYPE_DEBUG, "inserting, size=%llu\n", element->size);
284 
285  ev = GNUNET_MQ_msg_extra (element_msg, element->size,
287 
288  GNUNET_memcpy (&element_msg[1], element->data, element->size);
289 
290  if (NULL != idc)
291  {
292  i = GNUNET_new (struct InsertDoneInfo);
293  i->idc = idc;
294  i->cls = idc_cls;
296  }
297  GNUNET_MQ_send (consensus->mq, ev);
298 }
#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:93
const void * data
Actual data of the element.
static void idc_adapter(void *cls)
GNUNET_CONSENSUS_InsertDoneCallback idc
Definition: consensus_api.c:95
#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:774
Message with an element.
Definition: consensus.h:72
#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:353
struct GNUNET_MQ_Handle * mq
Message queue for the client.
Definition: consensus_api.c:85
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 314 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().

317 {
318  struct GNUNET_MQ_Envelope *ev;
319 
320  GNUNET_assert (NULL != conclude);
321  GNUNET_assert (NULL == consensus->conclude_cb);
322 
323  consensus->conclude_cls = conclude_cls;
324  consensus->conclude_cb = conclude;
325 
327  GNUNET_MQ_send (consensus->mq, ev);
328 }
GNUNET_CONSENSUS_ConcludeCallback conclude_cb
Called when the conclude operation finishes or fails.
Definition: consensus_api.c:70
#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:75
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:353
struct GNUNET_MQ_Handle * mq
Message queue for the client.
Definition: consensus_api.c:85
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 338 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().

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