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 TunnelContext;
  59 struct ElementEntry;
  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 responses to a 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
 106
 107
 108 /**
 109  * Signature of functions that create the implementation-specific
 110  * state for a set supporting a specific operation.
 111  *
 112  * @return a set state specific to the supported operation
 113  */
 114 typedef struct SetState *(*CreateImpl) (void);
 115
 116
 117 /**
 118  * Signature of functions that implement the add/remove functionality
 119  * for a set supporting a specific operation.
 120  *
 121  * @param set implementation-specific set state
 122  * @param msg element message from the client
 123  */
 124 typedef void (*AddRemoveImpl) (struct SetState *state, struct ElementEntry *ee);
 125
 126
 127 /**
 128  * Signature of functions that handle disconnection
 129  * of the remote peer.
 130  *
 131  * @param op the set operation, contains implementation-specific data
 132  */
 133 typedef void (*PeerDisconnectImpl) (struct OperationState *op);
 134
 135
 136 /**
 137  * Signature of functions that implement the destruction of the
 138  * implementation-specific set state.
 139  *
 140  * @param state the set state, contains implementation-specific data
 141  */
 142 typedef void (*DestroySetImpl) (struct SetState *state);
 143
 144
 145 /**
 146  * Signature of functions that implement the creation of set operations
 147  * (currently evaluate and accept).
 148  *
 149  * @param spec specification of the set operation to be created
 150  * @param tunnel the tunnel with the other peer
 151  * @param tc tunnel context
 152  */
 153 typedef void (*OpCreateImpl) (struct OperationSpecification *spec,
 154                               struct GNUNET_MESH_Tunnel *tunnel,
 155                               struct TunnelContext *tc);
 156
 157
 158 /**
 159  * Signature of functions that implement the message handling for
 160  * the different set operations.
 161  *
 162  * @param op operation state
 163  * @param msg received message
 164  * @return GNUNET_OK on success, GNUNET_SYSERR to
 165  *         destroy the operation and the tunnel
 166  */
 167 typedef int (*MsgHandlerImpl) (struct OperationState *op,
 168                                const struct GNUNET_MessageHeader *msg);
 169
 170 typedef void (*CancelImpl) (struct SetState *set,
 171                             uint32_t request_id);
 172
 173
 174 /**
 175  * Signature of functions that implement sending all the set's
 176  * elements to the client.
 177  *
 178  * @param set set that should be iterated over
 179  */
 180 typedef void (*IterateImpl) (struct Set *set);
 181
 182
 183 /**
 184  * Dispatch table for a specific set operation.
 185  * Every set operation has to implement the callback
 186  * in this struct.
 187  */
 188 struct SetVT
 189 {
 190   /**
 191    * Callback for the set creation.
 192    */
 193   CreateImpl create;
 194
 195   /**
 196    * Callback for element insertion
 197    */
 198   AddRemoveImpl add;
 199
 200   /**
 201    * Callback for element removal.
 202    */
 203   AddRemoveImpl remove;
 204
 205   /**
 206    * Callback for accepting a set operation request
 207    */
 208   OpCreateImpl accept;
 209
 210   /**
 211    * Callback for starting evaluation with a remote peer.
 212    */
 213   OpCreateImpl evaluate;
 214
 215   /**
 216    * Callback for destruction of the set state.
 217    */
 218   DestroySetImpl destroy_set;
 219
 220   /**
 221    * Callback for handling operation-specific messages.
 222    */
 223   MsgHandlerImpl msg_handler;
 224
 225   /**
 226    * Callback for handling the remote peer's
 227    * disconnect.
 228    */
 229   PeerDisconnectImpl peer_disconnect;
 230
 231   /**
 232    * Callback for canceling an operation by
 233    * its ID.
 234    */
 235   CancelImpl cancel;
 236
 237   /**
 238    * Callback for iterating over all set elements.
 239    */
 240   IterateImpl iterate;
 241 };
 242
 243
 244 /**
 245  * Information about an element element in the set.
 246  * All elements are stored in a hash-table
 247  * from their hash-code to their 'struct Element',
 248  * so that the remove and add operations are reasonably
 249  * fast.
 250  */
 251 struct ElementEntry
 252 {
 253   /**
 254    * The actual element. The data for the element
 255    * should be allocated at the end of this struct.
 256    */
 257   struct GNUNET_SET_Element element;
 258
 259   /**
 260    * Hash of the element.
 261    * Will be used to derive the different IBF keys
 262    * for different salts.
 263    */
 264   struct GNUNET_HashCode element_hash;
 265
 266   /**
 267    * Generation the element was added by the client.
 268    * Operations of earlier generations will not consider the element.
 269    */
 270   unsigned int generation_added;
 271
 272   /**
 273    * GNUNET_YES if the element has been removed in some generation.
 274    */
 275   int removed;
 276
 277   /**
 278    * Generation the element was removed by the client.
 279    * Operations of later generations will not consider the element.
 280    * Only valid if is_removed is GNUNET_YES.
 281    */
 282   unsigned int generation_removed;
 283
 284   /**
 285    * GNUNET_YES if the element is a remote element, and does not belong
 286    * to the operation's set.
 287    */
 288   int remote;
 289 };
 290
 291
 292 /**
 293  * A set that supports a specific operation
 294  * with other peers.
 295  */
 296 struct Set
 297 {
 298   /**
 299    * Client that owns the set.
 300    * Only one client may own a set.
 301    */
 302   struct GNUNET_SERVER_Client *client;
 303
 304   /**
 305    * Message queue for the client
 306    */
 307   struct GNUNET_MQ_Handle *client_mq;
 308
 309   /**
 310    * Type of operation supported for this set
 311    */
 312   enum GNUNET_SET_OperationType operation;
 313
 314   /**
 315    * Virtual table for this set.
 316    * Determined by the operation type of this set.
 317    */
 318   const struct SetVT *vt;
 319
 320   /**
 321    * Sets are held in a doubly linked list.
 322    */
 323   struct Set *next;
 324
 325   /**
 326    * Sets are held in a doubly linked list.
 327    */
 328   struct Set *prev;
 329
 330   /**
 331    * Implementation-specific state.
 332    */
 333   struct SetState *state;
 334
 335   /**
 336    * Current state of iterating elements for the client.
 337    * NULL if we are not currently iterating.
 338    */
 339   struct GNUNET_CONTAINER_MultiHashMapIterator *iter;
 340
 341   /**
 342    * Maps 'struct GNUNET_HashCode' to 'struct ElementEntry'.
 343    */
 344   struct GNUNET_CONTAINER_MultiHashMap *elements;
 345
 346   /**
 347    * Current generation, that is, number of
 348    * previously executed operations on this set
 349    */
 350   unsigned int current_generation;
 351 };
 352
 353
 354 /**
 355  * Information about a tunnel we are connected to.
 356  * Used as tunnel context with mesh.
 357  */
 358 struct TunnelContext
 359 {
 360   /**
 361    * V-Table for the operation belonging
 362    * to the tunnel contest.
 363    */
 364   const struct SetVT *vt;
 365
 366   /**
 367    * Implementation-specific operation state.
 368    */
 369   struct OperationState *op;
 370 };
 371
 372
 373 /**
 374  * Get the table with implementing functions for
 375  * set union.
 376  */
 377 const struct SetVT *
 378 _GSS_union_vt (void);
 379
 380
 381 #endif