diff options
author | Christian Grothoff <christian@grothoff.org> | 2012-11-15 13:38:22 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2012-11-15 13:38:22 +0000 |
commit | bddfc596973e41bd3ca02791f77122463133464a (patch) | |
tree | a856511af456099d5236824760e9ab84e1808fd0 | |
parent | f71b28f067caf23942411128d1ceaee2550d022c (diff) | |
download | gnunet-bddfc596973e41bd3ca02791f77122463133464a.tar.gz gnunet-bddfc596973e41bd3ca02791f77122463133464a.zip |
polishing consensus API
-rw-r--r-- | src/include/gnunet_consensus_service.h | 92 |
1 files changed, 50 insertions, 42 deletions
diff --git a/src/include/gnunet_consensus_service.h b/src/include/gnunet_consensus_service.h index f20e0ca54..ade7a03ab 100644 --- a/src/include/gnunet_consensus_service.h +++ b/src/include/gnunet_consensus_service.h | |||
@@ -41,38 +41,43 @@ extern "C" | |||
41 | 41 | ||
42 | 42 | ||
43 | /** | 43 | /** |
44 | * Called when a new element was received from another peer. | 44 | * Called when a new element was received from another peer; elements |
45 | * given to a consensus operation by the local peer are NOT given | ||
46 | * to this callback. | ||
45 | * | 47 | * |
46 | * @return GNUNET_YES to keep the new value, GNUNET_NO to discard it | 48 | * @param cls closure |
49 | * @param element_size will match the size given to GNUNET_CONSENSUS_create | ||
50 | * @param element | ||
47 | */ | 51 | */ |
48 | typedef int (*GNUNET_CONSENSUS_NewElementCallback) (void *cls, | 52 | typedef void (*GNUNET_CONSENSUS_NewElementCallback) (void *cls, |
49 | struct GNUNET_PeerIdentity *source, | 53 | size_t element_size, |
50 | uint8_t *new_data); | 54 | const void *element); |
51 | 55 | ||
52 | 56 | ||
53 | /** | 57 | /** |
54 | * Called when a conclusion was successful. | 58 | * Called when a conclusion was successful. |
55 | * | 59 | * |
56 | * TODO: A way to get to the set elements at the point of conclusion | 60 | * @param cls |
61 | * @param num_peers_in_consensus | ||
62 | * @param peers_in_consensus | ||
57 | */ | 63 | */ |
58 | typedef void (*GNUNET_CONSENSUS_ConcludeCallback) (void *cls, int success); | 64 | typedef void (*GNUNET_CONSENSUS_ConcludeCallback) (void *cls, |
59 | 65 | unsigned int num_peers_in_consensus, | |
60 | /** | 66 | cnost struct GNUNET_PeerIdentity *peers_in_consensus); |
61 | * Opaque handle for the consensus service. | ||
62 | */ | ||
63 | struct GNUNET_CONSENSUS_Handle; | ||
64 | 67 | ||
65 | 68 | ||
66 | /** | 69 | /** |
67 | * Opaque handle for the consensus service. | 70 | * Opaque handle for the consensus service. |
68 | */ | 71 | */ |
69 | struct GNUNET_CONSENSUS_ConcludeHandle; | 72 | struct GNUNET_CONSENSUS_Handle; |
70 | 73 | ||
71 | 74 | ||
72 | /** | 75 | /** |
73 | * Create a consensus session. | 76 | * Create a consensus session. |
74 | * | 77 | * |
75 | * @param peers zero-terminated list of peers participating in this consensus session | 78 | * @param cfg |
79 | * @param num_peers | ||
80 | * @param peers array of peers participating in this consensus session | ||
76 | * @param session_id session identifier | 81 | * @param session_id session identifier |
77 | * Allows a group of peers to have more than consensus session. | 82 | * Allows a group of peers to have more than consensus session. |
78 | * @param element_size size of the elements in the reconciled set in bytes | 83 | * @param element_size size of the elements in the reconciled set in bytes |
@@ -83,53 +88,56 @@ struct GNUNET_CONSENSUS_ConcludeHandle; | |||
83 | * @return handle to use | 88 | * @return handle to use |
84 | */ | 89 | */ |
85 | struct GNUNET_CONSENSUS_Handle * | 90 | struct GNUNET_CONSENSUS_Handle * |
86 | GNUNET_CONSENSUS_create (struct GNUNET_PeerIdentity *peers, | 91 | GNUNET_CONSENSUS_create (const struct GNUNET_CONFIGURATION_Handle *cfg, |
87 | uint32_t session_id, | 92 | unsigned int num_peers, |
88 | int element_size, | 93 | const struct GNUNET_PeerIdentity *peers, |
89 | uint8_t **initial_elements, | 94 | const struct GNUNET_HashCode *session_id, |
95 | size_t element_size, | ||
96 | const void **initial_elements, | ||
90 | GNUNET_CONSENSUS_NewElementCallback new_element, | 97 | GNUNET_CONSENSUS_NewElementCallback new_element, |
91 | void *cls); | 98 | void *new_element_cls); |
99 | |||
92 | 100 | ||
93 | 101 | ||
94 | /** | 102 | /** |
95 | * Try to reach a short-term consensus with all other peers in the consensus session. | 103 | * Insert an element in the set being reconsiled. Must not be called after |
96 | * | 104 | * "GNUNET_CONSENSUS_conclude". |
97 | * @param consensus consensus session | ||
98 | * @param timeout timeout after which the conculde callback | ||
99 | * will be called with success=GNUNET_NO | ||
100 | * @param conclude called when the conclusion was successful | ||
101 | * @param cls closure for the conclude callback | ||
102 | * | 105 | * |
106 | * @param consensus handle for the consensus session | ||
107 | * @param element_size must match element size from GNUNET_CONSENSUS_create | ||
108 | * @param element the element to be inserted | ||
103 | */ | 109 | */ |
104 | struct GNUNET_CONSENSUS_ConcludeHandle | 110 | void |
105 | GNUNET_CONSENSUS_conclude(struct GNUNET_CONSENSUS_Handle *consensus, | 111 | GNUNET_CONSENSUS_insert (struct GNUNET_CONSENSUS_Handle *consensus, |
106 | struct GNUNET_TIME_Relative timeout, | 112 | size_t element_size, |
107 | GNUNET_CONSENSUS_ConcludeCallback conclude, | 113 | const void *element); |
108 | void *cls); | ||
109 | 114 | ||
110 | 115 | ||
111 | /** | 116 | /** |
112 | * Insert an element in the set being reconsiled. | 117 | * We are finished inserting new elements into the consensus; |
113 | * | 118 | * try to conclude the consensus within a given time window. |
114 | * @param handle handle for the consensus session | ||
115 | * @param element the element to be inserted | ||
116 | * | 119 | * |
120 | * @param consensus consensus session | ||
121 | * @param timeout timeout after which the conculde callback | ||
122 | * must be called | ||
123 | * @param conclude called when the conclusion was successful | ||
124 | * @param conclude_cls closure for the conclude callback | ||
117 | */ | 125 | */ |
118 | void | 126 | void |
119 | GNUNET_CONSENSUS_insert(struct GNUNET_CONSENSUS_Handle, uint8_t *element); | 127 | GNUNET_CONSENSUS_conclude (struct GNUNET_CONSENSUS_Handle *consensus, |
128 | struct GNUNET_TIME_Relative timeout, | ||
129 | GNUNET_CONSENSUS_ConcludeCallback conclude, | ||
130 | void *conclude_cls); | ||
120 | 131 | ||
121 | 132 | ||
122 | /** | 133 | /** |
123 | * Destroy a consensus handle (free all state associated with | 134 | * Destroy a consensus handle (free all state associated with |
124 | * it). | 135 | * it, no longer call any of the callbacks). |
125 | * | 136 | * |
126 | * @param h consensus handle to destroy | 137 | * @param consensus handle to destroy |
127 | */ | 138 | */ |
128 | void | 139 | void |
129 | GNUNET_CONSENSUS_destroy (struct GNUNET_CONSENSUS_Handle *h); | 140 | GNUNET_CONSENSUS_destroy (struct GNUNET_CONSENSUS_Handle *consensus); |
130 | |||
131 | |||
132 | |||
133 | 141 | ||
134 | 142 | ||
135 | #if 0 /* keep Emacsens' auto-indent happy */ | 143 | #if 0 /* keep Emacsens' auto-indent happy */ |