1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
/*
This file is part of GNUnet
(C) 2008--2012 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
by the Free Software Foundation; either version 3, or (at your
option) any later version.
GNUnet is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with GNUnet; see the file COPYING. If not, write to the
Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
*/
/**
* @file testbed/testbed_api_operations.h
* @brief internal API to access the 'operations' subsystem
* @author Christian Grothoff
*/
#ifndef NEW_TESTING_API_OPERATIONS_H
#define NEW_TESTING_API_OPERATIONS_H
#include "gnunet_testbed_service.h"
#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);
/**
* 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 nres the number of units of the resources of queue needed by the
* operation. Should be greater than 0.
*/
void
GNUNET_TESTBED_operation_queue_insert2_ (struct OperationQueue *queue,
struct GNUNET_TESTBED_Operation
*operation, 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.
*
* @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);
/**
* 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 operation the operation to marks as waiting
*/
void
GNUNET_TESTBED_operation_begin_wait_ (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.
*
* @param cls the closure from GNUNET_TESTBED_operation_create_()
*/
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.
*
* @param cls the closure from GNUNET_TESTBED_operation_create_()
*/
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
* @return handle to the operation
*/
struct GNUNET_TESTBED_Operation *
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
*/
void
GNUNET_TESTBED_operation_release_ (struct GNUNET_TESTBED_Operation *operation);
#endif
/* end of testbed_api_operations.h */
|
