diff options
Diffstat (limited to 'src/testbed/testbed_api.h')
-rw-r--r-- | src/testbed/testbed_api.h | 521 |
1 files changed, 0 insertions, 521 deletions
diff --git a/src/testbed/testbed_api.h b/src/testbed/testbed_api.h deleted file mode 100644 index d4ef832ad..000000000 --- a/src/testbed/testbed_api.h +++ /dev/null | |||
@@ -1,521 +0,0 @@ | |||
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.h | ||
23 | * @brief Interface for functions internally exported from testbed_api.c | ||
24 | * @author Sree Harsha Totakura | ||
25 | */ | ||
26 | |||
27 | #ifndef TESTBED_API_H | ||
28 | #define TESTBED_API_H | ||
29 | |||
30 | #include "gnunet_util_lib.h" | ||
31 | #include "gnunet_testbed_service.h" | ||
32 | #include "testbed.h" | ||
33 | #include "testbed_helper.h" | ||
34 | |||
35 | /** | ||
36 | * Testbed Helper binary name | ||
37 | */ | ||
38 | #define HELPER_TESTBED_BINARY "gnunet-helper-testbed" | ||
39 | |||
40 | |||
41 | /** | ||
42 | * Enumeration of operations | ||
43 | */ | ||
44 | enum OperationType | ||
45 | { | ||
46 | /** | ||
47 | * Peer create operation | ||
48 | */ | ||
49 | OP_PEER_CREATE, | ||
50 | |||
51 | /** | ||
52 | * Peer start operation | ||
53 | */ | ||
54 | OP_PEER_START, | ||
55 | |||
56 | /** | ||
57 | * Peer stop operation | ||
58 | */ | ||
59 | OP_PEER_STOP, | ||
60 | |||
61 | /** | ||
62 | * Peer destroy operation | ||
63 | */ | ||
64 | OP_PEER_DESTROY, | ||
65 | |||
66 | /** | ||
67 | * Get peer information operation | ||
68 | */ | ||
69 | OP_PEER_INFO, | ||
70 | |||
71 | /** | ||
72 | * Reconfigure a peer | ||
73 | */ | ||
74 | OP_PEER_RECONFIGURE, | ||
75 | |||
76 | /** | ||
77 | * Overlay connection operation | ||
78 | */ | ||
79 | OP_OVERLAY_CONNECT, | ||
80 | |||
81 | /** | ||
82 | * Forwarded operation | ||
83 | */ | ||
84 | OP_FORWARDED, | ||
85 | |||
86 | /** | ||
87 | * Link controllers operation | ||
88 | */ | ||
89 | OP_LINK_CONTROLLERS, | ||
90 | |||
91 | /** | ||
92 | * Get slave config operation | ||
93 | */ | ||
94 | OP_GET_SLAVE_CONFIG, | ||
95 | |||
96 | /** | ||
97 | * Stop and destroy all peers | ||
98 | */ | ||
99 | OP_SHUTDOWN_PEERS, | ||
100 | |||
101 | /** | ||
102 | * Start/stop service at a peer | ||
103 | */ | ||
104 | OP_MANAGE_SERVICE | ||
105 | }; | ||
106 | |||
107 | |||
108 | /** | ||
109 | * Enumeration of states of OperationContext | ||
110 | */ | ||
111 | enum OperationContextState | ||
112 | { | ||
113 | /** | ||
114 | * The initial state where the associated operation has just been created | ||
115 | * and is waiting in the operation queues to be started | ||
116 | */ | ||
117 | OPC_STATE_INIT = 0, | ||
118 | |||
119 | /** | ||
120 | * The operation has been started. It may occupy some resources which are to | ||
121 | * be freed if cancelled. | ||
122 | */ | ||
123 | OPC_STATE_STARTED, | ||
124 | |||
125 | /** | ||
126 | * The operation has finished. The end results of this operation may occupy | ||
127 | * some resources which are to be freed by operation_done | ||
128 | */ | ||
129 | OPC_STATE_FINISHED | ||
130 | }; | ||
131 | |||
132 | |||
133 | /** | ||
134 | * Context information for GNUNET_TESTBED_Operation | ||
135 | */ | ||
136 | struct OperationContext | ||
137 | { | ||
138 | /** | ||
139 | * The controller to which this operation context belongs to | ||
140 | */ | ||
141 | struct GNUNET_TESTBED_Controller *c; | ||
142 | |||
143 | /** | ||
144 | * The operation | ||
145 | */ | ||
146 | struct GNUNET_TESTBED_Operation *op; | ||
147 | |||
148 | /** | ||
149 | * The operation closure | ||
150 | */ | ||
151 | void *op_cls; | ||
152 | |||
153 | /** | ||
154 | * Data relevant to the operation | ||
155 | */ | ||
156 | void *data; | ||
157 | |||
158 | /** | ||
159 | * The id of the operation | ||
160 | */ | ||
161 | uint64_t id; | ||
162 | |||
163 | /** | ||
164 | * The type of operation | ||
165 | */ | ||
166 | enum OperationType type; | ||
167 | |||
168 | /** | ||
169 | * The state of the operation | ||
170 | */ | ||
171 | enum OperationContextState state; | ||
172 | }; | ||
173 | |||
174 | |||
175 | /** | ||
176 | * Operation empty callback | ||
177 | * | ||
178 | * @param cls closure | ||
179 | */ | ||
180 | typedef void | ||
181 | (*TESTBED_opcq_empty_cb) (void *cls); | ||
182 | |||
183 | |||
184 | /** | ||
185 | * Handle to interact with a GNUnet testbed controller. Each | ||
186 | * controller has at least one master handle which is created when the | ||
187 | * controller is created; this master handle interacts with the | ||
188 | * controller process, destroying it destroys the controller (by | ||
189 | * closing stdin of the controller process). Additionally, | ||
190 | * controllers can interact with each other (in a P2P fashion); those | ||
191 | * links are established via TCP/IP on the controller's service port. | ||
192 | */ | ||
193 | struct GNUNET_TESTBED_Controller | ||
194 | { | ||
195 | /** | ||
196 | * The host where the controller is running | ||
197 | */ | ||
198 | struct GNUNET_TESTBED_Host *host; | ||
199 | |||
200 | /** | ||
201 | * The controller callback | ||
202 | */ | ||
203 | GNUNET_TESTBED_ControllerCallback cc; | ||
204 | |||
205 | /** | ||
206 | * The closure for controller callback | ||
207 | */ | ||
208 | void *cc_cls; | ||
209 | |||
210 | /** | ||
211 | * The configuration to use while connecting to controller | ||
212 | */ | ||
213 | struct GNUNET_CONFIGURATION_Handle *cfg; | ||
214 | |||
215 | /** | ||
216 | * The message queue to the controller service | ||
217 | */ | ||
218 | struct GNUNET_MQ_Handle *mq; | ||
219 | |||
220 | /** | ||
221 | * The host registration handle; NULL if no current registration requests are | ||
222 | * present | ||
223 | */ | ||
224 | struct GNUNET_TESTBED_HostRegistrationHandle *rh; | ||
225 | |||
226 | /** | ||
227 | * The map of active operation contexts | ||
228 | */ | ||
229 | struct GNUNET_CONTAINER_MultiHashMap32 *opc_map; | ||
230 | |||
231 | /** | ||
232 | * If this callback is not NULL, schedule it as a task when opc_map gets empty | ||
233 | */ | ||
234 | TESTBED_opcq_empty_cb opcq_empty_cb; | ||
235 | |||
236 | /** | ||
237 | * Closure for the above task | ||
238 | */ | ||
239 | void *opcq_empty_cls; | ||
240 | |||
241 | /** | ||
242 | * Operation queue for simultaneous operations | ||
243 | */ | ||
244 | struct OperationQueue *opq_parallel_operations; | ||
245 | |||
246 | /** | ||
247 | * Operation queue for simultaneous service connections | ||
248 | */ | ||
249 | struct OperationQueue *opq_parallel_service_connections; | ||
250 | |||
251 | /** | ||
252 | * Operation queue for simultaneous topology configuration operations | ||
253 | */ | ||
254 | struct OperationQueue *opq_parallel_topology_config_operations; | ||
255 | |||
256 | /** | ||
257 | * handle for hashtable of barrier handles, values are | ||
258 | * of type `struct GNUNET_TESTBED_Barrier`. | ||
259 | */ | ||
260 | struct GNUNET_CONTAINER_MultiHashMap *barrier_map; | ||
261 | |||
262 | /** | ||
263 | * The controller event mask | ||
264 | */ | ||
265 | uint64_t event_mask; | ||
266 | |||
267 | /** | ||
268 | * The operation id counter. use current value and increment | ||
269 | */ | ||
270 | uint32_t operation_counter; | ||
271 | }; | ||
272 | |||
273 | |||
274 | /** | ||
275 | * Handle for barrier | ||
276 | */ | ||
277 | struct GNUNET_TESTBED_Barrier | ||
278 | { | ||
279 | /** | ||
280 | * hashcode identifying this barrier in the hashmap | ||
281 | */ | ||
282 | struct GNUNET_HashCode key; | ||
283 | |||
284 | /** | ||
285 | * The controller handle given while initialising this barrier | ||
286 | */ | ||
287 | struct GNUNET_TESTBED_Controller *c; | ||
288 | |||
289 | /** | ||
290 | * The name of the barrier | ||
291 | */ | ||
292 | char *name; | ||
293 | |||
294 | /** | ||
295 | * The continuation callback to call when we have a status update on this | ||
296 | */ | ||
297 | GNUNET_TESTBED_barrier_status_cb cb; | ||
298 | |||
299 | /** | ||
300 | * the closure for the above callback | ||
301 | */ | ||
302 | void *cls; | ||
303 | |||
304 | /** | ||
305 | * Should the barrier crossed status message be echoed back to the controller? | ||
306 | */ | ||
307 | int echo; | ||
308 | }; | ||
309 | |||
310 | |||
311 | /** | ||
312 | * Queues a message in send queue for sending to the service | ||
313 | * | ||
314 | * @param controller the handle to the controller | ||
315 | * @param msg the message to queue | ||
316 | * @deprecated | ||
317 | */ | ||
318 | void | ||
319 | GNUNET_TESTBED_queue_message_ (struct GNUNET_TESTBED_Controller *controller, | ||
320 | struct GNUNET_MessageHeader *msg); | ||
321 | |||
322 | |||
323 | /** | ||
324 | * Inserts the given operation context into the operation context map of the | ||
325 | * given controller. Creates the operation context map if one does not exist | ||
326 | * for the controller | ||
327 | * | ||
328 | * @param c the controller | ||
329 | * @param opc the operation context to be inserted | ||
330 | */ | ||
331 | void | ||
332 | GNUNET_TESTBED_insert_opc_ (struct GNUNET_TESTBED_Controller *c, | ||
333 | struct OperationContext *opc); | ||
334 | |||
335 | |||
336 | /** | ||
337 | * Removes the given operation context from the operation context map of the | ||
338 | * given controller | ||
339 | * | ||
340 | * @param c the controller | ||
341 | * @param opc the operation context to remove | ||
342 | */ | ||
343 | void | ||
344 | GNUNET_TESTBED_remove_opc_ (const struct GNUNET_TESTBED_Controller *c, | ||
345 | struct OperationContext *opc); | ||
346 | |||
347 | |||
348 | /** | ||
349 | * Compresses given configuration using zlib compress | ||
350 | * | ||
351 | * @param config the serialized configuration | ||
352 | * @param size the size of config | ||
353 | * @param xconfig will be set to the compressed configuration (memory is fresly | ||
354 | * allocated) | ||
355 | * @return the size of the xconfig | ||
356 | */ | ||
357 | size_t | ||
358 | GNUNET_TESTBED_compress_config_ (const char *config, | ||
359 | size_t size, | ||
360 | char **xconfig); | ||
361 | |||
362 | |||
363 | /** | ||
364 | * Function to serialize and compress using zlib a configuration through a | ||
365 | * configuration handle | ||
366 | * | ||
367 | * @param cfg the configuration | ||
368 | * @param size the size of configuration when serialize. Will be set on success. | ||
369 | * @param xsize the sizeo of the compressed configuration. Will be set on success. | ||
370 | * @return the serialized and compressed configuration | ||
371 | */ | ||
372 | char * | ||
373 | GNUNET_TESTBED_compress_cfg_ (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
374 | size_t *size, | ||
375 | size_t *xsize); | ||
376 | |||
377 | |||
378 | /** | ||
379 | * Creates a helper initialization message. This function is here because we | ||
380 | * want to use this in testing | ||
381 | * | ||
382 | * @param trusted_ip the ip address of the controller which will be set as TRUSTED | ||
383 | * HOST(all connections form this ip are permitted by the testbed) when | ||
384 | * starting testbed controller at host. This can either be a single ip | ||
385 | * address or a network address in CIDR notation. | ||
386 | * @param hostname the hostname of the destination this message is intended for | ||
387 | * @param cfg the configuration that has to used to start the testbed service | ||
388 | * thru helper | ||
389 | * @return the initialization message | ||
390 | */ | ||
391 | struct GNUNET_TESTBED_HelperInit * | ||
392 | GNUNET_TESTBED_create_helper_init_msg_ (const char *cname, | ||
393 | const char *hostname, | ||
394 | const struct | ||
395 | GNUNET_CONFIGURATION_Handle *cfg); | ||
396 | |||
397 | |||
398 | /** | ||
399 | * Sends the given message as an operation. The given callback is called when a | ||
400 | * reply for the operation is available. Call | ||
401 | * GNUNET_TESTBED_forward_operation_msg_cancel_() to cleanup the returned | ||
402 | * operation context if the cc hasn't been called | ||
403 | * | ||
404 | * @param controller the controller to which the message has to be sent | ||
405 | * @param operation_id the operation id of the message | ||
406 | * @param msg the message to send | ||
407 | * @param cc the callback to call when reply is available | ||
408 | * @param cc_cls the closure for the above callback | ||
409 | * @return the operation context which can be used to cancel the forwarded | ||
410 | * operation | ||
411 | */ | ||
412 | struct OperationContext * | ||
413 | GNUNET_TESTBED_forward_operation_msg_ (struct | ||
414 | GNUNET_TESTBED_Controller *controller, | ||
415 | uint64_t operation_id, | ||
416 | const struct GNUNET_MessageHeader *msg, | ||
417 | GNUNET_MQ_MessageCallback cc, | ||
418 | void *cc_cls); | ||
419 | |||
420 | /** | ||
421 | * Function to cancel an operation created by simply forwarding an operation | ||
422 | * message. | ||
423 | * | ||
424 | * @param opc the operation context from GNUNET_TESTBED_forward_operation_msg_() | ||
425 | */ | ||
426 | void | ||
427 | GNUNET_TESTBED_forward_operation_msg_cancel_ (struct OperationContext *opc); | ||
428 | |||
429 | |||
430 | /** | ||
431 | * Generates configuration by uncompressing configuration in given message. The | ||
432 | * given message should be of the following types: | ||
433 | * #GNUNET_MESSAGE_TYPE_TESTBED_PEERCONFIG, | ||
434 | * #GNUNET_MESSAGE_TYPE_TESTBED_SLAVECONFIG | ||
435 | * | ||
436 | * @param msg the message containing compressed configuration | ||
437 | * @return handle to the parsed configuration | ||
438 | */ | ||
439 | struct GNUNET_CONFIGURATION_Handle * | ||
440 | GNUNET_TESTBED_extract_config_ (const struct GNUNET_MessageHeader *msg); | ||
441 | |||
442 | |||
443 | /** | ||
444 | * Checks the integrity of the OpeationFailureEventMessage and if good returns | ||
445 | * the error message it contains. | ||
446 | * | ||
447 | * @param msg the OperationFailureEventMessage | ||
448 | * @return the error message | ||
449 | */ | ||
450 | const char * | ||
451 | GNUNET_TESTBED_parse_error_string_ (const struct | ||
452 | GNUNET_TESTBED_OperationFailureEventMessage | ||
453 | *msg); | ||
454 | |||
455 | |||
456 | /** | ||
457 | * Function to return the operation id for a controller. The operation id is | ||
458 | * created from the controllers host id and its internal operation counter. | ||
459 | * | ||
460 | * @param controller the handle to the controller whose operation id has to be incremented | ||
461 | * @return the incremented operation id. | ||
462 | */ | ||
463 | uint64_t | ||
464 | GNUNET_TESTBED_get_next_op_id (struct GNUNET_TESTBED_Controller *controller); | ||
465 | |||
466 | |||
467 | /** | ||
468 | * Like GNUNET_TESTBED_get_slave_config(), however without the host registration | ||
469 | * check. Another difference is that this function takes the id of the slave | ||
470 | * host. | ||
471 | * | ||
472 | * @param op_cls the closure for the operation | ||
473 | * @param master the handle to master controller | ||
474 | * @param slave_host_id id of the host where the slave controller is running to | ||
475 | * the slave_host should remain valid until this operation is cancelled | ||
476 | * or marked as finished | ||
477 | * @return the operation handle; | ||
478 | */ | ||
479 | struct GNUNET_TESTBED_Operation * | ||
480 | GNUNET_TESTBED_get_slave_config_ (void *op_cls, | ||
481 | struct GNUNET_TESTBED_Controller *master, | ||
482 | uint32_t slave_host_id); | ||
483 | |||
484 | |||
485 | /** | ||
486 | * Initialise a barrier and call the given callback when the required percentage | ||
487 | * of peers (quorum) reach the barrier OR upon error. | ||
488 | * | ||
489 | * @param controller the handle to the controller | ||
490 | * @param name identification name of the barrier | ||
491 | * @param quorum the percentage of peers that is required to reach the barrier. | ||
492 | * Peers signal reaching a barrier by calling | ||
493 | * GNUNET_TESTBED_barrier_reached(). | ||
494 | * @param cb the callback to call when the barrier is reached or upon error. | ||
495 | * Cannot be NULL. | ||
496 | * @param cls closure for the above callback | ||
497 | * @param echo #GNUNET_YES to echo the barrier crossed status message back to the | ||
498 | * controller | ||
499 | * @return barrier handle; NULL upon error | ||
500 | */ | ||
501 | struct GNUNET_TESTBED_Barrier * | ||
502 | GNUNET_TESTBED_barrier_init_ (struct GNUNET_TESTBED_Controller *controller, | ||
503 | const char *name, | ||
504 | unsigned int quorum, | ||
505 | GNUNET_TESTBED_barrier_status_cb cb, | ||
506 | void *cls, | ||
507 | int echo); | ||
508 | |||
509 | |||
510 | /** | ||
511 | * Remove a barrier and it was the last one in the barrier hash map, destroy the | ||
512 | * hash map | ||
513 | * | ||
514 | * @param barrier the barrier to remove | ||
515 | */ | ||
516 | void | ||
517 | GNUNET_TESTBED_barrier_remove_ (struct GNUNET_TESTBED_Barrier *barrier); | ||
518 | |||
519 | |||
520 | #endif | ||
521 | /* end of testbed_api.h */ | ||