testbed_api_operations.h File Reference

internal API to access the 'operations' subsystem More...

#include "gnunet_testbed_service.h"
#include "gnunet_helper_lib.h"

Include dependency graph for testbed_api_operations.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef void(*	OperationStart) (void *cls)
	Function to call to start an operation once all queues the operation is part of declare that the operation can be activated. More...
typedef void(*	OperationRelease) (void *cls)
	Function to call to cancel an operation (release all associated resources). More...

Enumerations
enum	OperationQueueType { OPERATION_QUEUE_TYPE_FIXED, OPERATION_QUEUE_TYPE_ADAPTIVE }
	The type of operation queue. More...

Functions
struct OperationQueue *	GNUNET_TESTBED_operation_queue_create_ (enum OperationQueueType type, unsigned int max_active)
	Create an operation queue. More...
void	GNUNET_TESTBED_operation_queue_destroy_ (struct OperationQueue *queue)
	Destroy an operation queue. More...
int	GNUNET_TESTBED_operation_queue_destroy_empty_ (struct OperationQueue *queue)
	Destroys the operation queue if it is empty. More...
void	GNUNET_TESTBED_operation_queue_reset_max_active_ (struct OperationQueue *queue, unsigned int max_active)
	Function to reset the maximum number of operations in the given queue. More...
void	GNUNET_TESTBED_operation_queue_insert2_ (struct OperationQueue *queue, struct GNUNET_TESTBED_Operation *op, unsigned int nres)
	Add an operation to a queue. More...
void	GNUNET_TESTBED_operation_queue_insert_ (struct OperationQueue *queue, struct GNUNET_TESTBED_Operation *op)
	Add an operation to a queue. More...
void	GNUNET_TESTBED_operation_begin_wait_ (struct GNUNET_TESTBED_Operation *op)
	Marks the given operation as waiting on the queues. More...
struct GNUNET_TESTBED_Operation *	GNUNET_TESTBED_operation_create_ (void *cls, OperationStart start, OperationRelease release)
	Create an 'operation' to be performed. More...
void	GNUNET_TESTBED_operation_release_ (struct GNUNET_TESTBED_Operation *op)
	An operation is 'done' (was cancelled or finished); remove it from the queues and release associated resources. More...
void	GNUNET_TESTBED_operation_inactivate_ (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. More...
void	GNUNET_TESTBED_operation_activate_ (struct GNUNET_TESTBED_Operation *op)
	Marks and inactive operation as active. More...
void	GNUNET_TESTBED_operation_mark_failed (struct GNUNET_TESTBED_Operation *op)
	Marks an operation as failed. More...

Detailed Description

internal API to access the 'operations' subsystem

Author

Christian Grothoff

Definition in file testbed_api_operations.h.

Typedef Documentation

OperationStart

typedef void(* OperationStart) (void *cls)

Function to call to start an operation once all queues the operation is part of declare that the operation can be activated.

Parameters

cls	the closure from GNUNET_TESTBED_operation_create_()

Definition at line 157 of file testbed_api_operations.h.

OperationRelease

typedef void(* OperationRelease) (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.

Parameters

cls	the closure from GNUNET_TESTBED_operation_create_()

Definition at line 173 of file testbed_api_operations.h.

Enumeration Type Documentation

OperationQueueType

enum OperationQueueType

The type of operation queue.

Enumerator
OPERATION_QUEUE_TYPE_FIXED	Operation queue which permits a fixed maximum number of operations to be active at any time.
OPERATION_QUEUE_TYPE_ADAPTIVE	Operation queue which adapts the number of operations to be active based on the operation completion times of previously executed operation in it.

Definition at line 43 of file testbed_api_operations.h.

{
  OPERATION_QUEUE_TYPE_FIXED,

  OPERATION_QUEUE_TYPE_ADAPTIVE
};

Function Documentation

GNUNET_TESTBED_operation_queue_create_()

struct OperationQueue* GNUNET_TESTBED_operation_queue_create_	(	enum OperationQueueType	type,
		unsigned int	max_active
	)

Create an operation queue.

Parameters

type	the type of operation queue
max_active	maximum number of operations in this queue that can be active in parallel at the same time.

Returns

handle to the queue

Parameters

type	the type of operation queue
max_active	maximum number of operations in this queue that can be active in parallel at the same time

Returns

handle to the queue

Definition at line 1051 of file testbed_api_operations.c.

References ADAPTIVE_QUEUE_DEFAULT_HISTORY, ADAPTIVE_QUEUE_DEFAULT_MAX_ACTIVE, adaptive_queue_set_max_active(), OperationQueue::fctx, GNUNET_new, GNUNET_TESTBED_SD_init_(), OperationQueue::max_active, FeedbackCtx::max_active_bound, OPERATION_QUEUE_TYPE_FIXED, QueueEntry::queue, FeedbackCtx::sd, type, and OperationQueue::type.

Referenced by GNUNET_TESTBED_controller_connect(), GNUNET_TESTBED_get_statistics(), GNUNET_TESTBED_host_create_with_id(), and testbed_run().

{
  struct OperationQueue *queue;
  struct FeedbackCtx *fctx;

  queue = GNUNET_new (struct OperationQueue);
  queue->type = type;
  if (OPERATION_QUEUE_TYPE_FIXED == type)
  {
    queue->max_active = max_active;
  }
  else
  {
    fctx = GNUNET_new (struct FeedbackCtx);
    fctx->max_active_bound = max_active;
    fctx->sd = GNUNET_TESTBED_SD_init_ (ADAPTIVE_QUEUE_DEFAULT_HISTORY);
    queue->fctx = fctx;
    adaptive_queue_set_max_active (queue, ADAPTIVE_QUEUE_DEFAULT_MAX_ACTIVE);
  }
  return queue;
}

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_TESTBED_operation_queue_destroy_()

void GNUNET_TESTBED_operation_queue_destroy_

(

struct OperationQueue *

queue

)

Destroy an operation queue.

The queue MUST be empty at this time.

Parameters

queue

queue to destroy

Destroy an operation queue.

If the queue is still in use by operations it is marked as expired and its resources are released in the destructor GNUNET_TESTBED_operations_fini().

Parameters

queue

queue to destroy

Definition at line 1104 of file testbed_api_operations.c.

References OperationQueue::expired, GNUNET_array_append, GNUNET_assert, GNUNET_YES, is_queue_empty(), n_expired_opqs, and queue_destroy().

Referenced by GNUNET_TESTBED_controller_disconnect(), GNUNET_TESTBED_host_destroy(), GNUNET_TESTBED_operation_queue_destroy_empty_(), and shutdown_task().

{
  if (GNUNET_YES != is_queue_empty (queue))
  {
    GNUNET_assert (0 == queue->expired);  /* Are you calling twice on same queue? */
    queue->expired = 1;
    GNUNET_array_append (expired_opqs, n_expired_opqs, queue);
    return;
  }
  queue_destroy (queue);
}

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_TESTBED_operation_queue_destroy_empty_()

int GNUNET_TESTBED_operation_queue_destroy_empty_

(

struct OperationQueue *

queue

)

Destroys the operation queue if it is empty.

If not empty return GNUNET_NO.

Parameters

queue

the queue to destroy if empty

Returns

GNUNET_YES if the queue is destroyed. GNUNET_NO if not (because it is not empty)

Definition at line 1125 of file testbed_api_operations.c.

References GNUNET_NO, GNUNET_TESTBED_operation_queue_destroy_(), GNUNET_YES, and is_queue_empty().

Referenced by oprelease_get_stats().

{
  if (GNUNET_NO == is_queue_empty (queue))
    return GNUNET_NO;
  GNUNET_TESTBED_operation_queue_destroy_ (queue);
  return GNUNET_YES;
}

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_TESTBED_operation_queue_reset_max_active_()

void GNUNET_TESTBED_operation_queue_reset_max_active_	(	struct OperationQueue *	queue,
		unsigned int	max_active
	)

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.

Parameters

queue	the operation queue which has to be modified
max_active	the new maximum number of active operations

Definition at line 1166 of file testbed_api_operations.c.

References OperationQueue::active, defer(), OperationQueue::max_active, QueueEntry::op, OperationQueue::overload, recheck_waiting(), and OperationQueue::rq_head.

Referenced by adaptive_queue_set_max_active().

{
  struct QueueEntry *entry;

  queue->max_active = max_active;
  queue->overload = 0;
  while ((queue->active > queue->max_active)
         && (NULL != (entry = queue->rq_head)))
    defer (entry->op);
  recheck_waiting (queue);
}

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_TESTBED_operation_queue_insert2_()

void GNUNET_TESTBED_operation_queue_insert2_	(	struct OperationQueue *	queue,
		struct GNUNET_TESTBED_Operation *	op,
		unsigned int	nres
	)

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.

Parameters

queue	queue to add the operation to
op	operation to add to the queue
nres	the number of units of the resources of queue needed by the operation. Should be greater than 0.

Definition at line 1192 of file testbed_api_operations.c.

References GNUNET_array_append, GNUNET_assert, GNUNET_TESTBED_Operation::nqueues, GNUNET_TESTBED_Operation::nres, and GNUNET_TESTBED_Operation::queues.

Referenced by GNUNET_TESTBED_operation_queue_insert_().

{
  unsigned int qsize;

  GNUNET_assert (0 < nres);
  qsize = op->nqueues;
  GNUNET_array_append (op->queues, op->nqueues, queue);
  GNUNET_array_append (op->nres, qsize, nres);
  GNUNET_assert (qsize == op->nqueues);
}

Here is the caller graph for this function:

GNUNET_TESTBED_operation_queue_insert_()

void GNUNET_TESTBED_operation_queue_insert_	(	struct OperationQueue *	queue,
		struct GNUNET_TESTBED_Operation *	op
	)

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.

Parameters

queue	queue to add the operation to
op	operation to add to the 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. The operation is assumed to take 1 queue resource. Use GNUNET_TESTBED_operation_queue_insert2_() if it requires more than 1

Parameters

queue	queue to add the operation to
op	operation to add to the queue

Definition at line 1218 of file testbed_api_operations.c.

References GNUNET_TESTBED_operation_queue_insert2_().

Referenced by GNUNET_TESTBED_controller_link(), GNUNET_TESTBED_get_slave_config_(), GNUNET_TESTBED_get_statistics(), GNUNET_TESTBED_host_queue_oc_(), GNUNET_TESTBED_overlay_configure_topology_va(), GNUNET_TESTBED_peer_create(), GNUNET_TESTBED_peer_destroy(), GNUNET_TESTBED_peer_get_information(), GNUNET_TESTBED_peer_manage_service(), GNUNET_TESTBED_peer_start(), GNUNET_TESTBED_peer_stop(), GNUNET_TESTBED_peer_update_configuration(), GNUNET_TESTBED_service_connect(), GNUNET_TESTBED_shutdown_peers(), GST_connection_pool_get_handle(), and GST_neighbour_get_connection().

{
  return GNUNET_TESTBED_operation_queue_insert2_ (queue, op, 1);
}

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_TESTBED_operation_begin_wait_()

void GNUNET_TESTBED_operation_begin_wait_

(

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).

Parameters

op	the operation to marks as waiting

Definition at line 1235 of file testbed_api_operations.c.

References change_state(), check_readiness(), GNUNET_assert, OP_STATE_WAITING, and GNUNET_TESTBED_Operation::rq_entry.

Referenced by GNUNET_TESTBED_controller_link(), GNUNET_TESTBED_get_slave_config_(), GNUNET_TESTBED_get_statistics(), GNUNET_TESTBED_overlay_configure_topology_va(), GNUNET_TESTBED_overlay_connect(), GNUNET_TESTBED_peer_create(), GNUNET_TESTBED_peer_destroy(), GNUNET_TESTBED_peer_get_information(), GNUNET_TESTBED_peer_manage_service(), GNUNET_TESTBED_peer_start(), GNUNET_TESTBED_peer_stop(), GNUNET_TESTBED_peer_update_configuration(), GNUNET_TESTBED_service_connect(), GNUNET_TESTBED_shutdown_peers(), GST_connection_pool_get_handle(), and GST_neighbour_get_connection().

{
  GNUNET_assert (NULL == op->rq_entry);
  change_state (op, OP_STATE_WAITING);
  (void) check_readiness (op);
}

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_TESTBED_operation_create_()

struct GNUNET_TESTBED_Operation* GNUNET_TESTBED_operation_create_	(	void *	cls,
		OperationStart	start,
		OperationRelease	release
	)

Create an 'operation' to be performed.

Parameters

cls	closure for the callbacks
start	function to call to start the operation
release	function to call to close down the operation

Returns

handle to the operation

Definition at line 1028 of file testbed_api_operations.c.

References GNUNET_TESTBED_Operation::cb_cls, GNUNET_new, QueueEntry::op, OP_STATE_INIT, GNUNET_TESTBED_Operation::release, start, GNUNET_TESTBED_Operation::start, and GNUNET_TESTBED_Operation::state.

Referenced by GNUNET_TESTBED_controller_link(), GNUNET_TESTBED_get_slave_config_(), GNUNET_TESTBED_get_statistics(), GNUNET_TESTBED_overlay_configure_topology_va(), GNUNET_TESTBED_overlay_connect(), GNUNET_TESTBED_peer_create(), GNUNET_TESTBED_peer_destroy(), GNUNET_TESTBED_peer_get_information(), GNUNET_TESTBED_peer_manage_service(), GNUNET_TESTBED_peer_start(), GNUNET_TESTBED_peer_stop(), GNUNET_TESTBED_peer_update_configuration(), GNUNET_TESTBED_service_connect(), GNUNET_TESTBED_shutdown_peers(), GST_connection_pool_get_handle(), and GST_neighbour_get_connection().

{
  struct GNUNET_TESTBED_Operation *op;

  op = GNUNET_new (struct GNUNET_TESTBED_Operation);
  op->start = start;
  op->state = OP_STATE_INIT;
  op->release = release;
  op->cb_cls = cls;
  return op;
}

Here is the caller graph for this function:

GNUNET_TESTBED_operation_release_()

void GNUNET_TESTBED_operation_release_

(

struct GNUNET_TESTBED_Operation *

op

)

An operation is 'done' (was cancelled or finished); remove it from the queues and release associated resources.

Parameters

op	operation that finished

Definition at line 1296 of file testbed_api_operations.c.

References OperationQueue::active, GNUNET_TESTBED_Operation::cb_cls, GNUNET_assert, GNUNET_free, GNUNET_TESTBED_operation_activate_(), GNUNET_TESTBED_Operation::nqueues, QueueEntry::nres, GNUNET_TESTBED_Operation::nres, OP_STATE_ACTIVE, OP_STATE_INACTIVE, OP_STATE_INIT, OP_STATE_READY, OP_STATE_WAITING, GNUNET_TESTBED_Operation::qentries, GNUNET_TESTBED_Operation::queues, recheck_waiting(), GNUNET_TESTBED_Operation::release, remove_queue_entry(), rq_remove(), GNUNET_TESTBED_Operation::state, and update_tslots().

Referenced by check_readiness(), GNUNET_TESTBED_operation_done(), and GST_neighbour_list_clean().

{
  struct QueueEntry *entry;
  struct OperationQueue *opq;
  unsigned int i;

  if (OP_STATE_INIT == op->state)
  {
    GNUNET_free (op);
    return;
  }
  if (OP_STATE_READY == op->state)
    rq_remove (op);
  if (OP_STATE_INACTIVE == op->state) /* Activate the operation if inactive */
    GNUNET_TESTBED_operation_activate_ (op);
  if (OP_STATE_ACTIVE == op->state)
    update_tslots (op);
  GNUNET_assert (NULL != op->queues);
  GNUNET_assert (NULL != op->qentries);
  for (i = 0; i < op->nqueues; i++)
  {
    entry = op->qentries[i];
    remove_queue_entry (op, i);
    opq = op->queues[i];
    switch (op->state)
    {
    case OP_STATE_INIT:
    case OP_STATE_INACTIVE:
      GNUNET_assert (0);
      break;

    case OP_STATE_WAITING:
      break;

    case OP_STATE_ACTIVE:
    case OP_STATE_READY:
      GNUNET_assert (0 != opq->active);
      GNUNET_assert (opq->active >= entry->nres);
      opq->active -= entry->nres;
      recheck_waiting (opq);
      break;
    }
    GNUNET_free (entry);
  }
  GNUNET_free (op->qentries);
  GNUNET_free (op->queues);
  GNUNET_free (op->nres);
  if (NULL != op->release)
    op->release (op->cb_cls);
  GNUNET_free (op);
}

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_TESTBED_operation_inactivate_()

void GNUNET_TESTBED_operation_inactivate_

(

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.

Parameters

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.

Definition at line 1253 of file testbed_api_operations.c.

References change_state(), GNUNET_assert, GNUNET_free, GNUNET_malloc, GNUNET_memcpy, GNUNET_TESTBED_Operation::nqueues, OP_STATE_ACTIVE, OP_STATE_INACTIVE, GNUNET_TESTBED_Operation::queues, recheck_waiting(), and GNUNET_TESTBED_Operation::state.

Referenced by GST_neighbour_get_connection_cancel(), and GST_neighbour_release_connection().

{
  struct OperationQueue **queues;
  size_t ms;
  unsigned int nqueues;
  unsigned int i;

  GNUNET_assert (OP_STATE_ACTIVE == op->state);
  change_state (op, OP_STATE_INACTIVE);
  nqueues = op->nqueues;
  ms = sizeof(struct OperationQueue *) * nqueues;
  queues = GNUNET_malloc (ms);
  /* Cloning is needed as the operation be released by waiting operations and
     hence its nqueues memory ptr will be freed */
  GNUNET_memcpy (queues, op->queues, ms);
  for (i = 0; i < nqueues; i++)
    recheck_waiting (queues[i]);
  GNUNET_free (queues);
}

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_TESTBED_operation_activate_()

void GNUNET_TESTBED_operation_activate_

(

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.

Parameters

op	the operation to be marked as active

Definition at line 1282 of file testbed_api_operations.c.

References change_state(), GNUNET_assert, OP_STATE_ACTIVE, OP_STATE_INACTIVE, and GNUNET_TESTBED_Operation::state.

Referenced by GNUNET_TESTBED_operation_release_(), and trigger_notifications().

{
  GNUNET_assert (OP_STATE_INACTIVE == op->state);
  change_state (op, OP_STATE_ACTIVE);
}

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_TESTBED_operation_mark_failed()

void GNUNET_TESTBED_operation_mark_failed

(

struct GNUNET_TESTBED_Operation *

op

)

Marks an operation as failed.

Parameters

op	the operation to be marked as failed

Definition at line 1355 of file testbed_api_operations.c.

References GNUNET_TESTBED_Operation::failed, and GNUNET_YES.

Referenced by handle_op_fail_event().

{
  op->failed = GNUNET_YES;
}

Here is the caller graph for this function: