started implementing set api, draft for mq

3 files changed, 262 insertions, 61 deletions

diff --git a/src/include/gnunet_protocols.h b/src/include/gnunet_protocols.h
index 431542660..54e059907 100644
--- a/src/include/gnunet_protocols.h
+++ b/src/include/gnunet_protocols.h
@@ -1760,8 +1760,66 @@ extern "C"
 #define GNUNET_MESSAGE_TYPE_CONSENSUS_P2P_ABORT 548
 
 
+/*******************************************************************************
+ * SET message types
+ ******************************************************************************/
+
+/**
+ * Cancel a set operation
+ */
+#define GNUNET_MESSAGE_TYPE_SET_CANCEL 570
+
+/**
+ * Acknowledge results
+ */
+#define GNUNET_MESSAGE_TYPE_SET_ACK 571
+
+/**
+ * Create an empty set
+ */
+#define GNUNET_MESSAGE_TYPE_SET_RESULT 572
+
+/**
+ * Add element to set
+ */
+#define GNUNET_MESSAGE_TYPE_SET_ADD 573
+
+
+/**
+ * Remove element from set
+ */
+#define GNUNET_MESSAGE_TYPE_SET_REMOVE 574
+
+
+/**
+ * Listen for operation requests
+ */
+#define GNUNET_MESSAGE_TYPE_SET_LISTEN 575
+
+/**
+ * Accept a set request
+ */
+#define GNUNET_MESSAGE_TYPE_SET_ACCEPT 576
+
+/**
+ * Evaluate a set operation
+ */
+#define GNUNET_MESSAGE_TYPE_SET_EVALUATE 577
+
+/**
+ * Evaluate a set operation
+ */
+#define GNUNET_MESSAGE_TYPE_SET_REQUEST 578
+
+
+/**
+ * Evaluate a set operation
+ */
+#define GNUNET_MESSAGE_TYPE_SET_CREATE 579
+
+
 /**
- *  Next available: 570
+ *  Next available: 600
  */
 
 
diff --git a/src/include/gnunet_set_service.h b/src/include/gnunet_set_service.h
index 78dc7b7d0..cf782c841 100644
--- a/src/include/gnunet_set_service.h
+++ b/src/include/gnunet_set_service.h
@@ -1,9 +1,76 @@
-// FIXME: copyright, etc.
+/*
+      This file is part of GNUnet
+      (C) 2013 Christian Grothoff (and other contributing authors)
+
+      GNUnet is free software; you can redistribute it and/or modify
+      it under the terms of the GNU General Public License as published
+      by the Free Software Foundation; either version 2, or (at your
+      option) any later version.
+
+      GNUnet is distributed in the hope that it will be useful, but
+      WITHOUT ANY WARRANTY; without even the implied warranty of
+      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+      General Public License for more details.
+
+      You should have received a copy of the GNU General Public License
+      along with GNUnet; see the file COPYING.  If not, write to the
+      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+      Boston, MA 02111-1307, USA.
+ */
+
+/**
+ * @file include/gnunet_set_service.h
+ * @brief two-peer set operations
+ * @author Florian Dold
+ */
+
+#ifndef GNUNET_SET_SERVICE_H
+#define GNUNET_SET_SERVICE_H
+
+#ifdef __cplusplus
+extern "C"
+{
+#if 0                           /* keep Emacsens' auto-indent happy */
+}
+#endif
+#endif
+
+#include "platform.h"
+#include "gnunet_common.h"
+#include "gnunet_time_lib.h"
+#include "gnunet_configuration_lib.h"
+
+
+/**
+ * Opaque handle to a set.
+ */
+struct GNUNET_SET_Handle;
+
+/**
+ * Opaque handle to a set operation request from another peer.
+ */
+struct GNUNET_SET_Request;
+
+/**
+ * Opaque handle to a listen operation.
+ */
+struct GNUNET_SET_ListenHandle;
+
+/**
+ * Opaque handle to a set operation.
+ */
+struct GNUNET_SET_OperationHandle;
+
+
+/**
+ * Opaque handle to a listen operation.
+ */
+struct GNUNET_SET_ListenHandle;
 
 /**
  * The operation that a set set supports.
  */
-enum GNUNET_SET_Operation
+enum GNUNET_SET_OperationType
 {
   /**
    * Set intersection, only return elements that are in both sets.
@@ -31,10 +98,37 @@ enum GNUNET_SET_Status
   /*
    * The other peer refused to to the operation with us
    */
-  GNUNET_SET_STATUS_REFUSED
+  GNUNET_SET_STATUS_REFUSED,
+  /*
+   * Success, all elements have been sent.
+   */
+  GNUNET_SET_STATUS_DONE
 };
 
-// FIXME: comment
+/**
+ * The way results are given to the client.
+ */
+enum GNUNET_SET_ResultMode
+{
+  /**
+   * Client gets every element in the resulting set.
+   */
+  GNUNET_SET_RESULT_FULL,
+  /**
+   * Client gets only elements that have been added to the set.
+   * Only works with set union.
+   */
+  GNUNET_SET_RESULT_ADDED,
+  /**
+   * Client gets only elements that have been removed from the set.
+   * Only works with set intersection.
+   */
+  GNUNET_SET_RESULT_REMOVED
+};
+
+/**
+ * Element stored in a set.
+ */
 struct GNUNET_SET_Element
 {
   /**
@@ -53,8 +147,53 @@ struct GNUNET_SET_Element
 
 
 /**
+ * Continuation used for some of the set operations
+ *
+ * @cls closure
+ */
+typedef void (*GNUNET_SET_Continuation) (void *cls);
+
+/**
+ * Callback for set operation results. Called for each element
+ * in the result set.
+ *
+ * @param cls closure
+ * @param element a result element, only valid if status is GNUNET_SET_STATUS_OK
+ * @param status see enum GNUNET_SET_Status
+ */
+typedef void
+(*GNUNET_SET_ResultIterator) (void *cls,
+                              struct GNUNET_SET_Element *element,
+                              enum GNUNET_SET_Status status);
+
+
+/**
+ * Called when another peer wants to do a set operation with the
+ * local peer
+ *
+ * @param other_peer the other peer
+ * @param context_msg message with application specific information from
+ *        the other peer
+ * @param request request from the other peer, use GNUNET_SET_accept
+ *        to accept it, otherwise the request will be refused
+ *        Note that we don't use a return value here, as it is also
+ *        necessary to specify the set we want to do the operation with,
+ *        whith sometimes can be derived from the context message.
+ *        Also necessary to specify the timeout.
+ */
+typedef void
+(*GNUNET_SET_ListenCallback) (void *cls,
+                              const struct GNUNET_PeerIdentity *other_peer,
+                              const struct GNUNET_MessageHeader *context_msg,
+                              struct GNUNET_SET_Request *request);
+
+
+
+/**
  * Create an empty set, supporting the specified operation.
  *
+ * @param cfg configuration to use for connecting to the
+ *        set service
  * @param op operation supported by the set
  *        Note that the operation has to be specified
  *        beforehand, as certain set operations need to maintain
@@ -62,10 +201,21 @@ struct GNUNET_SET_Element
  * @return a handle to the set
  */
 struct GNUNET_SET_Handle *
-GNUNET_SET_create (enum GNUNET_SET_Operation op);
+GNUNET_SET_create (struct GNUNET_CONFIGURATION_Handle *cfg,
+                   enum GNUNET_SET_OperationType op);
 
 
-// FIXME: comment
+/**
+ * Add an element to the given set.
+ * After the element has been added (in the sense of being
+ * transmitted to the set service), cont will be called.
+ * Calls to add_element can be queued
+ *
+ * @param set set to add element to
+ * @param element element to add to the set
+ * @param cont continuation called after the element has been added
+ * @param cont_cls closure for cont
+ */
 void
 GNUNET_SET_add_element (struct GNUNET_SET_Handle *set,
                         const struct GNUNET_SET_Element *element,
@@ -73,7 +223,17 @@ GNUNET_SET_add_element (struct GNUNET_SET_Handle *set,
                         void *cont_cls);
 
 
-// FIXME: comment
+/**
+ * Remove an element to the given set.
+ * After the element has been removed (in the sense of the
+ * request being transmitted to the set service), cont will be called.
+ * Calls to remove_element can be queued
+ *
+ * @param set set to remove element from
+ * @param element element to remove from the set
+ * @param cont continuation called after the element has been removed
+ * @param cont_cls closure for cont
+ */
 void
 GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set,
                            const struct GNUNET_SET_Element *element,
@@ -81,37 +241,17 @@ GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set,
                            void *cont_cls);
 
 
-// FIXME: comment
-struct GNUNET_SET_Handle *
-GNUNET_SET_clone (struct GNUNET_SET_Handle *set);
-
-
-// FIXME: comment
-void
-GNUNET_SET_destroy (struct GNUNET_SET_Handle *set);
-
-
-
 /**
- * Callback for set operation results. Called for each element
- * in the result set.
-// FIXME: might want a way to just get the 'additional/removd' elements
- *
- * @param cls closure
- * @param element element, or NULL to indicate that all elements
- *        have been passed to the callback
- *        Only valid if (status==GNUNET_SET_STATUS_OK) holds.
- * @param status see enum GNUNET_SET_Status
+ * Destroy the set handle, and free all associated resources.
  */
-typedef void
-(*GNUNET_SET_ResultIterator) (void *cls,
-                              struct GNUNET_SET_Element *element,
-                              enum GNUNET_SET_ResultStatus status);
+void
+GNUNET_SET_destroy (struct GNUNET_SET_Handle *set);
 
 
 /**
  * Evaluate a set operation with our set and the set of another peer.
  *
+ * @param set set to use
  * @param other_peer peer with the other set
  * @param app_id hash for the application using the set
  * @param context_msg additional information for the request
@@ -120,38 +260,23 @@ typedef void
  * @return a handle to cancel the operation
  */
 struct GNUNET_SET_OperationHandle *
-GNUNET_SET_evaluate (const struct GNUNET_PeerIdentity *other_peer,
+GNUNET_SET_evaluate (struct GNUNET_SET_Handle *set,
+                     const struct GNUNET_PeerIdentity *other_peer,
                      const struct GNUNET_HashCode *app_id,
                      const struct GNUNET_MessageHeader *context_msg,
                      struct GNUNET_TIME_Relative timeout,
+                     enum GNUNET_SET_ResultMode result_mode,
                      GNUNET_SET_ResultIterator result_cb,
                      void *result_cls);
 
 
-/**
- * Called when another peer wants to do a set operation with the
- * local peer
- *
- * @param other_peer the other peer
- * @param context_msg message with application specific information from
- *        the other peer
- * @param request request from the other peer, use GNUNET_SET_accept
- *        to accept it, otherwise the request will be refused
- *        Note that we don't use a return value here, as it is also
- *        necessary to specify the set we want to do the operation with,
- *        whith sometimes can be derived from the context message.
- *        Also necessary to specify the timeout.
- */
-typedef void
-(*GNUNET_SET_ListenCallback) (void *cls,
-                              const struct GNUNET_PeerIdentity *other_peer,
-                              const struct GNUNET_MessageHeader *context_msg,
-                              struct GNUNET_SET_Request *request);
 
 
 /**
  * Wait for set operation requests for the given application id
  * 
+ * @param cfg configuration to use for connecting to
+ *            the set service
  * @param operation operation we want to listen for
  * @param app_id id of the application that handles set operation requests
  * @param listen_cb called for each incoming request matching the operation
@@ -160,14 +285,19 @@ typedef void
  * @return a handle that can be used to cancel the listen operation
  */
 struct GNUNET_SET_ListenHandle *
-GNUNET_SET_listen (enum GNUNET_SET_Operation operation,
+GNUNET_SET_listen (struct GNUNET_CONFIGURATION_Handle *cfg,
+                   enum GNUNET_SET_OperationType op_type,
                    const struct GNUNET_HashCode *app_id,
                    GNUNET_SET_ListenCallback listen_cb,
                    void *listen_cls);
 
 
 
-// FIXME: comment
+/**
+ * Cancel the given listen operation.
+ *
+ * @param lh handle for the listen operation
+ */
 void
 GNUNET_SET_listen_cancel (struct GNUNET_SET_ListenHandle *lh);
 
@@ -185,12 +315,25 @@ struct GNUNET_SET_OperationHandle *
 GNUNET_SET_accept (struct GNUNET_SET_Request *request,
                    struct GNUNET_SET_Handle *set,
                    struct GNUNET_TIME_Relative timeout,
+                   enum GNUNET_SET_ResultMode result_mode,
                    GNUNET_SET_ResultIterator result_cb,
-                   void *cls)
+                   void *cls);
 
 
-// FIXME: comment
+/**
+ * Cancel the given set operation.
+ *
+ * @param op set operation to cancel
+ */
 void
-GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *op);
-                          
+GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *oh);
+
+
+#if 0                           /* keep Emacsens' auto-indent happy */
+{
+#endif
+#ifdef __cplusplus
+}
+#endif
 
+#endif
diff --git a/src/include/gnunet_testing_lib.h b/src/include/gnunet_testing_lib.h
index 7181b9ca1..d96743615 100644
--- a/src/include/gnunet_testing_lib.h
+++ b/src/include/gnunet_testing_lib.h
@@ -325,9 +325,9 @@ GNUNET_TESTING_peer_stop_async (struct GNUNET_TESTING_Peer *peer,
  * @param cfg configuration of the peer that was started
  * @param peer identity of the peer that was created
  */
-typedef void (*GNUNET_TESTING_TestMain)(void *cls,
-                                        const struct GNUNET_CONFIGURATION_Handle *cfg,
-                                        struct GNUNET_TESTING_Peer *peer);
+typedef void (*GNUNET_TESTING_TestMain) (void *cls,
+                                         const struct GNUNET_CONFIGURATION_Handle *cfg,
+                                         struct GNUNET_TESTING_Peer *peer);
 
 
 /**