From c7954a8ae4bd0e745de626e22b72328e7b2491f4 Mon Sep 17 00:00:00 2001 From: Christian Fuchs Date: Mon, 11 Nov 2013 17:32:48 +0000 Subject: added many comments documented set-union state "machine" removed many deprecated struct-members from state, ops-spec improved doxygen-compliant --- src/set/gnunet-service-set.h | 37 +++++++++++++++-------- src/set/gnunet-service-set_intersection.c | 46 ++++------------------------- src/set/gnunet-service-set_union.c | 49 +++++++++++++++++++++---------- 3 files changed, 63 insertions(+), 69 deletions(-) (limited to 'src/set') 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 @@ -57,22 +57,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 */ @@ -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, /** @@ -106,16 +119,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 */ @@ -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 () { -- cgit v1.2.3