added many comments

documented set-union state "machine"
removed many deprecated struct-members from state, ops-spec
improved doxygen-compliant

3 files changed, 63 insertions, 69 deletions

diff --git a/src/set/gnunet-service-set.h b/src/set/gnunet-service-set.h
index 7a2c5ba8d..dd6e91da8 100644
--- a/src/set/gnunet-service-set.h
+++ b/src/set/gnunet-service-set.h
@@ -91,7 +91,7 @@ struct OperationSpecification
   uint32_t salt;
 
   /**
-   * ID used to identify responses to a client.
+   * ID used to identify an operation between service and client 
    */
   uint32_t client_request_id;
 
@@ -168,16 +168,12 @@ typedef void (*OpCreateImpl) (struct Operation *op);
 typedef int (*MsgHandlerImpl) (struct Operation *op,
                                const struct GNUNET_MessageHeader *msg);
 
-typedef void (*CancelImpl) (struct Operation *op);
-
-
 /**
- * Signature of functions that implement sending all the set's
- * elements to the client.
+ * Signature of functions that implement operation cancellation
  *
- * @param set set that should be iterated over
+ * @param op operation state
  */
-typedef void (*IterateImpl) (struct Set *set);
+typedef void (*CancelImpl) (struct Operation *op);
 
 
 /**
@@ -233,11 +229,6 @@ struct SetVT
    * its ID.
    */
   CancelImpl cancel;
-
-  /**
-   * Callback for iterating over all set elements.
-   */
-  IterateImpl iterate;
 };
 
 
@@ -285,6 +276,8 @@ struct ElementEntry
   /**
    * GNUNET_YES if the element is a remote element, and does not belong
    * to the operation's set.
+   * 
+   * //TODO: Move to Union, unless additional set-operations are implemented ever
    */
   int remote;
 };
@@ -295,6 +288,8 @@ struct Operation
   /**
    * V-Table for the operation belonging
    * to the tunnel contest.
+   * 
+   * Used for all operation specific operations after receiving the ops request
    */
   const struct SetVT *vt;
 
@@ -311,6 +306,8 @@ struct Operation
   /**
    * GNUNET_YES if this is not a "real" set operation yet, and we still
    * need to wait for the other peer to give us more details.
+   * 
+   * //TODO: replace with state-enum
    */
   int is_incoming;
 
@@ -372,6 +369,9 @@ struct Set
   /**
    * Virtual table for this set.
    * Determined by the operation type of this set.
+   * 
+   * Used only for Add/remove of elements and when receiving an incoming 
+   * operation from a remote peer.
    */
   const struct SetVT *vt;
 
@@ -421,6 +421,13 @@ struct Set
 };
 
 
+/**
+ * Destroy the given operation.  Call the implementation-specific cancel function
+ * of the operation.  Disconnects from the remote peer.
+ * Does not disconnect the client, as there may be multiple operations per set.
+ *
+ * @param op operation to destroy
+ */
 void
 _GSS_operation_destroy (struct Operation *op);
 
@@ -428,6 +435,8 @@ _GSS_operation_destroy (struct Operation *op);
 /**
  * Get the table with implementing functions for
  * set union.
+ * 
+ * @return the operation specific VTable
  */
 const struct SetVT *
 _GSS_union_vt (void);
@@ -436,6 +445,8 @@ _GSS_union_vt (void);
 /**
  * Get the table with implementing functions for
  * set intersection.
+ * 
+ * @return the operation specific VTable
  */
 const struct SetVT *
 _GSS_intersection_vt (void);
diff --git a/src/set/gnunet-service-set_intersection.c b/src/set/gnunet-service-set_intersection.c
index 0e0450bd1..de5198b9c 100644
--- a/src/set/gnunet-service-set_intersection.c
+++ b/src/set/gnunet-service-set_intersection.c
@@ -58,22 +58,6 @@ enum IntersectionOperationPhase
 struct OperationState
 {
   /**
-   * Tunnel to the remote peer.
-   */
-  struct GNUNET_MESH_Tunnel *tunnel;
-
-  /**
-   * Detail information about the set operation,
-   * including the set to use.
-   */
-  struct OperationSpecification *spec;
-
-  /**
-   * Message queue for the peer.
-   */
-  struct GNUNET_MQ_Handle *mq;
-
-  /**
    * The bf we currently receive
    */
   struct GNUNET_CONTAINER_BloomFilter *remote_bf;
@@ -93,12 +77,6 @@ struct OperationState
    * was created.
    */
   unsigned int generation_created;
-
-  /**
-   * Set state of the set that this operation
-   * belongs to.
-   */
-  struct Set *set;
   
   /**
    * Maps element-id-hashes to 'elements in our set'.
@@ -134,24 +112,6 @@ struct OperationState
 };
 
 
-/**
- * Extra state required for efficient set intersection.
- */
-struct SetState
-{
-  /**
-   * Evaluate operations are held in
-   * a linked list.
-   */
-  struct OperationState *ops_head;
-
-  /**
-   * Evaluate operations are held in
-   * a linked list.
-   */
-  struct OperationState *ops_tail;
-};
-
 
 /**
  * Destroy a intersection operation, and free all resources
@@ -739,7 +699,11 @@ finish_and_destroy (struct Operation *op)
   send_done_and_destroy (op);
 }
 
-
+/**
+ * handler for peer-disconnects, notifies the client about the aborted operation
+ * 
+ * @param op the destroyed operation
+ */
 static void
 intersection_peer_disconnect (struct Operation *op)
 {
diff --git a/src/set/gnunet-service-set_union.c b/src/set/gnunet-service-set_union.c
index 6bd86c5b5..826071af8 100644
--- a/src/set/gnunet-service-set_union.c
+++ b/src/set/gnunet-service-set_union.c
@@ -74,22 +74,35 @@ enum UnionOperationPhase
    */
   PHASE_EXPECT_SE,
   /**
-   * We sent the strata estimator, and expect an IBF
+   * We sent the strata estimator, and expect an IBF. This phase is entered once 
+   * upon initialization and later via PHASE_EXPECT_ELEMENTS_AND_REQUESTS.
+   * 
+   * After receiving the complete IBF, we enter PHASE_EXPECT_ELEMENTS
    */
   PHASE_EXPECT_IBF,
   /**
-   * We know what type of IBF the other peer wants to send us,
-   * and expect the remaining parts
+   * Continuation for multi part IBFs.
    */
   PHASE_EXPECT_IBF_CONT,
   /**
    * We are sending request and elements,
    * and thus only expect elements from the other peer.
+   * 
+   * We are currently decoding an IBF until it can no longer be decoded,
+   * we currently send requests and expect elements
+   * The remote peer is in PHASE_EXPECT_ELEMENTS_AND_REQUESTS
    */
   PHASE_EXPECT_ELEMENTS,
   /**
    * We are expecting elements and requests, and send
    * requested elements back to the other peer.
+   * 
+   * We are in this phase if we have SENT an IBF for the remote peer to decode.
+   * We expect requests, send elements or could receive an new IBF, which takes
+   * us via PHASE_EXPECT_IBF to phase PHASE_EXPECT_ELEMENTS
+   * 
+   * The remote peer is thus in:
+   * PHASE_EXPECT_ELEMENTS 
    */
   PHASE_EXPECT_ELEMENTS_AND_REQUESTS,
   /**
@@ -107,16 +120,6 @@ enum UnionOperationPhase
 struct OperationState
 {
   /**
-   * Tunnel to the remote peer.
-   */
-  struct GNUNET_MESH_Tunnel *tunnel;
-
-  /**
-   * Message queue for the peer.
-   */
-  struct GNUNET_MQ_Handle *mq;
-
-  /**
    * Number of ibf buckets received
    */
   unsigned int ibf_buckets_received;
@@ -1195,6 +1198,7 @@ static void
 union_evaluate (struct Operation *op)
 {
   op->state = GNUNET_new (struct OperationState);
+  // copy the current generation's strata estimator for this operation
   op->state->se = strata_estimator_dup (op->spec->set->state->se);
   /* we started the operation, thus we have to send the operation request */
   op->state->phase = PHASE_EXPECT_SE;
@@ -1222,7 +1226,10 @@ union_accept (struct Operation *op)
 
 /**
  * Create a new set supporting the union operation
- *
+ * 
+ * We maintain one strata estimator per set and then manipulate it over the
+ * lifetime of the set, as recreating a strata estimator would be expensive.
+ * 
  * @return the newly created set
  */
 static struct SetState *
@@ -1321,7 +1328,12 @@ union_handle_p2p_message (struct Operation *op,
   return GNUNET_OK;
 }
 
-
+/**
+ * handler for peer-disconnects, notifies the client 
+ * about the aborted operation in case the op was not concluded
+ * 
+ * @param op the destroyed operation
+ */
 static void
 union_peer_disconnect (struct Operation *op)
 {
@@ -1339,12 +1351,19 @@ union_peer_disconnect (struct Operation *op)
     _GSS_operation_destroy (op);
     return;
   }
+  // else: the session has already been concluded
   GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "other peer disconnected (finished)\n");
   if (GNUNET_NO == op->state->client_done_sent)
     finish_and_destroy (op);
 }
 
 
+/**
+ * Get the table with implementing functions for
+ * set union.
+ * 
+ * @return the operation specific VTable
+ */
 const struct SetVT *
 _GSS_union_vt ()
 {