[GNUnet-SVN] r21283 - gnunet/src/testbed

[gnunet]

Author: grothoff
Date: 2012-05-05 20:51:21 +0200 (Sat, 05 May 2012)
New Revision: 21283

Modified:
   gnunet/src/testbed/testbed_api_operations.c
   gnunet/src/testbed/testbed_api_operations.h
Log:
-draft structure for operation queues

Modified: gnunet/src/testbed/testbed_api_operations.c
===================================================================
--- gnunet/src/testbed/testbed_api_operations.c 2012-05-05 18:29:32 UTC (rev 
21282)
+++ gnunet/src/testbed/testbed_api_operations.c 2012-05-05 18:51:21 UTC (rev 
21283)
@@ -32,12 +32,129 @@
  */
 struct GNUNET_TESTBED_Operation
 {
+  /**
+   * Function to call when we have the resources to begin the operation.
+   */
+  OperationStart start;
+
+  /**
+   * Function to call to clean up after the operation (which may or may
+   * not have been started yet).
+   */
+  OperationRelease release;
+                                
+  /**
+   * Closure for callbacks.
+   */
+  void *cb_cls;
+
   // FIXME!
+
 };
 
 
+/**
+ * Queue of operations where we can only support a certain
+ * number of concurrent operations of a particular type.
+ */
+struct OperationQueue
+{
 
+  /**
+   * Maximum number of operationst that can be concurrently
+   * active in this queue.
+   */
+  unsigned int max_active;
+
+  // FIXME!
+
+};
+
+
 /**
+ * Create an operation queue.
+ *
+ * @param max_active maximum number of operations in this
+ *        queue that can be active in parallel at the same time
+ * @return handle to the queue
+ */
+struct OperationQueue *
+GNUNET_TESTBED_operation_queue_create_ (unsigned int max_active)
+{
+  struct OperationQueue *queue;
+
+  queue = GNUNET_malloc (sizeof (struct OperationQueue));
+  queue->max_active = max_active;
+  return queue;
+}
+
+
+/**
+ * Destroy an operation queue.  The queue MUST be empty
+ * at this time.
+ *
+ * @param queue queue to destroy
+ */
+void
+GNUNET_TESTBED_operation_queue_destroy_ (struct OperationQueue *queue)
+{
+  GNUNET_break (0);
+  GNUNET_free (queue);
+}
+
+
+/**
+ * Add an operation to a queue.  An operation can be in multiple
+ * queues at once.  Once all queues permit the operation to become
+ * active, the operation will be activated.  The actual activation
+ * will occur in a separate task (thus allowing multiple queue 
+ * insertions to be made without having the first one instantly
+ * trigger the operation if the first queue has sufficient 
+ * resources).
+ *
+ * @param queue queue to add the operation to
+ * @param operation operation to add to the queue
+ */
+void
+GNUNET_TESTBED_operation_queue_insert_ (struct OperationQueue *queue,
+                                       struct GNUNET_TESTBED_Operation 
*operation)
+{
+  GNUNET_break (0);
+}
+
+
+/**
+ * Remove an operation from a queue.  This can be because the
+ * oeration was active and has completed (and the resources have
+ * been released), or because the operation was cancelled and
+ * thus scheduling the operation is no longer required.
+ *
+ * @param queue queue to add the operation to
+ * @param operation operation to add to the queue
+ */
+void
+GNUNET_TESTBED_operation_queue_remove_ (struct OperationQueue *queue,
+                                       struct GNUNET_TESTBED_Operation 
*operation)
+{
+  GNUNET_break (0);
+}
+
+
+/**
+ * An operation is 'done' (was cancelled or finished); remove
+ * it from the queues and release associated resources.
+ *
+ * @param operation operation that finished
+ */
+static void
+operation_release (struct GNUNET_TESTBED_Operation *operation)
+{
+  // call operation->release, remove from queues
+  GNUNET_break (0);
+}
+
+
+/**
  * Cancel a pending operation.  Releases all resources
  * of the operation and will ensure that no event
  * is generated for the operation.  Does NOT guarantee
@@ -49,8 +166,9 @@
 void
 GNUNET_TESTBED_operation_cancel (struct GNUNET_TESTBED_Operation *operation)
 {
+  // test that operation had not yet generated an event
   GNUNET_break (0);
-
+  operation_release (operation);
 }
 
 
@@ -66,7 +184,9 @@
 void
 GNUNET_TESTBED_operation_done (struct GNUNET_TESTBED_Operation *operation)
 {
+  // test that operation was started and had generated an event
   GNUNET_break (0);
+  operation_release (operation);
 }
 
 

Modified: gnunet/src/testbed/testbed_api_operations.h
===================================================================
--- gnunet/src/testbed/testbed_api_operations.h 2012-05-05 18:29:32 UTC (rev 
21282)
+++ gnunet/src/testbed/testbed_api_operations.h 2012-05-05 18:51:21 UTC (rev 
21283)
@@ -30,5 +30,103 @@
 #include "gnunet_helper_lib.h"
 
 
+/**
+ * Queue of operations where we can only support a certain
+ * number of concurrent operations of a particular type.
+ */
+struct OperationQueue;
+
+
+/**
+ * Create an operation queue.
+ *
+ * @param max_active maximum number of operations in this
+ *        queue that can be active in parallel at the same time
+ * @return handle to the queue
+ */
+struct OperationQueue *
+GNUNET_TESTBED_operation_queue_create_ (unsigned int max_active);
+
+
+/**
+ * Destroy an operation queue.  The queue MUST be empty
+ * at this time.
+ *
+ * @param queue queue to destroy
+ */
+void
+GNUNET_TESTBED_operation_queue_destroy_ (struct OperationQueue *queue);
+
+
+/**
+ * Add an operation to a queue.  An operation can be in multiple
+ * queues at once.  Once all queues permit the operation to become
+ * active, the operation will be activated.  The actual activation
+ * will occur in a separate task (thus allowing multiple queue 
+ * insertions to be made without having the first one instantly
+ * trigger the operation if the first queue has sufficient 
+ * resources).
+ *
+ * @param queue queue to add the operation to
+ * @param operation operation to add to the queue
+ */
+void
+GNUNET_TESTBED_operation_queue_insert_ (struct OperationQueue *queue,
+                                       struct GNUNET_TESTBED_Operation 
*operation);
+
+
+/**
+ * Remove an operation from a queue.  This can be because the
+ * oeration was active and has completed (and the resources have
+ * been released), or because the operation was cancelled and
+ * thus scheduling the operation is no longer required.
+ *
+ * @param queue queue to add the operation to
+ * @param operation operation to add to the queue
+ */
+void
+GNUNET_TESTBED_operation_queue_remove_ (struct OperationQueue *queue,
+                                       struct GNUNET_TESTBED_Operation 
*operation);
+
+
+
+/**
+ * Function to call to start an operation once all
+ * queues the operation is part of declare that the
+ * operation can be activated.
+ */
+typedef void (*OperationStart)(void *cls);
+
+
+/**
+ * Function to call to cancel an operation (release all associated
+ * resources).  This can be because of a call to
+ * "GNUNET_TESTBED_operation_cancel" (before the operation generated
+ * an event) or AFTER the operation generated an event due to a call
+ * to "GNUNET_TESTBED_operation_done".  Thus it is not guaranteed that
+ * a callback to the 'OperationStart' preceeds the call to
+ * 'OperationRelease'.  Implementations of this function are expected
+ * to clean up whatever state is in 'cls' and release all resources
+ * associated with the operation. 
+ */
+typedef void (*OperationRelease)(void *cls);
+
+
+/**
+ * Create an 'operation' to be performed.
+ *
+ * @param cls closure for the callbacks
+ * @param start function to call to start the operation
+ * @param release function to call to close down the operation
+ * @param ... FIXME
+ * @return handle to the operation
+ */
+struct GNUNET_TESTBED_Operation *
+GNUNET_TESTBED_operation_create_ (void *cls,
+                                 OperationStart start,
+                                 OperationRelease release,
+                                 ...);
+
+
 #endif
 /* end of testbed_api_operations.h */