2 This file is part of GNUnet
3 (C) 2013 Christian Grothoff (and other contributing authors)
5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version.
10 GNUnet is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
22 * @file set/gnunet-service-set.h
23 * @brief common components for the implementation the different set operations
24 * @author Florian Dold
25 * @author Christian Grothoff
27 #ifndef GNUNET_SERVICE_SET_H_PRIVATE
28 #define GNUNET_SERVICE_SET_H_PRIVATE
31 #include "gnunet_util_lib.h"
32 #include "gnunet_protocols.h"
33 #include "gnunet_applications.h"
34 #include "gnunet_core_service.h"
35 #include "gnunet_cadet_service.h"
36 #include "gnunet_set_service.h"
41 * Implementation-specific set state. Used as opaque pointer, and
42 * specified further in the respective implementation.
47 * Implementation-specific set operation. Used as opaque pointer, and
48 * specified further in the respective implementation.
50 struct OperationState;
53 * A set that supports a specific operation with other peers.
58 * Information about an element element in the set. All elements are
59 * stored in a hash-table from their hash-code to their 'struct
60 * Element', so that the remove and add operations are reasonably
66 * Operation context used to execute a set operation.
72 * Detail information about an operation.
74 struct OperationSpecification
78 * The remove peer we evaluate the operation with.
80 struct GNUNET_PeerIdentity peer;
83 * Application ID for the operation, used to distinguish
84 * multiple operations of the same type with the same peer.
86 struct GNUNET_HashCode app_id;
89 * Context message, may be NULL.
91 struct GNUNET_MessageHeader *context_msg;
94 * Set associated with the operation, NULL until the spec has been
95 * associated with a set.
100 * Salt to use for the operation.
105 * Remote peers element count
107 uint32_t remote_element_count;
110 * ID used to identify an operation between service and client
112 uint32_t client_request_id;
115 * The type of the operation.
117 enum GNUNET_SET_OperationType operation;
120 * When are elements sent to the client, and which elements are sent?
122 enum GNUNET_SET_ResultMode result_mode;
127 * Signature of functions that create the implementation-specific
128 * state for a set supporting a specific operation.
130 * @return a set state specific to the supported operation
132 typedef struct SetState *
133 (*CreateImpl) (void);
137 * Signature of functions that implement the add/remove functionality
138 * for a set supporting a specific operation.
140 * @param set implementation-specific set state
141 * @param ee element message from the client
144 (*AddRemoveImpl) (struct SetState *state,
145 struct ElementEntry *ee);
149 * Signature of functions that handle disconnection of the remote
152 * @param op the set operation, contains implementation-specific data
155 (*PeerDisconnectImpl) (struct Operation *op);
159 * Signature of functions that implement the destruction of the
160 * implementation-specific set state.
162 * @param state the set state, contains implementation-specific data
165 (*DestroySetImpl) (struct SetState *state);
169 * Signature of functions that implement the creation of set operations
170 * (currently "evaluate" and "accept").
172 * @param op operation that is created, should be initialized by the implementation
175 (*OpCreateImpl) (struct Operation *op);
179 * Signature of functions that implement the message handling for
180 * the different set operations.
182 * @param op operation state
183 * @param msg received message
184 * @return #GNUNET_OK on success, #GNUNET_SYSERR to
185 * destroy the operation and the tunnel
188 (*MsgHandlerImpl) (struct Operation *op,
189 const struct GNUNET_MessageHeader *msg);
193 * Signature of functions that implement operation cancellation
195 * @param op operation state
198 (*CancelImpl) (struct Operation *op);
202 * Dispatch table for a specific set operation. Every set operation
203 * has to implement the callback in this struct.
208 * Callback for the set creation.
213 * Callback for element insertion
218 * Callback for element removal.
220 AddRemoveImpl remove;
223 * Callback for accepting a set operation request
228 * Callback for starting evaluation with a remote peer.
230 OpCreateImpl evaluate;
233 * Callback for destruction of the set state.
235 DestroySetImpl destroy_set;
238 * Callback for handling operation-specific messages.
240 MsgHandlerImpl msg_handler;
243 * Callback for handling the remote peer's disconnect.
245 PeerDisconnectImpl peer_disconnect;
248 * Callback for canceling an operation by its ID.
255 * Information about an element element in the set. All elements are
256 * stored in a hash-table from their hash-code to their `struct
257 * Element`, so that the remove and add operations are reasonably
263 * The actual element. The data for the element
264 * should be allocated at the end of this struct.
266 struct GNUNET_SET_Element element;
269 * Hash of the element. For set union: Will be used to derive the
270 * different IBF keys for different salts.
272 struct GNUNET_HashCode element_hash;
275 * Generation the element was added by the client.
276 * Operations of earlier generations will not consider the element.
278 unsigned int generation_added;
281 * Generation the element was removed by the client.
282 * Operations of later generations will not consider the element.
283 * Only valid if @e removed is #GNUNET_YES.
285 unsigned int generation_removed;
288 * #GNUNET_YES if the element has been removed in some generation.
293 * #GNUNET_YES if the element is a remote element, and does not belong
294 * to the operation's set.
301 * Operation context used to execute a set operation.
306 * V-Table for the operation belonging to the tunnel contest.
308 * Used for all operation specific operations after receiving the ops request
310 const struct SetVT *vt;
313 * Tunnel to the peer.
315 struct GNUNET_CADET_Channel *channel;
318 * Message queue for the tunnel.
320 struct GNUNET_MQ_Handle *mq;
323 * Detail information about the set operation, including the set to
324 * use. When 'spec' is NULL, the operation is not yet entirely
327 struct OperationSpecification *spec;
330 * Operation-specific operation state.
332 struct OperationState *state;
335 * Evaluate operations are held in a linked list.
337 struct Operation *next;
340 * Evaluate operations are held in a linked list.
342 struct Operation *prev;
345 * #GNUNET_YES if this is not a "real" set operation yet, and we still
346 * need to wait for the other peer to give us more details.
351 * Generation in which the operation handle
354 unsigned int generation_created;
357 * Set to #GNUNET_YES if the set service should not free the
358 * operation, as it is still needed (e.g. in some scheduled task).
365 * A set that supports a specific operation with other peers.
371 * Sets are held in a doubly linked list (in `sets_head` and `sets_tail`).
376 * Sets are held in a doubly linked list.
381 * Client that owns the set. Only one client may own a set,
382 * and there can only be one set per client.
384 struct GNUNET_SERVER_Client *client;
387 * Message queue for the client.
389 struct GNUNET_MQ_Handle *client_mq;
392 * Virtual table for this set. Determined by the operation type of
395 * Used only for Add/remove of elements and when receiving an incoming
396 * operation from a remote peer.
398 const struct SetVT *vt;
401 * Implementation-specific state.
403 struct SetState *state;
406 * Current state of iterating elements for the client.
407 * NULL if we are not currently iterating.
409 struct GNUNET_CONTAINER_MultiHashMapIterator *iter;
412 * Maps `struct GNUNET_HashCode *` to `struct ElementEntry *`.
414 struct GNUNET_CONTAINER_MultiHashMap *elements;
417 * Evaluate operations are held in a linked list.
419 struct Operation *ops_head;
422 * Evaluate operations are held in a linked list.
424 struct Operation *ops_tail;
427 * Current generation, that is, number of previously executed
428 * operations on this set
430 unsigned int current_generation;
433 * Type of operation supported for this set
435 enum GNUNET_SET_OperationType operation;
441 * Destroy the given operation. Call the implementation-specific
442 * cancel function of the operation. Disconnects from the remote
443 * peer. Does not disconnect the client, as there may be multiple
444 * operations per set.
446 * @param op operation to destroy
447 * @param gc #GNUNET_YES to perform garbage collection on the set
450 _GSS_operation_destroy (struct Operation *op,
455 * Get the table with implementing functions for set union.
457 * @return the operation specific VTable
460 _GSS_union_vt (void);
464 * Get the table with implementing functions for set intersection.
466 * @return the operation specific VTable
469 _GSS_intersection_vt (void);