[GNUnet-SVN] r24982 - gnunet/src/include

[gnunet]

Author: grothoff
Date: 2012-11-15 14:38:22 +0100 (Thu, 15 Nov 2012)
New Revision: 24982

Modified:
   gnunet/src/include/gnunet_consensus_service.h
Log:
polishing consensus API

Modified: gnunet/src/include/gnunet_consensus_service.h
===================================================================
--- gnunet/src/include/gnunet_consensus_service.h       2012-11-15 12:46:25 UTC 
(rev 24981)
+++ gnunet/src/include/gnunet_consensus_service.h       2012-11-15 13:38:22 UTC 
(rev 24982)
@@ -41,22 +41,31 @@
 
 
 /**
- * Called when a new element was received from another peer.
+ * Called when a new element was received from another peer; elements
+ * given to a consensus operation by the local peer are NOT given
+ * to this callback.
  *
- * @return GNUNET_YES to keep the new value, GNUNET_NO to discard it
+ * @param cls closure
+ * @param element_size will match the size given to GNUNET_CONSENSUS_create
+ * @param element
  */
-typedef int (*GNUNET_CONSENSUS_NewElementCallback) (void *cls,
-                                           struct GNUNET_PeerIdentity *source,
-                                           uint8_t *new_data);
+typedef void (*GNUNET_CONSENSUS_NewElementCallback) (void *cls,
+                                                    size_t element_size,
+                                                    const void *element);
 
 
 /**
  * Called when a conclusion was successful.
  *
- * TODO: A way to get to the set elements at the point of conclusion
+ * @param cls
+ * @param num_peers_in_consensus
+ * @param peers_in_consensus
  */
-typedef void (*GNUNET_CONSENSUS_ConcludeCallback) (void *cls, int success);
+typedef void (*GNUNET_CONSENSUS_ConcludeCallback) (void *cls, 
+                                                  unsigned int 
num_peers_in_consensus,
+                                                  cnost struct 
GNUNET_PeerIdentity *peers_in_consensus);
 
+
 /**
  * Opaque handle for the consensus service.
  */
@@ -64,15 +73,11 @@
 
 
 /**
- * Opaque handle for the consensus service.
- */
-struct GNUNET_CONSENSUS_ConcludeHandle;
-
-
-/**
  * Create a consensus session.
  *
- * @param peers zero-terminated list of peers participating in this consensus 
session
+ * @param cfg
+ * @param num_peers
+ * @param peers array of peers participating in this consensus session
  * @param session_id session identifier
  *                   Allows a group of peers to have more than consensus 
session.
  * @param element_size size of the elements in the reconciled set in bytes
@@ -83,55 +88,58 @@
  * @return handle to use
  */
 struct GNUNET_CONSENSUS_Handle *
-GNUNET_CONSENSUS_create (struct GNUNET_PeerIdentity *peers,
-                         uint32_t session_id,
-                         int element_size,
-                         uint8_t **initial_elements,
+GNUNET_CONSENSUS_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
+                        unsigned int num_peers,
+                        const struct GNUNET_PeerIdentity *peers,
+                         const struct GNUNET_HashCode *session_id,
+                         size_t element_size,
+                         const void **initial_elements,
                          GNUNET_CONSENSUS_NewElementCallback new_element,
-                         void *cls);
+                         void *new_element_cls);
 
 
+
 /**
- * Try to reach a short-term consensus with all other peers in the consensus 
session.
+ * Insert an element in the set being reconsiled.  Must not be called after
+ * "GNUNET_CONSENSUS_conclude".
  *
- * @param consensus consensus session
- * @param timeout timeout after which the conculde callback
- *                will be called with success=GNUNET_NO
- * @param conclude called when the conclusion was successful
- * @param cls closure for the conclude callback
- *
+ * @param consensus handle for the consensus session
+ * @param element_size must match element size from GNUNET_CONSENSUS_create
+ * @param element the element to be inserted
  */
-struct GNUNET_CONSENSUS_ConcludeHandle
-GNUNET_CONSENSUS_conclude(struct GNUNET_CONSENSUS_Handle *consensus,
-                          struct GNUNET_TIME_Relative timeout,
-                          GNUNET_CONSENSUS_ConcludeCallback conclude,
-                          void *cls);
+void
+GNUNET_CONSENSUS_insert (struct GNUNET_CONSENSUS_Handle *consensus,
+                        size_t element_size,
+                        const void *element);
 
 
 /**
- * Insert an element in the set being reconsiled.
+ * We are finished inserting new elements into the consensus;
+ * try to conclude the consensus within a given time window.
  *
- * @param handle handle for the consensus session
- * @param element the element to be inserted
- *
+ * @param consensus consensus session
+ * @param timeout timeout after which the conculde callback
+ *                must be called
+ * @param conclude called when the conclusion was successful
+ * @param conclude_cls closure for the conclude callback
  */
 void
-GNUNET_CONSENSUS_insert(struct GNUNET_CONSENSUS_Handle, uint8_t *element);
+GNUNET_CONSENSUS_conclude (struct GNUNET_CONSENSUS_Handle *consensus,
+                          struct GNUNET_TIME_Relative timeout,
+                          GNUNET_CONSENSUS_ConcludeCallback conclude,
+                          void *conclude_cls);
 
 
 /**
  * Destroy a consensus handle (free all state associated with
- * it).
+ * it, no longer call any of the callbacks).
  *
- * @param h consensus handle to destroy
+ * @param consensus handle to destroy
  */
 void
-GNUNET_CONSENSUS_destroy (struct GNUNET_CONSENSUS_Handle *h);
+GNUNET_CONSENSUS_destroy (struct GNUNET_CONSENSUS_Handle *consensus);
 
 
-
-
-
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
 #endif