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

cls	closure
element	new 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
success	GNUNET_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

cfg	configuration to use for connecting to the consensus service
num_peers	number of peers in the peers array
peers	array of peers participating in this consensus session Inclusion of the local peer is optional.
session_id	session identifier Allows a group of peers to have more than consensus session.
start	start time of the consensus, conclude should be called before the start time.
deadline	time when the consensus should have concluded
new_element_cb	callback, called when a new element is added to the set by another peer. Also called when an error occurs.
new_element_cls	closure for new_element

Returns

handle to use, NULL on error

Parameters

cfg	configuration to use for connecting to the consensus service
num_peers	number of peers in the peers array
peers	array of peers participating in this consensus session Inclusion of the local peer is optional.
session_id	session identifier Allows a group of peers to have more than consensus session.
start	start time of the consensus, conclude should be called before the start time.
deadline	time when the consensus should have concluded
new_element_cb	callback, called when a new element is added to the set by another peer
new_element_cls	closure for new_element

Returns

handle to use, NULL on error

Definition at line 196 of file consensus_api.c.

{
  struct GNUNET_CONSENSUS_Handle *consensus
    = GNUNET_new (struct GNUNET_CONSENSUS_Handle);
  struct GNUNET_MQ_MessageHandler mq_handlers[] = {
    GNUNET_MQ_hd_var_size (new_element,
                           GNUNET_MESSAGE_TYPE_CONSENSUS_CLIENT_RECEIVED_ELEMENT,
                           struct GNUNET_CONSENSUS_ElementMessage,
                           consensus),
    GNUNET_MQ_hd_fixed_size (conclude_done,
                             GNUNET_MESSAGE_TYPE_CONSENSUS_CLIENT_CONCLUDE_DONE,
                             struct GNUNET_MessageHeader,
                             consensus),
    GNUNET_MQ_handler_end ()
  };
  struct GNUNET_CONSENSUS_JoinMessage *join_msg;
  struct GNUNET_MQ_Envelope *ev;
 
  consensus->cfg = cfg;
  consensus->new_element_cb = new_element_cb;
  consensus->new_element_cls = new_element_cls;
  consensus->session_id = *session_id;
  consensus->mq = GNUNET_CLIENT_connect (cfg,
                                         "consensus",
                                         mq_handlers,
                                         &mq_error_handler,
                                         consensus);
  if (NULL == consensus->mq)
  {
    GNUNET_free (consensus);
    return NULL;
  }
  ev = GNUNET_MQ_msg_extra (join_msg,
                            (num_peers * sizeof(struct GNUNET_PeerIdentity)),
                            GNUNET_MESSAGE_TYPE_CONSENSUS_CLIENT_JOIN);
 
  join_msg->session_id = consensus->session_id;
  join_msg->start = GNUNET_TIME_absolute_hton (start);
  join_msg->deadline = GNUNET_TIME_absolute_hton (deadline);
  join_msg->num_peers = htonl (num_peers);
  GNUNET_memcpy (&join_msg[1],
                 peers,
                 num_peers * sizeof(struct GNUNET_PeerIdentity));
 
  GNUNET_MQ_send (consensus->mq, ev);
  return consensus;
}

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

consensus	handle for the consensus session
element	the element to be inserted
idc	function called when we are done with this element and it is thus allowed to call GNUNET_CONSENSUS_insert() again
idc_cls	closure for idc

Must not be called after "GNUNET_CONSENSUS_conclude".

Parameters

consensus	handle for the consensus session
element	the element to be inserted
idc	function called when we are done with this element and it is thus allowed to call GNUNET_CONSENSUS_insert again
idc_cls	closure for 'idc'

Definition at line 273 of file consensus_api.c.

{
  struct GNUNET_CONSENSUS_ElementMessage *element_msg;
  struct GNUNET_MQ_Envelope *ev;
  struct InsertDoneInfo *i;
 
  LOG (GNUNET_ERROR_TYPE_DEBUG, "inserting, size=%u\n", element->size);
 
  ev = GNUNET_MQ_msg_extra (element_msg, element->size,
                            GNUNET_MESSAGE_TYPE_CONSENSUS_CLIENT_INSERT);
 
  GNUNET_memcpy (&element_msg[1], element->data, element->size);
 
  if (NULL != idc)
  {
    i = GNUNET_new (struct InsertDoneInfo);
    i->idc = idc;
    i->cls = idc_cls;
    GNUNET_MQ_notify_sent (ev, idc_adapter, i);
  }
  GNUNET_MQ_send (consensus->mq, ev);
}

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

consensus	consensus session
conclude	called when the conclusion was successful
conclude_cls	closure 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

consensus	consensus session
conclude	called when the conclusion was successful
conclude_cls	closure for the conclude callback

Definition at line 311 of file consensus_api.c.

{
  struct GNUNET_MQ_Envelope *ev;
 
  GNUNET_assert (NULL != conclude);
  GNUNET_assert (NULL == consensus->conclude_cb);
 
  consensus->conclude_cls = conclude_cls;
  consensus->conclude_cb = conclude;
 
  ev = GNUNET_MQ_msg_header (GNUNET_MESSAGE_TYPE_CONSENSUS_CLIENT_CONCLUDE);
  GNUNET_MQ_send (consensus->mq, ev);
}

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

consensus

handle to destroy

Definition at line 335 of file consensus_api.c.

{
  if (NULL != consensus->mq)
  {
    GNUNET_MQ_destroy (consensus->mq);
    consensus->mq = NULL;
  }
  GNUNET_free (consensus);
}

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: