aboutsummaryrefslogtreecommitdiff
path: root/src/testbed/testbed_api.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/testbed/testbed_api.h')
-rw-r--r--src/testbed/testbed_api.h521
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 */
44enum 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 */
111enum 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 */
136struct 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 */
180typedef 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 */
193struct 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 */
277struct 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 */
318void
319GNUNET_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 */
331void
332GNUNET_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 */
343void
344GNUNET_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 */
357size_t
358GNUNET_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 */
372char *
373GNUNET_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 */
391struct GNUNET_TESTBED_HelperInit *
392GNUNET_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 */
412struct OperationContext *
413GNUNET_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 */
426void
427GNUNET_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 */
439struct GNUNET_CONFIGURATION_Handle *
440GNUNET_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 */
450const char *
451GNUNET_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 */
463uint64_t
464GNUNET_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 */
479struct GNUNET_TESTBED_Operation *
480GNUNET_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 */
501struct GNUNET_TESTBED_Barrier *
502GNUNET_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 */
516void
517GNUNET_TESTBED_barrier_remove_ (struct GNUNET_TESTBED_Barrier *barrier);
518
519
520#endif
521/* end of testbed_api.h */