src/testbed/testbed_api_operations.h

   1 /*
   2       This file is part of GNUnet
   3       Copyright (C) 2008--2013 GNUnet e.V.
   4
   5       GNUnet is free software: you can redistribute it and/or modify it
   6       under the terms of the GNU Affero General Public License as published
   7       by the Free Software Foundation, either version 3 of the License,
   8       or (at your 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       Affero General Public License for more details.
  14
  15       You should have received a copy of the GNU Affero General Public License
  16       along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18      SPDX-License-Identifier: AGPL3.0-or-later
  19  */
  20
  21 /**
  22  * @file testbed/testbed_api_operations.h
  23  * @brief internal API to access the 'operations' subsystem
  24  * @author Christian Grothoff
  25  */
  26 #ifndef NEW_TESTING_API_OPERATIONS_H
  27 #define NEW_TESTING_API_OPERATIONS_H
  28
  29 #include "gnunet_testbed_service.h"
  30 #include "gnunet_helper_lib.h"
  31
  32
  33 /**
  34  * Queue of operations where we can only support a certain
  35  * number of concurrent operations of a particular type.
  36  */
  37 struct OperationQueue;
  38
  39
  40 /**
  41  * The type of operation queue
  42  */
  43 enum OperationQueueType {
  44   /**
  45    * Operation queue which permits a fixed maximum number of operations to be
  46    * active at any time
  47    */
  48   OPERATION_QUEUE_TYPE_FIXED,
  49
  50   /**
  51    * Operation queue which adapts the number of operations to be active based on
  52    * the operation completion times of previously executed operation in it
  53    */
  54   OPERATION_QUEUE_TYPE_ADAPTIVE
  55 };
  56
  57
  58 /**
  59  * Create an operation queue.
  60  *
  61  * @param type the type of operation queue
  62  * @param max_active maximum number of operations in this queue that can be
  63  *   active in parallel at the same time.
  64  * @return handle to the queue
  65  */
  66 struct OperationQueue *
  67 GNUNET_TESTBED_operation_queue_create_(enum OperationQueueType type,
  68                                        unsigned int max_active);
  69
  70
  71 /**
  72  * Destroy an operation queue.  The queue MUST be empty
  73  * at this time.
  74  *
  75  * @param queue queue to destroy
  76  */
  77 void
  78 GNUNET_TESTBED_operation_queue_destroy_(struct OperationQueue *queue);
  79
  80
  81 /**
  82  * Destroys the operation queue if it is empty.  If not empty return GNUNET_NO.
  83  *
  84  * @param queue the queue to destroy if empty
  85  * @return GNUNET_YES if the queue is destroyed.  GNUNET_NO if not (because it
  86  *           is not empty)
  87  */
  88 int
  89 GNUNET_TESTBED_operation_queue_destroy_empty_(struct OperationQueue *queue);
  90
  91
  92 /**
  93  * Function to reset the maximum number of operations in the given queue. If
  94  * max_active is lesser than the number of currently active operations, the
  95  * active operations are not stopped immediately.
  96  *
  97  * @param queue the operation queue which has to be modified
  98  * @param max_active the new maximum number of active operations
  99  */
 100 void
 101 GNUNET_TESTBED_operation_queue_reset_max_active_(struct OperationQueue *queue,
 102                                                  unsigned int max_active);
 103
 104
 105 /**
 106  * Add an operation to a queue.  An operation can be in multiple queues at
 107  * once. Once the operation is inserted into all the queues
 108  * GNUNET_TESTBED_operation_begin_wait_() has to be called to actually start
 109  * waiting for the operation to become active.
 110  *
 111  * @param queue queue to add the operation to
 112  * @param op operation to add to the queue
 113  * @param nres the number of units of the resources of queue needed by the
 114  *          operation. Should be greater than 0.
 115  */
 116 void
 117 GNUNET_TESTBED_operation_queue_insert2_(struct OperationQueue *queue,
 118                                         struct GNUNET_TESTBED_Operation *op,
 119                                         unsigned int nres);
 120
 121
 122 /**
 123  * Add an operation to a queue.  An operation can be in multiple queues at
 124  * once. Once the operation is inserted into all the queues
 125  * GNUNET_TESTBED_operation_begin_wait_() has to be called to actually start
 126  * waiting for the operation to become active.
 127  *
 128  * @param queue queue to add the operation to
 129  * @param op operation to add to the queue
 130  */
 131 void
 132 GNUNET_TESTBED_operation_queue_insert_(struct OperationQueue *queue,
 133                                        struct GNUNET_TESTBED_Operation *op);
 134
 135
 136 /**
 137  * Marks the given operation as waiting on the queues.  Once all queues permit
 138  * the operation to become active, the operation will be activated.  The actual
 139  * activation will occur in a separate task (thus allowing multiple queue
 140  * insertions to be made without having the first one instantly trigger the
 141  * operation if the first queue has sufficient resources).
 142  *
 143  * @param op the operation to marks as waiting
 144  */
 145 void
 146 GNUNET_TESTBED_operation_begin_wait_(struct GNUNET_TESTBED_Operation *op);
 147
 148
 149 /**
 150  * Function to call to start an operation once all
 151  * queues the operation is part of declare that the
 152  * operation can be activated.
 153  *
 154  * @param cls the closure from GNUNET_TESTBED_operation_create_()
 155  */
 156 typedef void (*OperationStart) (void *cls);
 157
 158
 159 /**
 160  * Function to call to cancel an operation (release all associated
 161  * resources).  This can be because of a call to
 162  * "GNUNET_TESTBED_operation_cancel" (before the operation generated
 163  * an event) or AFTER the operation generated an event due to a call
 164  * to "GNUNET_TESTBED_operation_done".  Thus it is not guaranteed that
 165  * a callback to the 'OperationStart' preceeds the call to
 166  * 'OperationRelease'.  Implementations of this function are expected
 167  * to clean up whatever state is in 'cls' and release all resources
 168  * associated with the operation.
 169  *
 170  * @param cls the closure from GNUNET_TESTBED_operation_create_()
 171  */
 172 typedef void (*OperationRelease) (void *cls);
 173
 174
 175 /**
 176  * Create an 'operation' to be performed.
 177  *
 178  * @param cls closure for the callbacks
 179  * @param start function to call to start the operation
 180  * @param release function to call to close down the operation
 181  * @return handle to the operation
 182  */
 183 struct GNUNET_TESTBED_Operation *
 184 GNUNET_TESTBED_operation_create_(void *cls, OperationStart start,
 185                                  OperationRelease release);
 186
 187
 188 /**
 189  * An operation is 'done' (was cancelled or finished); remove
 190  * it from the queues and release associated resources.
 191  *
 192  * @param op operation that finished
 193  */
 194 void
 195 GNUNET_TESTBED_operation_release_(struct GNUNET_TESTBED_Operation *op);
 196
 197
 198 /**
 199  * Marks an active operation as inactive - the operation will be kept in a
 200  * ready-to-be-released state and continues to hold resources until another
 201  * operation contents for them.
 202  *
 203  * @param op the operation to be marked as inactive.  The operation start
 204  *          callback should have been called before for this operation to mark
 205  *          it as inactive.
 206  */
 207 void
 208 GNUNET_TESTBED_operation_inactivate_(struct GNUNET_TESTBED_Operation *op);
 209
 210
 211 /**
 212  * Marks and inactive operation as active.  This fuction should be called to
 213  * ensure that the oprelease callback will not be called until it is either
 214  * marked as inactive or released.
 215  *
 216  * @param op the operation to be marked as active
 217  */
 218 void
 219 GNUNET_TESTBED_operation_activate_(struct GNUNET_TESTBED_Operation *op);
 220
 221
 222 /**
 223  * Marks an operation as failed
 224  *
 225  * @param op the operation to be marked as failed
 226  */
 227 void
 228 GNUNET_TESTBED_operation_mark_failed(struct GNUNET_TESTBED_Operation *op);
 229
 230
 231 #endif
 232 /* end of testbed_api_operations.h */