2 This file is part of GNUnet
3 (C) 2013, 2014 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.
21 * @file set/gnunet-service-set.h
22 * @brief common components for the implementation the different set operations
23 * @author Florian Dold
24 * @author Christian Grothoff
26 #ifndef GNUNET_SERVICE_SET_H_PRIVATE
27 #define GNUNET_SERVICE_SET_H_PRIVATE
30 #include "gnunet_util_lib.h"
31 #include "gnunet_protocols.h"
32 #include "gnunet_applications.h"
33 #include "gnunet_core_service.h"
34 #include "gnunet_cadet_service.h"
35 #include "gnunet_set_service.h"
40 * Implementation-specific set state. Used as opaque pointer, and
41 * specified further in the respective implementation.
46 * Implementation-specific set operation. Used as opaque pointer, and
47 * specified further in the respective implementation.
49 struct OperationState;
52 * A set that supports a specific operation with other peers.
57 * Information about an element element in the set. All elements are
58 * stored in a hash-table from their hash-code to their 'struct
59 * Element', so that the remove and add operations are reasonably
65 * Operation context used to execute a set operation.
71 * Detail information about an operation.
73 struct OperationSpecification
77 * The remove peer we evaluate the operation with.
79 struct GNUNET_PeerIdentity peer;
82 * Application ID for the operation, used to distinguish
83 * multiple operations of the same type with the same peer.
85 struct GNUNET_HashCode app_id;
88 * Context message, may be NULL.
90 struct GNUNET_MessageHeader *context_msg;
93 * Set associated with the operation, NULL until the spec has been
94 * associated with a set.
99 * Salt to use for the operation.
104 * Remote peers element count
106 uint32_t remote_element_count;
109 * ID used to identify an operation between service and client
111 uint32_t client_request_id;
114 * The type of the operation.
116 enum GNUNET_SET_OperationType operation;
119 * When are elements sent to the client, and which elements are sent?
121 enum GNUNET_SET_ResultMode result_mode;
126 * Signature of functions that create the implementation-specific
127 * state for a set supporting a specific operation.
129 * @return a set state specific to the supported operation
131 typedef struct SetState *
132 (*CreateImpl) (void);
136 * Signature of functions that implement the add/remove functionality
137 * for a set supporting a specific operation.
139 * @param set implementation-specific set state
140 * @param ee element message from the client
143 (*AddRemoveImpl) (struct SetState *state,
144 struct ElementEntry *ee);
148 * Signature of functions that handle disconnection of the remote
151 * @param op the set operation, contains implementation-specific data
154 (*PeerDisconnectImpl) (struct Operation *op);
158 * Signature of functions that implement the destruction of the
159 * implementation-specific set state.
161 * @param state the set state, contains implementation-specific data
164 (*DestroySetImpl) (struct SetState *state);
168 * Signature of functions that implement accepting a set operation.
170 * @param op operation that is created by accepting the operation,
171 * should be initialized by the implementation
174 (*OpAcceptImpl) (struct Operation *op);
178 * Signature of functions that implement starting the evaluation of
181 * @param op operation that is created, should be initialized to
182 * begin the evaluation
183 * @param opaque_context message to be transmitted to the listener
184 * to convince him to accept, may be NULL
187 (*OpEvaluateImpl) (struct Operation *op,
188 const struct GNUNET_MessageHeader *opaque_context);
192 * Signature of functions that implement the message handling for
193 * the different set operations.
195 * @param op operation state
196 * @param msg received message
197 * @return #GNUNET_OK on success, #GNUNET_SYSERR to
198 * destroy the operation and the tunnel
201 (*MsgHandlerImpl) (struct Operation *op,
202 const struct GNUNET_MessageHeader *msg);
206 * Signature of functions that implement operation cancellation
208 * @param op operation state
211 (*CancelImpl) (struct Operation *op);
215 * Dispatch table for a specific set operation. Every set operation
216 * has to implement the callback in this struct.
221 * Callback for the set creation.
226 * Callback for element insertion
231 * Callback for element removal.
233 AddRemoveImpl remove;
236 * Callback for accepting a set operation request
241 * Callback for starting evaluation with a remote peer.
243 OpEvaluateImpl evaluate;
246 * Callback for destruction of the set state.
248 DestroySetImpl destroy_set;
251 * Callback for handling operation-specific messages.
253 MsgHandlerImpl msg_handler;
256 * Callback for handling the remote peer's disconnect.
258 PeerDisconnectImpl peer_disconnect;
261 * Callback for canceling an operation by its ID.
268 * Information about an element element in the set. All elements are
269 * stored in a hash-table from their hash-code to their `struct
270 * Element`, so that the remove and add operations are reasonably
276 * The actual element. The data for the element
277 * should be allocated at the end of this struct.
279 struct GNUNET_SET_Element element;
282 * Hash of the element. For set union: Will be used to derive the
283 * different IBF keys for different salts.
285 struct GNUNET_HashCode element_hash;
288 * Generation the element was added by the client.
289 * Operations of earlier generations will not consider the element.
291 unsigned int generation_added;
294 * Generation the element was removed by the client.
295 * Operations of later generations will not consider the element.
296 * Only valid if @e removed is #GNUNET_YES.
298 unsigned int generation_removed;
301 * #GNUNET_YES if the element has been removed in some generation.
306 * #GNUNET_YES if the element is a remote element, and does not belong
307 * to the operation's set.
314 * Operation context used to execute a set operation.
319 * V-Table for the operation belonging to the tunnel contest.
321 * Used for all operation specific operations after receiving the ops request
323 const struct SetVT *vt;
326 * Tunnel to the peer.
328 struct GNUNET_CADET_Channel *channel;
331 * Message queue for the tunnel.
333 struct GNUNET_MQ_Handle *mq;
336 * Detail information about the set operation, including the set to
337 * use. When 'spec' is NULL, the operation is not yet entirely
340 struct OperationSpecification *spec;
343 * Operation-specific operation state. Note that the exact
344 * type depends on this being a union or intersection operation
345 * (and thus on @e vt).
347 struct OperationState *state;
350 * Evaluate operations are held in a linked list.
352 struct Operation *next;
355 * Evaluate operations are held in a linked list.
357 struct Operation *prev;
360 * The identity of the requesting peer. Needs to
361 * be stored here as the op spec might not have been created yet.
363 struct GNUNET_PeerIdentity peer;
366 * Timeout task, if the incoming peer has not been accepted
367 * after the timeout, it will be disconnected.
369 GNUNET_SCHEDULER_TaskIdentifier timeout_task;
372 * Unique request id for the request from a remote peer, sent to the
373 * client, which will accept or reject the request. Set to '0' iff
374 * the request has not been suggested yet.
379 * #GNUNET_YES if this is not a "real" set operation yet, and we still
380 * need to wait for the other peer to give us more details.
385 * Generation in which the operation handle
388 unsigned int generation_created;
391 * Incremented whenever (during shutdown) some component still
392 * needs to do something with this before the operation is freed.
393 * (Used as a reference counter, but only during termination.)
400 * A set that supports a specific operation with other peers.
406 * Sets are held in a doubly linked list (in `sets_head` and `sets_tail`).
411 * Sets are held in a doubly linked list.
416 * Client that owns the set. Only one client may own a set,
417 * and there can only be one set per client.
419 struct GNUNET_SERVER_Client *client;
422 * Message queue for the client.
424 struct GNUNET_MQ_Handle *client_mq;
427 * Virtual table for this set. Determined by the operation type of
430 * Used only for Add/remove of elements and when receiving an incoming
431 * operation from a remote peer.
433 const struct SetVT *vt;
436 * Implementation-specific state.
438 struct SetState *state;
441 * Current state of iterating elements for the client.
442 * NULL if we are not currently iterating.
444 struct GNUNET_CONTAINER_MultiHashMapIterator *iter;
447 * Maps `struct GNUNET_HashCode *` to `struct ElementEntry *`.
449 struct GNUNET_CONTAINER_MultiHashMap *elements;
452 * Evaluate operations are held in a linked list.
454 struct Operation *ops_head;
457 * Evaluate operations are held in a linked list.
459 struct Operation *ops_tail;
462 * Current generation, that is, number of previously executed
463 * operations on this set
465 unsigned int current_generation;
468 * Type of operation supported for this set
470 enum GNUNET_SET_OperationType operation;
473 * Each @e iter is assigned a unique number, so that the client
474 * can distinguish iterations.
476 uint16_t iteration_id;
482 * Destroy the given operation. Call the implementation-specific
483 * cancel function of the operation. Disconnects from the remote
484 * peer. Does not disconnect the client, as there may be multiple
485 * operations per set.
487 * @param op operation to destroy
488 * @param gc #GNUNET_YES to perform garbage collection on the set
491 _GSS_operation_destroy (struct Operation *op,
496 * Get the table with implementing functions for set union.
498 * @return the operation specific VTable
501 _GSS_union_vt (void);
505 * Get the table with implementing functions for set intersection.
507 * @return the operation specific VTable
510 _GSS_intersection_vt (void);