/*
This file is part of GNUnet
- (C) 2013 Christian Grothoff (and other contributing authors)
+ (C) 2013, 2014 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
+ by the Free Software Foundation; either version 3, or (at your
option) any later version.
GNUnet is distributed in the hope that it will be useful, but
Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
*/
-
/**
* @file set/gnunet-service-set.h
* @brief common components for the implementation the different set operations
* @author Florian Dold
+ * @author Christian Grothoff
*/
-
#ifndef GNUNET_SERVICE_SET_H_PRIVATE
#define GNUNET_SERVICE_SET_H_PRIVATE
#include "platform.h"
-#include "gnunet_common.h"
+#include "gnunet_util_lib.h"
#include "gnunet_protocols.h"
#include "gnunet_applications.h"
-#include "gnunet_util_lib.h"
#include "gnunet_core_service.h"
-#include "gnunet_mesh_service.h"
+#include "gnunet_cadet_service.h"
#include "gnunet_set_service.h"
#include "set.h"
/**
- * Implementation-specific set state.
- * Used as opaque pointer, and specified further
- * in the respective implementation.
+ * Implementation-specific set state. Used as opaque pointer, and
+ * specified further in the respective implementation.
*/
struct SetState;
-
/**
- * Implementation-specific set operation.
- * Used as opaque pointer, and specified further
- * in the respective implementation.
+ * Implementation-specific set operation. Used as opaque pointer, and
+ * specified further in the respective implementation.
*/
struct OperationState;
-
-/* forward declarations */
+/**
+ * A set that supports a specific operation with other peers.
+ */
struct Set;
-struct TunnelContext;
+
+/**
+ * Information about an element element in the set. All elements are
+ * stored in a hash-table from their hash-code to their 'struct
+ * Element', so that the remove and add operations are reasonably
+ * fast.
+ */
+struct ElementEntry;
+
+/**
+ * Operation context used to execute a set operation.
+ */
+struct Operation;
/**
*/
struct OperationSpecification
{
- /**
- * The type of the operation.
- */
- enum GNUNET_SET_OperationType operation;
/**
- * The remove peer we evaluate the operation with
+ * The remove peer we evaluate the operation with.
*/
struct GNUNET_PeerIdentity peer;
*/
struct GNUNET_MessageHeader *context_msg;
+ /**
+ * Set associated with the operation, NULL until the spec has been
+ * associated with a set.
+ */
+ struct Set *set;
+
/**
* Salt to use for the operation.
*/
uint32_t salt;
/**
- * ID used to identify responses to a client.
+ * Remote peers element count
+ */
+ uint32_t remote_element_count;
+
+ /**
+ * ID used to identify an operation between service and client
*/
uint32_t client_request_id;
/**
- * Set associated with the operation, NULL until the spec has been associated
- * with a set.
+ * The type of the operation.
*/
- struct Set *set;
+ enum GNUNET_SET_OperationType operation;
+
+ /**
+ * When are elements sent to the client, and which elements are sent?
+ */
+ enum GNUNET_SET_ResultMode result_mode;
};
*
* @return a set state specific to the supported operation
*/
-typedef struct SetState *(*CreateImpl) (void);
+typedef struct SetState *
+(*CreateImpl) (void);
/**
* for a set supporting a specific operation.
*
* @param set implementation-specific set state
- * @param msg element message from the client
+ * @param ee element message from the client
*/
-typedef void (*AddRemoveImpl) (struct SetState *state, const struct GNUNET_SET_Element *element);
+typedef void
+(*AddRemoveImpl) (struct SetState *state,
+ struct ElementEntry *ee);
/**
- * Signature of functions that handle disconnection
- * of the remote peer.
+ * Signature of functions that handle disconnection of the remote
+ * peer.
*
* @param op the set operation, contains implementation-specific data
*/
-typedef void (*PeerDisconnectImpl) (struct OperationState *op);
+typedef void
+(*PeerDisconnectImpl) (struct Operation *op);
/**
*
* @param state the set state, contains implementation-specific data
*/
-typedef void (*DestroySetImpl) (struct SetState *state);
+typedef void
+(*DestroySetImpl) (struct SetState *state);
/**
- * Signature of functions that implement the creation of set operations
- * (currently evaluate and accept).
+ * Signature of functions that implement accepting a set operation.
*
- * @param spec specification of the set operation to be created
- * @param tunnel the tunnel with the other peer
- * @param tc tunnel context
+ * @param op operation that is created by accepting the operation,
+ * should be initialized by the implementation
*/
-typedef void (*OpCreateImpl) (struct OperationSpecification *spec,
- struct GNUNET_MESH_Tunnel *tunnel,
- struct TunnelContext *tc);
+typedef void
+(*OpAcceptImpl) (struct Operation *op);
+
+
+/**
+ * Signature of functions that implement starting the evaluation of
+ * set operations.
+ *
+ * @param op operation that is created, should be initialized to
+ * begin the evaluation
+ * @param opaque_context message to be transmitted to the listener
+ * to convince him to accept, may be NULL
+ */
+typedef void
+(*OpEvaluateImpl) (struct Operation *op,
+ const struct GNUNET_MessageHeader *opaque_context);
/**
*
* @param op operation state
* @param msg received message
- * @return GNUNET_OK on success, GNUNET_SYSERR to
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR to
* destroy the operation and the tunnel
*/
-typedef int (*MsgHandlerImpl) (struct OperationState *op,
- const struct GNUNET_MessageHeader *msg);
+typedef int
+(*MsgHandlerImpl) (struct Operation *op,
+ const struct GNUNET_MessageHeader *msg);
-typedef void (*CancelImpl) (struct SetState *set,
- uint32_t request_id);
+
+/**
+ * Signature of functions that implement operation cancellation
+ *
+ * @param op operation state
+ */
+typedef void
+(*CancelImpl) (struct Operation *op);
/**
- * Dispatch table for a specific set operation.
- * Every set operation has to implement the callback
- * in this struct.
+ * Dispatch table for a specific set operation. Every set operation
+ * has to implement the callback in this struct.
*/
struct SetVT
{
/**
* Callback for accepting a set operation request
*/
- OpCreateImpl accept;
+ OpAcceptImpl accept;
/**
* Callback for starting evaluation with a remote peer.
*/
- OpCreateImpl evaluate;
+ OpEvaluateImpl evaluate;
/**
* Callback for destruction of the set state.
MsgHandlerImpl msg_handler;
/**
- * Callback for handling the remote peer's
- * disconnect.
+ * Callback for handling the remote peer's disconnect.
*/
PeerDisconnectImpl peer_disconnect;
/**
- * Callback for canceling an operation by
- * its ID.
+ * Callback for canceling an operation by its ID.
*/
CancelImpl cancel;
};
/**
- * A set that supports a specific operation
- * with other peers.
+ * Information about an element element in the set. All elements are
+ * stored in a hash-table from their hash-code to their `struct
+ * Element`, so that the remove and add operations are reasonably
+ * fast.
*/
-struct Set
+struct ElementEntry
{
/**
- * Client that owns the set.
- * Only one client may own a set.
+ * The actual element. The data for the element
+ * should be allocated at the end of this struct.
*/
- struct GNUNET_SERVER_Client *client;
+ struct GNUNET_SET_Element element;
/**
- * Message queue for the client
+ * Hash of the element. For set union: Will be used to derive the
+ * different IBF keys for different salts.
*/
- struct GNUNET_MQ_Handle *client_mq;
+ struct GNUNET_HashCode element_hash;
/**
- * Type of operation supported for this set
+ * Generation the element was added by the client.
+ * Operations of earlier generations will not consider the element.
*/
- enum GNUNET_SET_OperationType operation;
+ unsigned int generation_added;
+
+ /**
+ * Generation the element was removed by the client.
+ * Operations of later generations will not consider the element.
+ * Only valid if @e removed is #GNUNET_YES.
+ */
+ unsigned int generation_removed;
+
+ /**
+ * #GNUNET_YES if the element has been removed in some generation.
+ */
+ int removed;
+
+ /**
+ * #GNUNET_YES if the element is a remote element, and does not belong
+ * to the operation's set.
+ */
+ int remote;
+};
+
+/**
+ * Operation context used to execute a set operation.
+ */
+struct Operation
+{
/**
- * Virtual table for this set.
- * Determined by the operation type of this set.
+ * 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;
/**
- * Sets are held in a doubly linked list.
+ * Tunnel to the peer.
*/
- struct Set *next;
+ struct GNUNET_CADET_Channel *channel;
/**
- * Sets are held in a doubly linked list.
+ * Message queue for the tunnel.
*/
- struct Set *prev;
+ struct GNUNET_MQ_Handle *mq;
/**
- * Implementation-specific state.
+ * Detail information about the set operation, including the set to
+ * use. When 'spec' is NULL, the operation is not yet entirely
+ * initialized.
*/
- struct SetState *state;
+ struct OperationSpecification *spec;
+
+ /**
+ * Operation-specific operation state. Note that the exact
+ * type depends on this being a union or intersection operation
+ * (and thus on @e vt).
+ */
+ struct OperationState *state;
+
+ /**
+ * Evaluate operations are held in a linked list.
+ */
+ struct Operation *next;
+
+ /**
+ * Evaluate operations are held in a linked list.
+ */
+ struct Operation *prev;
+
+ /**
+ * The identity of the requesting peer. Needs to
+ * be stored here as the op spec might not have been created yet.
+ */
+ struct GNUNET_PeerIdentity peer;
+
+ /**
+ * Timeout task, if the incoming peer has not been accepted
+ * after the timeout, it will be disconnected.
+ */
+ GNUNET_SCHEDULER_TaskIdentifier timeout_task;
+
+ /**
+ * Unique request id for the request from a remote peer, sent to the
+ * client, which will accept or reject the request. Set to '0' iff
+ * the request has not been suggested yet.
+ */
+ uint32_t suggest_id;
+
+ /**
+ * #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.
+ */
+ int is_incoming;
+
+ /**
+ * Generation in which the operation handle
+ * was created.
+ */
+ unsigned int generation_created;
+
+ /**
+ * Set to #GNUNET_YES if the set service should not free the
+ * operation, as it is still needed (e.g. in some scheduled task).
+ */
+ int keep;
};
/**
- * Information about a tunnel we are connected to.
- * Used as tunnel context with mesh.
+ * A set that supports a specific operation with other peers.
*/
-struct TunnelContext
+struct Set
{
+
+ /**
+ * Sets are held in a doubly linked list (in `sets_head` and `sets_tail`).
+ */
+ struct Set *next;
+
+ /**
+ * Sets are held in a doubly linked list.
+ */
+ struct Set *prev;
+
/**
- * V-Table for the operation belonging
- * to the tunnel contest.
+ * Client that owns the set. Only one client may own a set,
+ * and there can only be one set per client.
+ */
+ struct GNUNET_SERVER_Client *client;
+
+ /**
+ * Message queue for the client.
+ */
+ struct GNUNET_MQ_Handle *client_mq;
+
+ /**
+ * 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;
/**
- * Implementation-specific operation state.
+ * Implementation-specific state.
*/
- struct OperationState *op;
+ struct SetState *state;
+
+ /**
+ * Current state of iterating elements for the client.
+ * NULL if we are not currently iterating.
+ */
+ struct GNUNET_CONTAINER_MultiHashMapIterator *iter;
+
+ /**
+ * Maps `struct GNUNET_HashCode *` to `struct ElementEntry *`.
+ */
+ struct GNUNET_CONTAINER_MultiHashMap *elements;
+
+ /**
+ * Evaluate operations are held in a linked list.
+ */
+ struct Operation *ops_head;
+
+ /**
+ * Evaluate operations are held in a linked list.
+ */
+ struct Operation *ops_tail;
+
+ /**
+ * Current generation, that is, number of previously executed
+ * operations on this set
+ */
+ unsigned int current_generation;
+
+ /**
+ * Type of operation supported for this set
+ */
+ enum GNUNET_SET_OperationType operation;
+
+ /**
+ * Each @e iter is assigned a unique number, so that the client
+ * can distinguish iterations.
+ */
+ uint16_t iteration_id;
+
};
/**
- * Get the table with implementing functions for
- * set union.
+ * 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
+ * @param gc #GNUNET_YES to perform garbage collection on the set
+ */
+void
+_GSS_operation_destroy (struct Operation *op,
+ int gc);
+
+
+/**
+ * Get the table with implementing functions for set union.
+ *
+ * @return the operation specific VTable
*/
const struct SetVT *
_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);
+
+
#endif