src/include/gnunet_set_service.h

   1 /*
   2       This file is part of GNUnet
   3       Copyright (C) 2013, 2014 GNUnet e.V.
   4
   5       GNUnet is free software: you can redistribute it and/or modify it
   6       under the terms of the GNU Affero General Public License as published
   7       by the Free Software Foundation, either version 3 of the License,
   8       or (at your 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       Affero General Public License for more details.
  14
  15       You should have received a copy of the GNU Affero General Public License
  16       along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18      SPDX-License-Identifier: AGPL3.0-or-later
  19  */
  20
  21 /**
  22  * @author Florian Dold
  23  * @author Christian Grothoff
  24  *
  25  * @file
  26  * Two-peer set operations
  27  *
  28  * @defgroup set  Set service
  29  * Two-peer set operations
  30  *
  31  * @see [Documentation](https://gnunet.org/set-subsystem)
  32  *
  33  * @{
  34  */
  35
  36 #ifndef GNUNET_SET_SERVICE_H
  37 #define GNUNET_SET_SERVICE_H
  38
  39 #ifdef __cplusplus
  40 extern "C"
  41 {
  42 #if 0                           /* keep Emacsens' auto-indent happy */
  43 }
  44 #endif
  45 #endif
  46
  47 #include "gnunet_common.h"
  48 #include "gnunet_time_lib.h"
  49 #include "gnunet_configuration_lib.h"
  50
  51
  52 /**
  53  * Maximum size of a context message for set operation requests.
  54  */
  55 #define GNUNET_SET_CONTEXT_MESSAGE_MAX_SIZE ((1 << 16) - 1024)
  56
  57
  58 /**
  59  * Opaque handle to a set.
  60  */
  61 struct GNUNET_SET_Handle;
  62
  63 /**
  64  * Opaque handle to a set operation request from another peer.
  65  */
  66 struct GNUNET_SET_Request;
  67
  68 /**
  69  * Opaque handle to a listen operation.
  70  */
  71 struct GNUNET_SET_ListenHandle;
  72
  73 /**
  74  * Opaque handle to a set operation.
  75  */
  76 struct GNUNET_SET_OperationHandle;
  77
  78
  79 /**
  80  * The operation that a set set supports.
  81  */
  82 enum GNUNET_SET_OperationType
  83 {
  84   /**
  85    * A purely local set that does not support any operation.
  86    */
  87   GNUNET_SET_OPERATION_NONE,
  88
  89   /**
  90    * Set intersection, only return elements that are in both sets.
  91    */
  92   GNUNET_SET_OPERATION_INTERSECTION,
  93
  94   /**
  95    * Set union, return all elements that are in at least one of the sets.
  96    */
  97   GNUNET_SET_OPERATION_UNION
  98 };
  99
 100
 101 /**
 102  * Status for the result callback
 103  */
 104 enum GNUNET_SET_Status
 105 {
 106   /**
 107    * Everything went ok, we are transmitting an element of the
 108    * result (in set, or to be removed from set, depending on
 109    * the `enum GNUNET_SET_ResultMode`).
 110    *
 111    * Only applies to
 112    * #GNUNET_SET_RESULT_FULL,
 113    * #GNUNET_SET_RESULT_ADDED,
 114    * #GNUNET_SET_RESULT_REMOVED,
 115    */
 116   GNUNET_SET_STATUS_OK,
 117
 118   /**
 119    * Element should be added to the result set
 120    * of the local peer, i.e. the local peer is
 121    * missing an element.
 122    *
 123    * Only applies to #GNUNET_SET_RESULT_SYMMETRIC
 124    */
 125   GNUNET_SET_STATUS_ADD_LOCAL,
 126
 127   /**
 128    * Element should be added to the result set
 129    * of the remote peer, i.e. the remote peer is
 130    * missing an element.
 131    *
 132    * Only applies to #GNUNET_SET_RESULT_SYMMETRIC
 133    */
 134   GNUNET_SET_STATUS_ADD_REMOTE,
 135
 136   /**
 137    * The other peer refused to to the operation with us,
 138    * or something went wrong.
 139    */
 140   GNUNET_SET_STATUS_FAILURE,
 141
 142   /**
 143    * Success, all elements have been returned (but the other peer
 144    * might still be receiving some from us, so we are not done).  Only
 145    * used during UNION operation.
 146    */
 147   GNUNET_SET_STATUS_HALF_DONE,
 148
 149   /**
 150    * Success, all elements have been sent (and received).
 151    */
 152   GNUNET_SET_STATUS_DONE
 153 };
 154
 155
 156 /**
 157  * The way results are given to the client.
 158  */
 159 enum GNUNET_SET_ResultMode
 160 {
 161   /**
 162    * Client gets every element in the resulting set.
 163    *
 164    * Only supported for set intersection.
 165    */
 166   GNUNET_SET_RESULT_FULL,
 167
 168   /**
 169    * Client gets notified of the required changes
 170    * for both the local and the remote set.
 171    *
 172    * Only supported for set
 173    */
 174   GNUNET_SET_RESULT_SYMMETRIC,
 175
 176   /**
 177    * Client gets only elements that have been removed from the set.
 178    *
 179    * Only supported for set intersection.
 180    */
 181   GNUNET_SET_RESULT_REMOVED,
 182
 183   /**
 184    * Client gets only elements that have been added to the set.
 185    *
 186    * Only supported for set union.
 187    */
 188   GNUNET_SET_RESULT_ADDED
 189 };
 190
 191
 192 /**
 193  * Element stored in a set.
 194  */
 195 struct GNUNET_SET_Element
 196 {
 197   /**
 198    * Number of bytes in the buffer pointed to by data.
 199    */
 200   uint16_t size;
 201
 202   /**
 203    * Application-specific element type.
 204    */
 205   uint16_t element_type;
 206
 207   /**
 208    * Actual data of the element
 209    */
 210   const void *data;
 211 };
 212
 213
 214 /**
 215  * Possible options to pass to a set operation.
 216  *
 217  * Used as tag for struct #GNUNET_SET_Option.
 218  */
 219 enum GNUNET_SET_OptionType
 220 {
 221   /**
 222    * List terminator.
 223    */
 224   GNUNET_SET_OPTION_END=0,
 225   /**
 226    * Fail set operations when the other peer shows weird behavior
 227    * that might by a Byzantine fault.
 228    *
 229    * For set union, 'v.num' is a lower bound on elements
 230    * that the other peer must have in common with us.
 231    */
 232   GNUNET_SET_OPTION_BYZANTINE=1,
 233   /**
 234    * Do not use the optimized set operation, but send full sets.
 235    * Might trigger Byzantine fault detection.
 236    */
 237   GNUNET_SET_OPTION_FORCE_FULL=2,
 238   /**
 239    * Only use optimized set operations, even though for this
 240    * particular set operation they might be much slower.
 241    * Might trigger Byzantine fault detection.
 242    */
 243   GNUNET_SET_OPTION_FORCE_DELTA=4,
 244 };
 245
 246
 247 /**
 248  * Option for set operations.
 249  */
 250 struct GNUNET_SET_Option
 251 {
 252   /**
 253    * Type of the option.
 254    */
 255   enum GNUNET_SET_OptionType type;
 256
 257   /**
 258    * Value for the option, only used with some options.
 259    */
 260   union
 261   {
 262     uint64_t num;
 263   } v;
 264 };
 265
 266
 267 /**
 268  * Continuation used for some of the set operations
 269  *
 270  * @param cls closure
 271  */
 272 typedef void
 273 (*GNUNET_SET_Continuation) (void *cls);
 274
 275
 276 /**
 277  * Callback for set operation results. Called for each element
 278  * in the result set.
 279  *
 280  * @param cls closure
 281  * @param element a result element, only valid if status is #GNUNET_SET_STATUS_OK
 282  * @param current_size current set size
 283  * @param status see `enum GNUNET_SET_Status`
 284  */
 285 typedef void
 286 (*GNUNET_SET_ResultIterator) (void *cls,
 287                               const struct GNUNET_SET_Element *element,
 288                               uint64_t current_size,
 289                               enum GNUNET_SET_Status status);
 290
 291 /**
 292  * Iterator for set elements.
 293  *
 294  * @param cls closure
 295  * @param element the current element, NULL if all elements have been
 296  *        iterated over
 297  * @return #GNUNET_YES to continue iterating, #GNUNET_NO to stop.
 298  */
 299 typedef int
 300 (*GNUNET_SET_ElementIterator) (void *cls,
 301                                const struct GNUNET_SET_Element *element);
 302
 303
 304 /**
 305  * Called when another peer wants to do a set operation with the
 306  * local peer. If a listen error occurs, the @a request is NULL.
 307  *
 308  * @param cls closure
 309  * @param other_peer the other peer
 310  * @param context_msg message with application specific information from
 311  *        the other peer
 312  * @param request request from the other peer (never NULL), use GNUNET_SET_accept()
 313  *        to accept it, otherwise the request will be refused
 314  *        Note that we can't just return value from the listen callback,
 315  *        as it is also necessary to specify the set we want to do the
 316  *        operation with, whith sometimes can be derived from the context
 317  *        message. It's necessary to specify the timeout.
 318  */
 319 typedef void
 320 (*GNUNET_SET_ListenCallback) (void *cls,
 321                               const struct GNUNET_PeerIdentity *other_peer,
 322                               const struct GNUNET_MessageHeader *context_msg,
 323                               struct GNUNET_SET_Request *request);
 324
 325
 326 typedef void
 327 (*GNUNET_SET_CopyReadyCallback) (void *cls,
 328                                  struct GNUNET_SET_Handle *copy);
 329
 330
 331 /**
 332  * Create an empty set, supporting the specified operation.
 333  *
 334  * @param cfg configuration to use for connecting to the
 335  *        set service
 336  * @param op operation supported by the set
 337  *        Note that the operation has to be specified
 338  *        beforehand, as certain set operations need to maintain
 339  *        data structures spefific to the operation
 340  * @return a handle to the set
 341  */
 342 struct GNUNET_SET_Handle *
 343 GNUNET_SET_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
 344                    enum GNUNET_SET_OperationType op);
 345
 346
 347 /**
 348  * Add an element to the given set.
 349  * After the element has been added (in the sense of being
 350  * transmitted to the set service), @a cont will be called.
 351  * Calls to #GNUNET_SET_add_element can be queued
 352  *
 353  * @param set set to add element to
 354  * @param element element to add to the set
 355  * @param cont continuation called after the element has been added
 356  * @param cont_cls closure for @a cont
 357  * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
 358  *         set is invalid (e.g. the set service crashed)
 359  */
 360 int
 361 GNUNET_SET_add_element (struct GNUNET_SET_Handle *set,
 362                         const struct GNUNET_SET_Element *element,
 363                         GNUNET_SET_Continuation cont,
 364                         void *cont_cls);
 365
 366
 367 /**
 368  * Remove an element to the given set.
 369  * After the element has been removed (in the sense of the
 370  * request being transmitted to the set service), cont will be called.
 371  * Calls to remove_element can be queued
 372  *
 373  * @param set set to remove element from
 374  * @param element element to remove from the set
 375  * @param cont continuation called after the element has been removed
 376  * @param cont_cls closure for @a cont
 377  * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
 378  *         set is invalid (e.g. the set service crashed)
 379  */
 380 int
 381 GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set,
 382                            const struct GNUNET_SET_Element *element,
 383                            GNUNET_SET_Continuation cont,
 384                            void *cont_cls);
 385
 386
 387 void
 388 GNUNET_SET_copy_lazy (struct GNUNET_SET_Handle *set,
 389                       GNUNET_SET_CopyReadyCallback cb,
 390                       void *cls);
 391
 392
 393 /**
 394  * Destroy the set handle, and free all associated resources.
 395  * Iterations must have completed (or be explicitly canceled)
 396  * before destroying the corresponding set.  Operations may
 397  * still be pending when a set is destroyed.
 398  *
 399  * @param set set to destroy
 400  */
 401 void
 402 GNUNET_SET_destroy (struct GNUNET_SET_Handle *set);
 403
 404
 405 /**
 406  * Prepare a set operation to be evaluated with another peer.
 407  * The evaluation will not start until the client provides
 408  * a local set with GNUNET_SET_commit().
 409  *
 410  * @param other_peer peer with the other set
 411  * @param app_id hash for the application using the set
 412  * @param context_msg additional information for the request
 413  * @param result_mode specified how results will be returned,
 414  *        see `enum GNUNET_SET_ResultMode`.
 415  * @param result_cb called on error or success
 416  * @param result_cls closure for @a result_cb
 417  * @return a handle to cancel the operation
 418  */
 419 struct GNUNET_SET_OperationHandle *
 420 GNUNET_SET_prepare (const struct GNUNET_PeerIdentity *other_peer,
 421                     const struct GNUNET_HashCode *app_id,
 422                     const struct GNUNET_MessageHeader *context_msg,
 423                     enum GNUNET_SET_ResultMode result_mode,
 424                     struct GNUNET_SET_Option options[],
 425                     GNUNET_SET_ResultIterator result_cb,
 426                     void *result_cls);
 427
 428
 429 /**
 430  * Wait for set operation requests for the given application ID.
 431  * If the connection to the set service is lost, the listener is
 432  * re-created transparently with exponential backoff.
 433  *
 434  * @param cfg configuration to use for connecting to
 435  *            the set service
 436  * @param operation operation we want to listen for
 437  * @param app_id id of the application that handles set operation requests
 438  * @param listen_cb called for each incoming request matching the operation
 439  *                  and application id
 440  * @param listen_cls handle for @a listen_cb
 441  * @return a handle that can be used to cancel the listen operation
 442  */
 443 struct GNUNET_SET_ListenHandle *
 444 GNUNET_SET_listen (const struct GNUNET_CONFIGURATION_Handle *cfg,
 445                    enum GNUNET_SET_OperationType op_type,
 446                    const struct GNUNET_HashCode *app_id,
 447                    GNUNET_SET_ListenCallback listen_cb,
 448                    void *listen_cls);
 449
 450
 451 /**
 452  * Cancel the given listen operation.  After calling cancel, the
 453  * listen callback for this listen handle will not be called again.
 454  * Note that cancelling a listen operation will automatically reject
 455  * all operations that have not yet been accepted.
 456  *
 457  * @param lh handle for the listen operation
 458  */
 459 void
 460 GNUNET_SET_listen_cancel (struct GNUNET_SET_ListenHandle *lh);
 461
 462
 463 /**
 464  * Accept a request we got via GNUNET_SET_listen().  Must be called during
 465  * GNUNET_SET_listen(), as the `struct GNUNET_SET_Request` becomes invalid
 466  * afterwards.
 467  * Call GNUNET_SET_commit() to provide the local set to use for the operation,
 468  * and to begin the exchange with the remote peer.
 469  *
 470  * @param request request to accept
 471  * @param result_mode specified how results will be returned,
 472  *        see `enum GNUNET_SET_ResultMode`.
 473  * @param result_cb callback for the results
 474  * @param result_cls closure for @a result_cb
 475  * @return a handle to cancel the operation
 476  */
 477 struct GNUNET_SET_OperationHandle *
 478 GNUNET_SET_accept (struct GNUNET_SET_Request *request,
 479                    enum GNUNET_SET_ResultMode result_mode,
 480                    struct GNUNET_SET_Option options[],
 481                    GNUNET_SET_ResultIterator result_cb,
 482                    void *result_cls);
 483
 484
 485 /**
 486  * Commit a set to be used with a set operation.
 487  * This function is called once we have fully constructed
 488  * the set that we want to use for the operation.  At this
 489  * time, the P2P protocol can then begin to exchange the
 490  * set information and call the result callback with the
 491  * result information.
 492  *
 493  * @param oh handle to the set operation
 494  * @param set the set to use for the operation
 495  * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
 496  *         set is invalid (e.g. the set service crashed)
 497  */
 498 int
 499 GNUNET_SET_commit (struct GNUNET_SET_OperationHandle *oh,
 500                    struct GNUNET_SET_Handle *set);
 501
 502
 503 /**
 504  * Cancel the given set operation.  May not be called after the
 505  * operation's `GNUNET_SET_ResultIterator` has been called with a
 506  * status that indicates error, timeout or done.
 507  *
 508  * @param oh set operation to cancel
 509  */
 510 void
 511 GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *oh);
 512
 513
 514 /**
 515  * Iterate over all elements in the given set.
 516  * Note that this operation involves transferring every element of the set
 517  * from the service to the client, and is thus costly.
 518  * Only one iteration per set may be active at the same time.
 519  *
 520  * @param set the set to iterate over
 521  * @param iter the iterator to call for each element
 522  * @param iter_cls closure for @a iter
 523  * @return #GNUNET_YES if the iteration started successfuly,
 524  *         #GNUNET_NO if another iteration was still active,
 525  *         #GNUNET_SYSERR if the set is invalid (e.g. the server crashed, disconnected)
 526  */
 527 int
 528 GNUNET_SET_iterate (struct GNUNET_SET_Handle *set,
 529                     GNUNET_SET_ElementIterator iter,
 530                     void *iter_cls);
 531
 532
 533 /**
 534  * Stop iteration over all elements in the given set.  Can only
 535  * be called before the iteration has "naturally" completed its
 536  * turn.
 537  *
 538  * @param set the set to stop iterating over
 539  */
 540 void
 541 GNUNET_SET_iterate_cancel (struct GNUNET_SET_Handle *set);
 542
 543
 544 /**
 545  * Create a copy of an element.  The copy
 546  * must be GNUNET_free-d by the caller.
 547  *
 548  * @param element the element to copy
 549  * @return the copied element
 550  */
 551 struct GNUNET_SET_Element *
 552 GNUNET_SET_element_dup (const struct GNUNET_SET_Element *element);
 553
 554
 555 /**
 556  * Hash a set element.
 557  *
 558  * @param element the element that should be hashed
 559  * @param ret_hash a pointer to where the hash of @a element
 560  *        should be stored
 561  */
 562 void
 563 GNUNET_SET_element_hash (const struct GNUNET_SET_Element *element,
 564                          struct GNUNET_HashCode *ret_hash);
 565
 566
 567 #if 0                           /* keep Emacsens' auto-indent happy */
 568 {
 569 #endif
 570 #ifdef __cplusplus
 571 }
 572 #endif
 573
 574 #endif
 575
 576 /** @} */  /* end of group */