-more datacache integration work

[oweals/gnunet.git] / src / include / gnunet_set_service.h

diff --git a/src/include/gnunet_set_service.h b/src/include/gnunet_set_service.h
index 1ff8d85d5cc98b36bcb536214cdbac354f9b6ac8..304bcf6d8d799113ee05069d93080a7c9b646064 100644 (file)
--- a/src/include/gnunet_set_service.h
+++ b/src/include/gnunet_set_service.h
@@ -1,6 +1,6 @@
 /*
       This file is part of GNUnet
-      (C) 2013, 2014 Christian Grothoff (and other contributing authors)
+      Copyright (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
@@ -74,8 +74,7 @@ struct GNUNET_SET_OperationHandle;
 enum GNUNET_SET_OperationType
 {
   /**
-   * A purely local set that does not support any
-   * operation.
+   * A purely local set that does not support any operation.
    */
   GNUNET_SET_OPERATION_NONE,
 
@@ -90,21 +89,19 @@ enum GNUNET_SET_OperationType
   GNUNET_SET_OPERATION_UNION
 };
 
+
 /**
  * Status for the result callback
  */
 enum GNUNET_SET_Status
 {
   /**
-   * Everything went ok.
+   * Everything went ok, we are transmitting an element of the
+   * result (in set, or to be removed from set, depending on
+   * the `enum GNUNET_SET_ResultMode`).
    */
   GNUNET_SET_STATUS_OK,
 
-  /**
-   * There was a timeout.
-   */
-  GNUNET_SET_STATUS_TIMEOUT,
-
   /**
    * The other peer refused to to the operation with us,
    * or something went wrong.
@@ -112,8 +109,9 @@ enum GNUNET_SET_Status
   GNUNET_SET_STATUS_FAILURE,
 
   /**
-   * Success, all elements have been returned (but the other
-   * peer might still be receiving some from us, so we are not done).
+   * Success, all elements have been returned (but the other peer
+   * might still be receiving some from us, so we are not done).  Only
+   * used during UNION operation.
    */
   GNUNET_SET_STATUS_HALF_DONE,
 
@@ -161,7 +159,7 @@ struct GNUNET_SET_Element
   /**
    * Application-specific element type.
    */
-  uint16_t type;
+  uint16_t element_type;
 
   /**
    * Actual data of the element
@@ -283,6 +281,11 @@ GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set,
 
 /**
  * Destroy the set handle, and free all associated resources.
+ * Iterations must have completed (or be explicitly canceled)
+ * before destroying the corresponding set.  Operations may
+ * still be pending when a set is destroyed.
+ *
+ * @param set set to destroy
  */
 void
 GNUNET_SET_destroy (struct GNUNET_SET_Handle *set);
@@ -334,9 +337,8 @@ GNUNET_SET_listen (const struct GNUNET_CONFIGURATION_Handle *cfg,
 
 
 /**
- * Cancel the given listen operation.
- * After calling cancel, the listen callback for this listen handle
- * will not be called again.
+ * Cancel the given listen operation.  After calling cancel, the
+ * listen callback for this listen handle will not be called again.
  *
  * @param lh handle for the listen operation
  */
@@ -384,9 +386,9 @@ GNUNET_SET_commit (struct GNUNET_SET_OperationHandle *oh,
 
 
 /**
- * Cancel the given set operation.
- * May not be called after the operation's `GNUNET_SET_ResultIterator` has been
- * called with a status that indicates error, timeout or done.
+ * Cancel the given set operation.  May not be called after the
+ * operation's `GNUNET_SET_ResultIterator` has been called with a
+ * status that indicates error, timeout or done.
  *
  * @param oh set operation to cancel
  */
@@ -404,13 +406,24 @@ GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *oh);
  * @param iter the iterator to call for each element
  * @param iter_cls closure for @a iter
  * @return #GNUNET_YES if the iteration started successfuly,
- *         #GNUNET_SYSERR if the set  is invalid (e.g. the server crashed, disconnected)
+ *         #GNUNET_NO if another iteration was still active,
+ *         #GNUNET_SYSERR if the set is invalid (e.g. the server crashed, disconnected)
  */
 int
 GNUNET_SET_iterate (struct GNUNET_SET_Handle *set,
                     GNUNET_SET_ElementIterator iter,
                     void *iter_cls);
 
+/**
+ * Stop iteration over all elements in the given set.  Can only
+ * be called before the iteration has "naturally" completed its
+ * turn.
+ *
+ * @param set the set to stop iterating over
+ */
+void
+GNUNET_SET_iterate_cancel (struct GNUNET_SET_Handle *set);
+
 
 #if 0                           /* keep Emacsens' auto-indent happy */
 {