2 This file is part of GNUnet
3 Copyright (C) 2013, 2014 GNUnet e.V.
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., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, 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;
124 * Always use delta operation instead of sending full sets,
125 * even it it's less efficient.
130 * Always send full sets, even if delta operations would
136 * #GNUNET_YES to fail operations where Byzantine faults
142 * Lower bound for the set size, used only when
143 * byzantine mode is enabled.
145 int byzantine_lower_bound;
150 * Signature of functions that create the implementation-specific
151 * state for a set supporting a specific operation.
153 * @return a set state specific to the supported operation, NULL on error
155 typedef struct SetState *
156 (*CreateImpl) (void);
160 * Signature of functions that implement the add/remove functionality
161 * for a set supporting a specific operation.
163 * @param set implementation-specific set state
164 * @param ee element message from the client
167 (*AddRemoveImpl) (struct SetState *state,
168 struct ElementEntry *ee);
172 * Signature of functions that handle disconnection of the remote
175 * @param op the set operation, contains implementation-specific data
178 (*PeerDisconnectImpl) (struct Operation *op);
182 * Signature of functions that implement the destruction of the
183 * implementation-specific set state.
185 * @param state the set state, contains implementation-specific data
188 (*DestroySetImpl) (struct SetState *state);
192 * Signature of functions that implement accepting a set operation.
194 * @param op operation that is created by accepting the operation,
195 * should be initialized by the implementation
198 (*OpAcceptImpl) (struct Operation *op);
202 * Signature of functions that implement starting the evaluation of
205 * @param op operation that is created, should be initialized to
206 * begin the evaluation
207 * @param opaque_context message to be transmitted to the listener
208 * to convince him to accept, may be NULL
211 (*OpEvaluateImpl) (struct Operation *op,
212 const struct GNUNET_MessageHeader *opaque_context);
216 * Signature of functions that implement the message handling for
217 * the different set operations.
219 * @param op operation state
220 * @param msg received message
221 * @return #GNUNET_OK on success, #GNUNET_SYSERR to
222 * destroy the operation and the tunnel
225 (*MsgHandlerImpl) (struct Operation *op,
226 const struct GNUNET_MessageHeader *msg);
230 * Signature of functions that implement operation cancellation
232 * @param op operation state
235 (*CancelImpl) (struct Operation *op);
238 typedef struct SetState *
239 (*CopyStateImpl) (struct Set *op);
243 * Dispatch table for a specific set operation. Every set operation
244 * has to implement the callback in this struct.
249 * Callback for the set creation.
254 * Callback for element insertion
259 * Callback for element removal.
261 AddRemoveImpl remove;
264 * Callback for accepting a set operation request
269 * Callback for starting evaluation with a remote peer.
271 OpEvaluateImpl evaluate;
274 * Callback for destruction of the set state.
276 DestroySetImpl destroy_set;
279 * Callback for handling operation-specific messages.
281 MsgHandlerImpl msg_handler;
284 * Callback for handling the remote peer's disconnect.
286 PeerDisconnectImpl peer_disconnect;
289 * Callback for canceling an operation by its ID.
293 CopyStateImpl copy_state;
298 * MutationEvent gives information about changes
299 * to an element (removal / addition) in a set content.
304 * First generation affected by this mutation event.
306 * If @a generation is 0, this mutation event is a list
309 unsigned int generation;
312 * If @a added is #GNUNET_YES, then this is a
313 * `remove` event, otherwise it is an `add` event.
320 * Information about an element element in the set. All elements are
321 * stored in a hash-table from their hash-code to their `struct
322 * Element`, so that the remove and add operations are reasonably
328 * The actual element. The data for the element
329 * should be allocated at the end of this struct.
331 struct GNUNET_SET_Element element;
334 * Hash of the element. For set union: Will be used to derive the
335 * different IBF keys for different salts.
337 struct GNUNET_HashCode element_hash;
340 * If @a mutations is not NULL, it contains
341 * a list of mutations, ordered by increasing generation.
342 * The list is terminated by a sentinel event with `generation`
345 * If @a mutations is NULL, then this element exists in all generations
346 * of the respective set content this element belongs to.
348 struct MutationEvent *mutations;
351 * Number of elements in the array @a mutations.
353 unsigned int mutations_size;
356 * #GNUNET_YES if the element is a remote element, and does not belong
357 * to the operation's set.
367 * Operation context used to execute a set operation.
372 * V-Table for the operation belonging to the tunnel contest.
374 * Used for all operation specific operations after receiving the ops request
376 const struct SetVT *vt;
379 * Channel to the peer.
381 struct GNUNET_CADET_Channel *channel;
384 * Port this operation runs on.
386 struct Listener *listener;
389 * Message queue for the channel.
391 struct GNUNET_MQ_Handle *mq;
394 * Detail information about the set operation, including the set to
395 * use. When 'spec' is NULL, the operation is not yet entirely
398 struct OperationSpecification *spec;
401 * Operation-specific operation state. Note that the exact
402 * type depends on this being a union or intersection operation
403 * (and thus on @e vt).
405 struct OperationState *state;
408 * Evaluate operations are held in a linked list.
410 struct Operation *next;
413 * Evaluate operations are held in a linked list.
415 struct Operation *prev;
418 * The identity of the requesting peer. Needs to
419 * be stored here as the op spec might not have been created yet.
421 struct GNUNET_PeerIdentity peer;
424 * Timeout task, if the incoming peer has not been accepted
425 * after the timeout, it will be disconnected.
427 struct GNUNET_SCHEDULER_Task *timeout_task;
430 * Unique request id for the request from a remote peer, sent to the
431 * client, which will accept or reject the request. Set to '0' iff
432 * the request has not been suggested yet.
437 * #GNUNET_YES if this is not a "real" set operation yet, and we still
438 * need to wait for the other peer to give us more details.
443 * Generation in which the operation handle
446 unsigned int generation_created;
449 * Incremented whenever (during shutdown) some component still
450 * needs to do something with this before the operation is freed.
451 * (Used as a reference counter, but only during termination.)
458 * SetContent stores the actual set elements,
459 * which may be shared by multiple generations derived
465 * Number of references to the content.
467 unsigned int refcount;
470 * Maps `struct GNUNET_HashCode *` to `struct ElementEntry *`.
472 struct GNUNET_CONTAINER_MultiHashMap *elements;
474 unsigned int latest_generation;
477 * Mutations requested by the client that we're
478 * unable to execute right now because we're iterating
479 * over the underlying hash map of elements.
481 struct PendingMutation *pending_mutations_head;
484 * Mutations requested by the client that we're
485 * unable to execute right now because we're iterating
486 * over the underlying hash map of elements.
488 struct PendingMutation *pending_mutations_tail;
491 * Number of concurrently active iterators.
497 struct GenerationRange
500 * First generation that is excluded.
505 * Generation after the last excluded generation.
511 struct PendingMutation
513 struct PendingMutation *prev;
514 struct PendingMutation *next;
519 * Message that describes the desired mutation.
520 * May only be a #GNUNET_MESSAGE_TYPE_SET_ADD or
521 * #GNUNET_MESSAGE_TYPE_SET_REMOVE.
523 struct GNUNET_MessageHeader *mutation_message;
528 * A set that supports a specific operation with other peers.
534 * Sets are held in a doubly linked list (in `sets_head` and `sets_tail`).
539 * Sets are held in a doubly linked list.
544 * Client that owns the set. Only one client may own a set,
545 * and there can only be one set per client.
547 struct GNUNET_SERVICE_Client *client;
550 * Message queue for the client.
552 struct GNUNET_MQ_Handle *client_mq;
555 * Virtual table for this set. Determined by the operation type of
558 * Used only for Add/remove of elements and when receiving an incoming
559 * operation from a remote peer.
561 const struct SetVT *vt;
564 * Implementation-specific state.
566 struct SetState *state;
569 * Current state of iterating elements for the client.
570 * NULL if we are not currently iterating.
572 struct GNUNET_CONTAINER_MultiHashMapIterator *iter;
575 * Evaluate operations are held in a linked list.
577 struct Operation *ops_head;
580 * Evaluate operations are held in a linked list.
582 struct Operation *ops_tail;
585 * Current generation, that is, number of previously executed
586 * operations and lazy copies on the underlying set content.
588 unsigned int current_generation;
591 * List of generations we have to exclude, due to lazy copies.
593 struct GenerationRange *excluded_generations;
596 * Number of elements in array @a excluded_generations.
598 unsigned int excluded_generations_size;
601 * Type of operation supported for this set
603 enum GNUNET_SET_OperationType operation;
606 * Each @e iter is assigned a unique number, so that the client
607 * can distinguish iterations.
609 uint16_t iteration_id;
612 * Generation we're currently iteration over.
614 unsigned int iter_generation;
617 * Content, possibly shared by multiple sets,
618 * and thus reference counted.
620 struct SetContent *content;
624 extern struct GNUNET_STATISTICS_Handle *_GSS_statistics;
628 * Destroy the given operation. Call the implementation-specific
629 * cancel function of the operation. Disconnects from the remote
630 * peer. Does not disconnect the client, as there may be multiple
631 * operations per set.
633 * @param op operation to destroy
634 * @param gc #GNUNET_YES to perform garbage collection on the set
637 _GSS_operation_destroy (struct Operation *op,
642 * Get the table with implementing functions for set union.
644 * @return the operation specific VTable
647 _GSS_union_vt (void);
651 * Get the table with implementing functions for set intersection.
653 * @return the operation specific VTable
656 _GSS_intersection_vt (void);
660 _GSS_is_element_of_set (struct ElementEntry *ee,
664 _GSS_is_element_of_operation (struct ElementEntry *ee,
665 struct Operation *op);