src/testbed/testbed_api_operations.c

   1 /*
   2       This file is part of GNUnet
   3       (C) 2008--2012 Christian Grothoff (and other contributing authors)
   4
   5       GNUnet is free software; you can redistribute it and/or modify
   6       it under the terms of the GNU General Public License as published
   7       by the Free Software Foundation; either version 3, or (at your
   8       option) any later version.
   9
  10       GNUnet is distributed in the hope that it will be useful, but
  11       WITHOUT ANY WARRANTY; without even the implied warranty of
  12       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13       General Public License for more details.
  14
  15       You should have received a copy of the GNU General Public License
  16       along with GNUnet; see the file COPYING.  If not, write to the
  17       Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18       Boston, MA 02111-1307, USA.
  19  */
  20
  21 /**
  22  * @file testbed/testbed_api_operations.c
  23  * @brief functions to manage operation queues
  24  * @author Christian Grothoff
  25  */
  26 #include "platform.h"
  27 #include "testbed_api_operations.h"
  28
  29
  30 /**
  31  * Opaque handle to an abstract operation to be executed by the testing framework.
  32  */
  33 struct GNUNET_TESTBED_Operation
  34 {
  35   /**
  36    * Function to call when we have the resources to begin the operation.
  37    */
  38   OperationStart start;
  39
  40   /**
  41    * Function to call to clean up after the operation (which may or may
  42    * not have been started yet).
  43    */
  44   OperationRelease release;
  45
  46   /**
  47    * Closure for callbacks.
  48    */
  49   void *cb_cls;
  50
  51   // FIXME!
  52
  53 };
  54
  55
  56 /**
  57  * Queue of operations where we can only support a certain
  58  * number of concurrent operations of a particular type.
  59  */
  60 struct OperationQueue
  61 {
  62
  63   /**
  64    * Maximum number of operationst that can be concurrently
  65    * active in this queue.
  66    */
  67   unsigned int max_active;
  68
  69   // FIXME!
  70
  71 };
  72
  73
  74 /**
  75  * Create an operation queue.
  76  *
  77  * @param max_active maximum number of operations in this
  78  *        queue that can be active in parallel at the same time
  79  * @return handle to the queue
  80  */
  81 struct OperationQueue *
  82 GNUNET_TESTBED_operation_queue_create_ (unsigned int max_active)
  83 {
  84   struct OperationQueue *queue;
  85
  86   queue = GNUNET_malloc (sizeof (struct OperationQueue));
  87   queue->max_active = max_active;
  88   return queue;
  89 }
  90
  91
  92 /**
  93  * Destroy an operation queue.  The queue MUST be empty
  94  * at this time.
  95  *
  96  * @param queue queue to destroy
  97  */
  98 void
  99 GNUNET_TESTBED_operation_queue_destroy_ (struct OperationQueue *queue)
 100 {
 101   GNUNET_break (0);
 102   GNUNET_free (queue);
 103 }
 104
 105
 106 /**
 107  * Add an operation to a queue.  An operation can be in multiple
 108  * queues at once.  Once all queues permit the operation to become
 109  * active, the operation will be activated.  The actual activation
 110  * will occur in a separate task (thus allowing multiple queue
 111  * insertions to be made without having the first one instantly
 112  * trigger the operation if the first queue has sufficient
 113  * resources).
 114  *
 115  * @param queue queue to add the operation to
 116  * @param operation operation to add to the queue
 117  */
 118 void
 119 GNUNET_TESTBED_operation_queue_insert_ (struct OperationQueue *queue,
 120                                         struct GNUNET_TESTBED_Operation *operation)
 121 {
 122   GNUNET_break (0);
 123 }
 124
 125
 126 /**
 127  * Remove an operation from a queue.  This can be because the
 128  * oeration was active and has completed (and the resources have
 129  * been released), or because the operation was cancelled and
 130  * thus scheduling the operation is no longer required.
 131  *
 132  * @param queue queue to add the operation to
 133  * @param operation operation to add to the queue
 134  */
 135 void
 136 GNUNET_TESTBED_operation_queue_remove_ (struct OperationQueue *queue,
 137                                         struct GNUNET_TESTBED_Operation *operation)
 138 {
 139   GNUNET_break (0);
 140 }
 141
 142
 143 /**
 144  * An operation is 'done' (was cancelled or finished); remove
 145  * it from the queues and release associated resources.
 146  *
 147  * @param operation operation that finished
 148  */
 149 static void
 150 operation_release (struct GNUNET_TESTBED_Operation *operation)
 151 {
 152   // call operation->release, remove from queues
 153   GNUNET_break (0);
 154 }
 155
 156
 157 /**
 158  * Cancel a pending operation.  Releases all resources
 159  * of the operation and will ensure that no event
 160  * is generated for the operation.  Does NOT guarantee
 161  * that the operation will be fully undone (or that
 162  * nothing ever happened).
 163  *
 164  * @param operation operation to cancel
 165  */
 166 void
 167 GNUNET_TESTBED_operation_cancel (struct GNUNET_TESTBED_Operation *operation)
 168 {
 169   // test that operation had not yet generated an event
 170   GNUNET_break (0);
 171   operation_release (operation);
 172 }
 173
 174
 175 /**
 176  * Signal that the information from an operation has been fully
 177  * processed.  This function MUST be called for each event
 178  * of type 'operation_finished' to fully remove the operation
 179  * from the operation queue.  After calling this function, the
 180  * 'op_result' becomes invalid (!).
 181  *
 182  * @param operation operation to signal completion for
 183  */
 184 void
 185 GNUNET_TESTBED_operation_done (struct GNUNET_TESTBED_Operation *operation)
 186 {
 187   // test that operation was started and had generated an event
 188   GNUNET_break (0);
 189   operation_release (operation);
 190 }
 191
 192
 193
 194 /* end of testbed_api_operations.c */