src/set/gnunet-service-set.h

   1 /*
   2       This file is part of GNUnet
   3       (C) 2013, 2014 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  * @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
  25  */
  26 #ifndef GNUNET_SERVICE_SET_H_PRIVATE
  27 #define GNUNET_SERVICE_SET_H_PRIVATE
  28
  29 #include "platform.h"
  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"
  36 #include "set.h"
  37
  38
  39 /**
  40  * Implementation-specific set state.  Used as opaque pointer, and
  41  * specified further in the respective implementation.
  42  */
  43 struct SetState;
  44
  45 /**
  46  * Implementation-specific set operation.  Used as opaque pointer, and
  47  * specified further in the respective implementation.
  48  */
  49 struct OperationState;
  50
  51 /**
  52  * A set that supports a specific operation with other peers.
  53  */
  54 struct Set;
  55
  56 /**
  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
  60  * fast.
  61  */
  62 struct ElementEntry;
  63
  64 /**
  65  * Operation context used to execute a set operation.
  66  */
  67 struct Operation;
  68
  69
  70 /**
  71  * Detail information about an operation.
  72  */
  73 struct OperationSpecification
  74 {
  75
  76   /**
  77    * The remove peer we evaluate the operation with.
  78    */
  79   struct GNUNET_PeerIdentity peer;
  80
  81   /**
  82    * Application ID for the operation, used to distinguish
  83    * multiple operations of the same type with the same peer.
  84    */
  85   struct GNUNET_HashCode app_id;
  86
  87   /**
  88    * Context message, may be NULL.
  89    */
  90   struct GNUNET_MessageHeader *context_msg;
  91
  92   /**
  93    * Set associated with the operation, NULL until the spec has been
  94    * associated with a set.
  95    */
  96   struct Set *set;
  97
  98   /**
  99    * Salt to use for the operation.
 100    */
 101   uint32_t salt;
 102
 103   /**
 104    * Remote peers element count
 105    */
 106   uint32_t remote_element_count;
 107
 108   /**
 109    * ID used to identify an operation between service and client
 110    */
 111   uint32_t client_request_id;
 112
 113   /**
 114    * The type of the operation.
 115    */
 116   enum GNUNET_SET_OperationType operation;
 117
 118   /**
 119    * When are elements sent to the client, and which elements are sent?
 120    */
 121   enum GNUNET_SET_ResultMode result_mode;
 122 };
 123
 124
 125 /**
 126  * Signature of functions that create the implementation-specific
 127  * state for a set supporting a specific operation.
 128  *
 129  * @return a set state specific to the supported operation
 130  */
 131 typedef struct SetState *
 132 (*CreateImpl) (void);
 133
 134
 135 /**
 136  * Signature of functions that implement the add/remove functionality
 137  * for a set supporting a specific operation.
 138  *
 139  * @param set implementation-specific set state
 140  * @param ee element message from the client
 141  */
 142 typedef void
 143 (*AddRemoveImpl) (struct SetState *state,
 144                   struct ElementEntry *ee);
 145
 146
 147 /**
 148  * Signature of functions that handle disconnection of the remote
 149  * peer.
 150  *
 151  * @param op the set operation, contains implementation-specific data
 152  */
 153 typedef void
 154 (*PeerDisconnectImpl) (struct Operation *op);
 155
 156
 157 /**
 158  * Signature of functions that implement the destruction of the
 159  * implementation-specific set state.
 160  *
 161  * @param state the set state, contains implementation-specific data
 162  */
 163 typedef void
 164 (*DestroySetImpl) (struct SetState *state);
 165
 166
 167 /**
 168  * Signature of functions that implement accepting a set operation.
 169  *
 170  * @param op operation that is created by accepting the operation,
 171  *        should be initialized by the implementation
 172  */
 173 typedef void
 174 (*OpAcceptImpl) (struct Operation *op);
 175
 176
 177 /**
 178  * Signature of functions that implement starting the evaluation of
 179  * set operations.
 180  *
 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
 185  */
 186 typedef void
 187 (*OpEvaluateImpl) (struct Operation *op,
 188                    const struct GNUNET_MessageHeader *opaque_context);
 189
 190
 191 /**
 192  * Signature of functions that implement the message handling for
 193  * the different set operations.
 194  *
 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
 199  */
 200 typedef int
 201 (*MsgHandlerImpl) (struct Operation *op,
 202                    const struct GNUNET_MessageHeader *msg);
 203
 204
 205 /**
 206  * Signature of functions that implement operation cancellation
 207  *
 208  * @param op operation state
 209  */
 210 typedef void
 211 (*CancelImpl) (struct Operation *op);
 212
 213
 214 /**
 215  * Dispatch table for a specific set operation.  Every set operation
 216  * has to implement the callback in this struct.
 217  */
 218 struct SetVT
 219 {
 220   /**
 221    * Callback for the set creation.
 222    */
 223   CreateImpl create;
 224
 225   /**
 226    * Callback for element insertion
 227    */
 228   AddRemoveImpl add;
 229
 230   /**
 231    * Callback for element removal.
 232    */
 233   AddRemoveImpl remove;
 234
 235   /**
 236    * Callback for accepting a set operation request
 237    */
 238   OpAcceptImpl accept;
 239
 240   /**
 241    * Callback for starting evaluation with a remote peer.
 242    */
 243   OpEvaluateImpl evaluate;
 244
 245   /**
 246    * Callback for destruction of the set state.
 247    */
 248   DestroySetImpl destroy_set;
 249
 250   /**
 251    * Callback for handling operation-specific messages.
 252    */
 253   MsgHandlerImpl msg_handler;
 254
 255   /**
 256    * Callback for handling the remote peer's disconnect.
 257    */
 258   PeerDisconnectImpl peer_disconnect;
 259
 260   /**
 261    * Callback for canceling an operation by its ID.
 262    */
 263   CancelImpl cancel;
 264 };
 265
 266
 267 /**
 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
 271  * fast.
 272  */
 273 struct ElementEntry
 274 {
 275   /**
 276    * The actual element. The data for the element
 277    * should be allocated at the end of this struct.
 278    */
 279   struct GNUNET_SET_Element element;
 280
 281   /**
 282    * Hash of the element.  For set union: Will be used to derive the
 283    * different IBF keys for different salts.
 284    */
 285   struct GNUNET_HashCode element_hash;
 286
 287   /**
 288    * Generation the element was added by the client.
 289    * Operations of earlier generations will not consider the element.
 290    */
 291   unsigned int generation_added;
 292
 293   /**
 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.
 297    */
 298   unsigned int generation_removed;
 299
 300   /**
 301    * #GNUNET_YES if the element has been removed in some generation.
 302    */
 303   int removed;
 304
 305   /**
 306    * #GNUNET_YES if the element is a remote element, and does not belong
 307    * to the operation's set.
 308    */
 309   int remote;
 310 };
 311
 312
 313 /**
 314  * Operation context used to execute a set operation.
 315  */
 316 struct Operation
 317 {
 318   /**
 319    * V-Table for the operation belonging to the tunnel contest.
 320    *
 321    * Used for all operation specific operations after receiving the ops request
 322    */
 323   const struct SetVT *vt;
 324
 325   /**
 326    * Tunnel to the peer.
 327    */
 328   struct GNUNET_CADET_Channel *channel;
 329
 330   /**
 331    * Message queue for the tunnel.
 332    */
 333   struct GNUNET_MQ_Handle *mq;
 334
 335   /**
 336    * Detail information about the set operation, including the set to
 337    * use.  When 'spec' is NULL, the operation is not yet entirely
 338    * initialized.
 339    */
 340   struct OperationSpecification *spec;
 341
 342   /**
 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).
 346    */
 347   struct OperationState *state;
 348
 349   /**
 350    * Evaluate operations are held in a linked list.
 351    */
 352   struct Operation *next;
 353
 354   /**
 355    * Evaluate operations are held in a linked list.
 356    */
 357   struct Operation *prev;
 358
 359   /**
 360    * The identity of the requesting peer.  Needs to
 361    * be stored here as the op spec might not have been created yet.
 362    */
 363   struct GNUNET_PeerIdentity peer;
 364
 365   /**
 366    * Timeout task, if the incoming peer has not been accepted
 367    * after the timeout, it will be disconnected.
 368    */
 369   struct GNUNET_SCHEDULER_Task * timeout_task;
 370
 371   /**
 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.
 375    */
 376   uint32_t suggest_id;
 377
 378   /**
 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.
 381    */
 382   int is_incoming;
 383
 384   /**
 385    * Generation in which the operation handle
 386    * was created.
 387    */
 388   unsigned int generation_created;
 389
 390   /**
 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.)
 394    */
 395   unsigned int keep;
 396 };
 397
 398
 399 /**
 400  * A set that supports a specific operation with other peers.
 401  */
 402 struct Set
 403 {
 404
 405   /**
 406    * Sets are held in a doubly linked list (in `sets_head` and `sets_tail`).
 407    */
 408   struct Set *next;
 409
 410   /**
 411    * Sets are held in a doubly linked list.
 412    */
 413   struct Set *prev;
 414
 415   /**
 416    * Client that owns the set.  Only one client may own a set,
 417    * and there can only be one set per client.
 418    */
 419   struct GNUNET_SERVER_Client *client;
 420
 421   /**
 422    * Message queue for the client.
 423    */
 424   struct GNUNET_MQ_Handle *client_mq;
 425
 426   /**
 427    * Virtual table for this set.  Determined by the operation type of
 428    * this set.
 429    *
 430    * Used only for Add/remove of elements and when receiving an incoming
 431    * operation from a remote peer.
 432    */
 433   const struct SetVT *vt;
 434
 435   /**
 436    * Implementation-specific state.
 437    */
 438   struct SetState *state;
 439
 440   /**
 441    * Current state of iterating elements for the client.
 442    * NULL if we are not currently iterating.
 443    */
 444   struct GNUNET_CONTAINER_MultiHashMapIterator *iter;
 445
 446   /**
 447    * Maps `struct GNUNET_HashCode *` to `struct ElementEntry *`.
 448    */
 449   struct GNUNET_CONTAINER_MultiHashMap *elements;
 450
 451   /**
 452    * Evaluate operations are held in a linked list.
 453    */
 454   struct Operation *ops_head;
 455
 456   /**
 457    * Evaluate operations are held in a linked list.
 458    */
 459   struct Operation *ops_tail;
 460
 461   /**
 462    * Current generation, that is, number of previously executed
 463    * operations on this set
 464    */
 465   unsigned int current_generation;
 466
 467   /**
 468    * Type of operation supported for this set
 469    */
 470   enum GNUNET_SET_OperationType operation;
 471
 472   /**
 473    * Each @e iter is assigned a unique number, so that the client
 474    * can distinguish iterations.
 475    */
 476   uint16_t iteration_id;
 477
 478 };
 479
 480
 481 /**
 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.
 486  *
 487  * @param op operation to destroy
 488  * @param gc #GNUNET_YES to perform garbage collection on the set
 489  */
 490 void
 491 _GSS_operation_destroy (struct Operation *op,
 492                         int gc);
 493
 494
 495 /**
 496  * Get the table with implementing functions for set union.
 497  *
 498  * @return the operation specific VTable
 499  */
 500 const struct SetVT *
 501 _GSS_union_vt (void);
 502
 503
 504 /**
 505  * Get the table with implementing functions for set intersection.
 506  *
 507  * @return the operation specific VTable
 508  */
 509 const struct SetVT *
 510 _GSS_intersection_vt (void);
 511
 512
 513 #endif