X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Ftestbed%2Ftestbed_api_operations.h;h=c44325307e0afbbcea21b3280380eca74c2f3eb7;hb=db9c68c76d7a9eb3f200df9d0fcaf971387cb061;hp=245e9a60e4867dfcca3ed6d272b11e2a2d28a766;hpb=cc7efcc843411a956524a00c91425b9d626b03c3;p=oweals%2Fgnunet.git diff --git a/src/testbed/testbed_api_operations.h b/src/testbed/testbed_api_operations.h index 245e9a60e..c44325307 100644 --- a/src/testbed/testbed_api_operations.h +++ b/src/testbed/testbed_api_operations.h @@ -1,6 +1,6 @@ /* This file is part of GNUnet - (C) 2008--2012 Christian Grothoff (and other contributing authors) + (C) 2008--2013 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 @@ -37,15 +37,36 @@ struct OperationQueue; +/** + * The type of operation queue + */ +enum OperationQueueType +{ + /** + * Operation queue which permits a fixed maximum number of operations to be + * active at any time + */ + OPERATION_QUEUE_TYPE_FIXED, + + /** + * Operation queue which adapts the number of operations to be active based on + * the operation completion times of previously executed operation in it + */ + OPERATION_QUEUE_TYPE_ADAPTIVE +}; + + /** * Create an operation queue. * - * @param max_active maximum number of operations in this - * queue that can be active in parallel at the same time + * @param type the type of 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); +GNUNET_TESTBED_operation_queue_create_ (enum OperationQueueType type, + unsigned int max_active); /** @@ -59,43 +80,81 @@ 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). + * Destroys the operation queue if it is empty. If not empty return GNUNET_NO. + * + * @param queue the queue to destroy if empty + * @return GNUNET_YES if the queue is destroyed. GNUNET_NO if not (because it + * is not empty) + */ +int +GNUNET_TESTBED_operation_queue_destroy_empty_ (struct OperationQueue *queue); + + +/** + * Function to reset the maximum number of operations in the given queue. If + * max_active is lesser than the number of currently active operations, the + * active operations are not stopped immediately. + * + * @param queue the operation queue which has to be modified + * @param max_active the new maximum number of active operations + */ +void +GNUNET_TESTBED_operation_queue_reset_max_active_ (struct OperationQueue *queue, + unsigned int max_active); + + +/** + * Add an operation to a queue. An operation can be in multiple queues at + * once. Once the operation is inserted into all the queues + * GNUNET_TESTBED_operation_begin_wait_() has to be called to actually start + * waiting for the operation to become active. * * @param queue queue to add the operation to - * @param operation operation to add to the queue + * @param op operation to add to the queue + * @param nres the number of units of the resources of queue needed by the + * operation. Should be greater than 0. */ void -GNUNET_TESTBED_operation_queue_insert_ (struct OperationQueue *queue, - struct GNUNET_TESTBED_Operation *operation); +GNUNET_TESTBED_operation_queue_insert2_ (struct OperationQueue *queue, + struct GNUNET_TESTBED_Operation *op, + unsigned int nres); /** - * 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. + * Add an operation to a queue. An operation can be in multiple queues at + * once. Once the operation is inserted into all the queues + * GNUNET_TESTBED_operation_begin_wait_() has to be called to actually start + * waiting for the operation to become active. * * @param queue queue to add the operation to - * @param operation operation to add to the queue + * @param op operation to add to the queue */ void -GNUNET_TESTBED_operation_queue_remove_ (struct OperationQueue *queue, - struct GNUNET_TESTBED_Operation *operation); +GNUNET_TESTBED_operation_queue_insert_ (struct OperationQueue *queue, + struct GNUNET_TESTBED_Operation *op); + +/** + * Marks the given operation as waiting on the queues. 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 op the operation to marks as waiting + */ +void +GNUNET_TESTBED_operation_begin_wait_ (struct GNUNET_TESTBED_Operation *op); /** * Function to call to start an operation once all * queues the operation is part of declare that the * operation can be activated. + * + * @param cls the closure from GNUNET_TESTBED_operation_create_() */ -typedef void (*OperationStart)(void *cls); +typedef void (*OperationStart) (void *cls); /** @@ -107,9 +166,11 @@ typedef void (*OperationStart)(void *cls); * 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. + * associated with the operation. + * + * @param cls the closure from GNUNET_TESTBED_operation_create_() */ -typedef void (*OperationRelease)(void *cls); +typedef void (*OperationRelease) (void *cls); /** @@ -118,24 +179,54 @@ typedef void (*OperationRelease)(void *cls); * @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, - ...); +GNUNET_TESTBED_operation_create_ (void *cls, OperationStart start, + OperationRelease release); /** * An operation is 'done' (was cancelled or finished); remove * it from the queues and release associated resources. * - * @param operation operation that finished + * @param op operation that finished + */ +void +GNUNET_TESTBED_operation_release_ (struct GNUNET_TESTBED_Operation *op); + + +/** + * Marks an active operation as inactive - the operation will be kept in a + * ready-to-be-released state and continues to hold resources until another + * operation contents for them. + * + * @param op the operation to be marked as inactive. The operation start + * callback should have been called before for this operation to mark + * it as inactive. + */ +void +GNUNET_TESTBED_operation_inactivate_ (struct GNUNET_TESTBED_Operation *op); + + +/** + * Marks and inactive operation as active. This fuction should be called to + * ensure that the oprelease callback will not be called until it is either + * marked as inactive or released. + * + * @param op the operation to be marked as active + */ +void +GNUNET_TESTBED_operation_activate_ (struct GNUNET_TESTBED_Operation *op); + + +/** + * Marks an operation as failed + * + * @param op the operation to be marked as failed */ void -GNUNET_TESTBED_operation_release_ (struct GNUNET_TESTBED_Operation *operation); +GNUNET_TESTBED_operation_mark_failed (struct GNUNET_TESTBED_Operation *op); #endif