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