src/set/gnunet-service-set.h

   1 /*
   2       This file is part of GNUnet
   3       (C) 2013 Christian Grothoff (and other contributing authors)
   4
   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.
   9
  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.
  14
  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.
  19 */
  20
  21 /**
  22  * @file set/gnunet-service-set.h
  23  * @brief common components for the implementation the different set operations
  24  * @author Florian Dold
  25  */
  26
  27 #ifndef GNUNET_SERVICE_SET_H_PRIVATE
  28 #define GNUNET_SERVICE_SET_H_PRIVATE
  29
  30 #include "platform.h"
  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_mesh_service.h"
  36 #include "gnunet_set_service.h"
  37 #include "set.h"
  38
  39
  40 /**
  41  * Implementation-specific set state.
  42  * Used as opaque pointer, and specified further
  43  * in the respective implementation.
  44  */
  45 struct SetState;
  46
  47
  48 /**
  49  * Implementation-specific set operation.
  50  * Used as opaque pointer, and specified further
  51  * in the respective implementation.
  52  */
  53 struct OperationState;
  54
  55
  56 /* forward declarations */
  57 struct Set;
  58 struct ElementEntry;
  59 struct Operation;
  60
  61
  62 /**
  63  * Detail information about an operation.
  64  */
  65 struct OperationSpecification
  66 {
  67   /**
  68    * The type of the operation.
  69    */
  70   enum GNUNET_SET_OperationType operation;
  71
  72   /**
  73    * The remove peer we evaluate the operation with
  74    */
  75   struct GNUNET_PeerIdentity peer;
  76
  77   /**
  78    * Application ID for the operation, used to distinguish
  79    * multiple operations of the same type with the same peer.
  80    */
  81   struct GNUNET_HashCode app_id;
  82
  83   /**
  84    * Context message, may be NULL.
  85    */
  86   struct GNUNET_MessageHeader *context_msg;
  87
  88   /**
  89    * Salt to use for the operation.
  90    */
  91   uint32_t salt;
  92
  93   /**
  94    * ID used to identify an operation between service and client
  95    */
  96   uint32_t client_request_id;
  97
  98   /**
  99    * Set associated with the operation, NULL until the spec has been associated
 100    * with a set.
 101    */
 102   struct Set *set;
 103
 104   /**
 105    * When are elements sent to the client, and which elements are sent?
 106    */
 107   enum GNUNET_SET_ResultMode result_mode;
 108 };
 109
 110
 111
 112
 113 /**
 114  * Signature of functions that create the implementation-specific
 115  * state for a set supporting a specific operation.
 116  *
 117  * @return a set state specific to the supported operation
 118  */
 119 typedef struct SetState *(*CreateImpl) (void);
 120
 121
 122 /**
 123  * Signature of functions that implement the add/remove functionality
 124  * for a set supporting a specific operation.
 125  *
 126  * @param set implementation-specific set state
 127  * @param msg element message from the client
 128  */
 129 typedef void (*AddRemoveImpl) (struct SetState *state, struct ElementEntry *ee);
 130
 131
 132 /**
 133  * Signature of functions that handle disconnection
 134  * of the remote peer.
 135  *
 136  * @param op the set operation, contains implementation-specific data
 137  */
 138 typedef void (*PeerDisconnectImpl) (struct Operation *op);
 139
 140
 141 /**
 142  * Signature of functions that implement the destruction of the
 143  * implementation-specific set state.
 144  *
 145  * @param state the set state, contains implementation-specific data
 146  */
 147 typedef void (*DestroySetImpl) (struct SetState *state);
 148
 149
 150 /**
 151  * Signature of functions that implement the creation of set operations
 152  * (currently evaluate and accept).
 153  *
 154  * @param op operation that is created, should be initialized by the implementation
 155  */
 156 typedef void (*OpCreateImpl) (struct Operation *op);
 157
 158
 159 /**
 160  * Signature of functions that implement the message handling for
 161  * the different set operations.
 162  *
 163  * @param op operation state
 164  * @param msg received message
 165  * @return GNUNET_OK on success, GNUNET_SYSERR to
 166  *         destroy the operation and the tunnel
 167  */
 168 typedef int (*MsgHandlerImpl) (struct Operation *op,
 169                                const struct GNUNET_MessageHeader *msg);
 170
 171 /**
 172  * Signature of functions that implement operation cancellation
 173  *
 174  * @param op operation state
 175  */
 176 typedef void (*CancelImpl) (struct Operation *op);
 177
 178
 179 /**
 180  * Dispatch table for a specific set operation.
 181  * Every set operation has to implement the callback
 182  * in this struct.
 183  */
 184 struct SetVT
 185 {
 186   /**
 187    * Callback for the set creation.
 188    */
 189   CreateImpl create;
 190
 191   /**
 192    * Callback for element insertion
 193    */
 194   AddRemoveImpl add;
 195
 196   /**
 197    * Callback for element removal.
 198    */
 199   AddRemoveImpl remove;
 200
 201   /**
 202    * Callback for accepting a set operation request
 203    */
 204   OpCreateImpl accept;
 205
 206   /**
 207    * Callback for starting evaluation with a remote peer.
 208    */
 209   OpCreateImpl evaluate;
 210
 211   /**
 212    * Callback for destruction of the set state.
 213    */
 214   DestroySetImpl destroy_set;
 215
 216   /**
 217    * Callback for handling operation-specific messages.
 218    */
 219   MsgHandlerImpl msg_handler;
 220
 221   /**
 222    * Callback for handling the remote peer's
 223    * disconnect.
 224    */
 225   PeerDisconnectImpl peer_disconnect;
 226
 227   /**
 228    * Callback for canceling an operation by
 229    * its ID.
 230    */
 231   CancelImpl cancel;
 232 };
 233
 234
 235 /**
 236  * Information about an element element in the set.
 237  * All elements are stored in a hash-table
 238  * from their hash-code to their 'struct Element',
 239  * so that the remove and add operations are reasonably
 240  * fast.
 241  */
 242 struct ElementEntry
 243 {
 244   /**
 245    * The actual element. The data for the element
 246    * should be allocated at the end of this struct.
 247    */
 248   struct GNUNET_SET_Element element;
 249
 250   /**
 251    * Hash of the element.
 252    * For set union:
 253    * Will be used to derive the different IBF keys
 254    * for different salts.
 255    */
 256   struct GNUNET_HashCode element_hash;
 257
 258   /**
 259    * Generation the element was added by the client.
 260    * Operations of earlier generations will not consider the element.
 261    */
 262   unsigned int generation_added;
 263
 264   /**
 265    * GNUNET_YES if the element has been removed in some generation.
 266    */
 267   int removed;
 268
 269   /**
 270    * Generation the element was removed by the client.
 271    * Operations of later generations will not consider the element.
 272    * Only valid if is_removed is GNUNET_YES.
 273    */
 274   unsigned int generation_removed;
 275
 276   /**
 277    * GNUNET_YES if the element is a remote element, and does not belong
 278    * to the operation's set.
 279    *
 280    * //TODO: Move to Union, unless additional set-operations are implemented ever
 281    */
 282   int remote;
 283 };
 284
 285
 286 struct Operation
 287 {
 288   /**
 289    * V-Table for the operation belonging
 290    * to the tunnel contest.
 291    *
 292    * Used for all operation specific operations after receiving the ops request
 293    */
 294   const struct SetVT *vt;
 295
 296   /**
 297    * Tunnel to the peer.
 298    */
 299   struct GNUNET_MESH_Tunnel *tunnel;
 300
 301   /**
 302    * Message queue for the tunnel.
 303    */
 304   struct GNUNET_MQ_Handle *mq;
 305
 306   /**
 307    * GNUNET_YES if this is not a "real" set operation yet, and we still
 308    * need to wait for the other peer to give us more details.
 309    *
 310    * //TODO: replace with state-enum
 311    */
 312   int is_incoming;
 313
 314   /**
 315    * Generation in which the operation handle
 316    * was created.
 317    */
 318   unsigned int generation_created;
 319
 320   /**
 321    * Detail information about the set operation,
 322    * including the set to use.
 323    * When 'spec' is NULL, the operation is not yet entirely
 324    * initialized.
 325    */
 326   struct OperationSpecification *spec;
 327
 328   /**
 329    * Operation-specific operation state.
 330    */
 331   struct OperationState *state;
 332
 333   /**
 334    * Evaluate operations are held in
 335    * a linked list.
 336    */
 337   struct Operation *next;
 338
 339    /**
 340     * Evaluate operations are held in
 341     * a linked list.
 342     */
 343   struct Operation *prev;
 344 };
 345
 346
 347 /**
 348  * A set that supports a specific operation
 349  * with other peers.
 350  */
 351 struct Set
 352 {
 353   /**
 354    * Client that owns the set.
 355    * Only one client may own a set.
 356    */
 357   struct GNUNET_SERVER_Client *client;
 358
 359   /**
 360    * Message queue for the client
 361    */
 362   struct GNUNET_MQ_Handle *client_mq;
 363
 364   /**
 365    * Type of operation supported for this set
 366    */
 367   enum GNUNET_SET_OperationType operation;
 368
 369   /**
 370    * Virtual table for this set.
 371    * Determined by the operation type of this set.
 372    *
 373    * Used only for Add/remove of elements and when receiving an incoming
 374    * operation from a remote peer.
 375    */
 376   const struct SetVT *vt;
 377
 378   /**
 379    * Sets are held in a doubly linked list.
 380    */
 381   struct Set *next;
 382
 383   /**
 384    * Sets are held in a doubly linked list.
 385    */
 386   struct Set *prev;
 387
 388   /**
 389    * Implementation-specific state.
 390    */
 391   struct SetState *state;
 392
 393   /**
 394    * Current state of iterating elements for the client.
 395    * NULL if we are not currently iterating.
 396    */
 397   struct GNUNET_CONTAINER_MultiHashMapIterator *iter;
 398
 399   /**
 400    * Maps 'struct GNUNET_HashCode' to 'struct ElementEntry'.
 401    */
 402   struct GNUNET_CONTAINER_MultiHashMap *elements;
 403
 404   /**
 405    * Current generation, that is, number of
 406    * previously executed operations on this set
 407    */
 408   unsigned int current_generation;
 409
 410   /**
 411    * Evaluate operations are held in
 412    * a linked list.
 413    */
 414   struct Operation *ops_head;
 415
 416   /**
 417    * Evaluate operations are held in
 418    * a linked list.
 419    */
 420   struct Operation *ops_tail;
 421 };
 422
 423
 424 /**
 425  * Destroy the given operation.  Call the implementation-specific cancel function
 426  * of the operation.  Disconnects from the remote peer.
 427  * Does not disconnect the client, as there may be multiple operations per set.
 428  *
 429  * @param op operation to destroy
 430  */
 431 void
 432 _GSS_operation_destroy (struct Operation *op);
 433
 434
 435 /**
 436  * Get the table with implementing functions for
 437  * set union.
 438  *
 439  * @return the operation specific VTable
 440  */
 441 const struct SetVT *
 442 _GSS_union_vt (void);
 443
 444
 445 /**
 446  * Get the table with implementing functions for
 447  * set intersection.
 448  *
 449  * @return the operation specific VTable
 450  */
 451 const struct SetVT *
 452 _GSS_intersection_vt (void);
 453
 454
 455 #endif