diff options
author | Christian Grothoff <christian@grothoff.org> | 2012-05-05 15:49:25 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2012-05-05 15:49:25 +0000 |
commit | b042203d5a4f8729bbde84447841e8531010d1aa (patch) | |
tree | fb8cf28f5db734c2ae2a8d9580c9d4f83cdd5050 /src/include/gnunet_testbed_service.h | |
parent | 16f0681acc44d732c1827492fc2b0331cdaea009 (diff) | |
download | gnunet-b042203d5a4f8729bbde84447841e8531010d1aa.tar.gz gnunet-b042203d5a4f8729bbde84447841e8531010d1aa.zip |
-renaming new testing code to testbed
Diffstat (limited to 'src/include/gnunet_testbed_service.h')
-rw-r--r-- | src/include/gnunet_testbed_service.h | 1029 |
1 files changed, 1029 insertions, 0 deletions
diff --git a/src/include/gnunet_testbed_service.h b/src/include/gnunet_testbed_service.h new file mode 100644 index 000000000..a13c2bb10 --- /dev/null +++ b/src/include/gnunet_testbed_service.h | |||
@@ -0,0 +1,1029 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet | ||
3 | (C) 2008, 2009, 2012 Christian Grothoff (and other contributing authors) | ||
4 | |||
5 | GNUnet is free software; you can redistribute it and/or modify | ||
6 | it under the terms of the GNU General Public License as published | ||
7 | by the Free Software Foundation; either version 3, or (at your | ||
8 | 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 | General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU General Public License | ||
16 | along with GNUnet; see the file COPYING. If not, write to the | ||
17 | Free Software Foundation, Inc., 59 Temple Place - Suite 330, | ||
18 | Boston, MA 02111-1307, USA. | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @file include/gnunet_testbed_service.h | ||
23 | * @brief API for writing tests and creating large-scale | ||
24 | * emulation testbeds for GNUnet. | ||
25 | * @author Christian Grothoff | ||
26 | */ | ||
27 | |||
28 | #ifndef GNUNET_TESTBED_SERVICE_H | ||
29 | #define GNUNET_TESTBED_SERVICE_H | ||
30 | |||
31 | #include "gnunet_util_lib.h" | ||
32 | |||
33 | #ifdef __cplusplus | ||
34 | extern "C" | ||
35 | { | ||
36 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
37 | } | ||
38 | #endif | ||
39 | #endif | ||
40 | |||
41 | |||
42 | /** | ||
43 | * Opaque handle to a host running experiments managed by the testbed framework. | ||
44 | * The master process must be able to SSH to this host without password (via | ||
45 | * ssh-agent). | ||
46 | */ | ||
47 | struct GNUNET_TESTBED_Host; | ||
48 | |||
49 | /** | ||
50 | * Opaque handle to a peer controlled by the testbed framework. A peer runs | ||
51 | * at a particular host. | ||
52 | */ | ||
53 | struct GNUNET_TESTBED_Peer; | ||
54 | |||
55 | /** | ||
56 | * Opaque handle to an abstract operation to be executed by the testbed framework. | ||
57 | */ | ||
58 | struct GNUNET_TESTBED_Operation; | ||
59 | |||
60 | /** | ||
61 | * Handle to interact with a GNUnet testbed controller. Each controller has at | ||
62 | * least one master handle which is created when the controller is created; this | ||
63 | * master handle interacts with the controller via stdin/stdout of the controller | ||
64 | * process. Additionally, controllers can interact with each other (in a P2P | ||
65 | * fashion); those links are established via TCP/IP on the controller's service | ||
66 | * port. | ||
67 | */ | ||
68 | struct GNUNET_TESTBED_Controller; | ||
69 | |||
70 | /** | ||
71 | * Handle to a large-scale testbed that is managed at a high level. | ||
72 | */ | ||
73 | struct GNUNET_TESTBED_Testbed; | ||
74 | |||
75 | |||
76 | /** | ||
77 | * Create a host to run peers and controllers on. | ||
78 | * | ||
79 | * @param hostname name of the host, use "NULL" for localhost | ||
80 | * @param username username to use for the login; may be NULL | ||
81 | * @param port port number to use for ssh; use 0 to let ssh decide | ||
82 | * @return handle to the host, NULL on error | ||
83 | */ | ||
84 | struct GNUNET_TESTBED_Host * | ||
85 | GNUNET_TESTBED_host_create (const char *hostname, | ||
86 | const char *username, | ||
87 | uint16_t port); | ||
88 | |||
89 | |||
90 | /** | ||
91 | * Load a set of hosts from a configuration file. | ||
92 | * | ||
93 | * @param filename file with the host specification | ||
94 | * @param hosts set to the hosts found in the file | ||
95 | * @return number of hosts returned in 'hosts', 0 on error | ||
96 | */ | ||
97 | unsigned int | ||
98 | GNUNET_TESTBED_hosts_load_from_file (const char *filename, | ||
99 | struct GNUNET_TESTBED_Host **hosts); | ||
100 | |||
101 | |||
102 | /** | ||
103 | * Destroy a host handle. Must only be called once everything | ||
104 | * running on that host has been stopped. | ||
105 | * | ||
106 | * @param host handle to destroy | ||
107 | */ | ||
108 | void | ||
109 | GNUNET_TESTBED_host_destroy (struct GNUNET_TESTBED_Host *host); | ||
110 | |||
111 | |||
112 | /** | ||
113 | * Enumeration with (at most 64) possible event types that | ||
114 | * can be monitored using the testbed framework. | ||
115 | */ | ||
116 | enum GNUNET_TESTBED_EventType | ||
117 | { | ||
118 | /** | ||
119 | * A peer has been started. | ||
120 | */ | ||
121 | GNUNET_TESTBED_ET_PEER_START = 0, | ||
122 | |||
123 | /** | ||
124 | * A peer has been stopped. | ||
125 | */ | ||
126 | GNUNET_TESTBED_ET_PEER_STOP = 1, | ||
127 | |||
128 | /** | ||
129 | * A connection between two peers was established. | ||
130 | */ | ||
131 | GNUNET_TESTBED_ET_CONNECT = 2, | ||
132 | |||
133 | /** | ||
134 | * A connection between two peers was torn down. | ||
135 | */ | ||
136 | GNUNET_TESTBED_ET_DISCONNECT = 3, | ||
137 | |||
138 | /** | ||
139 | * A requested testbed operation has been completed. | ||
140 | */ | ||
141 | GNUNET_TESTBED_ET_OPERATION_FINISHED = 4, | ||
142 | |||
143 | /** | ||
144 | * The 'GNUNET_TESTBED_run' operation has been completed | ||
145 | */ | ||
146 | GNUNET_TESTBED_ET_TESTBED_ONLINE = 5 | ||
147 | |||
148 | }; | ||
149 | |||
150 | |||
151 | /** | ||
152 | * Types of information that can be requested about a peer. | ||
153 | */ | ||
154 | enum GNUNET_TESTBED_PeerInformationType | ||
155 | { | ||
156 | |||
157 | /** | ||
158 | * Special value (not valid for requesting information) | ||
159 | * that is used in the event struct if a 'generic' pointer | ||
160 | * is returned (for other operations not related to this | ||
161 | * enumeration). | ||
162 | */ | ||
163 | GNUNET_TESTBED_PIT_GENERIC = 0, | ||
164 | |||
165 | /** | ||
166 | * What host is the peer running on? Returns a 'const struct | ||
167 | * GNUNET_TESTBED_Host *'. Valid until | ||
168 | * 'GNUNET_TESTBED_operation_done' is called. | ||
169 | */ | ||
170 | GNUNET_TESTBED_PIT_HOST, | ||
171 | |||
172 | /** | ||
173 | * What configuration is the peer using? Returns a 'const struct | ||
174 | * GNUNET_CONFIGURATION_Handle *'. Valid until | ||
175 | * 'GNUNET_TESTNIG_operation_done' is called. However, the | ||
176 | * values may be inaccurate if the peer is reconfigured in | ||
177 | * the meantime. | ||
178 | */ | ||
179 | GNUNET_TESTBED_PIT_CONFIGURATION, | ||
180 | |||
181 | /** | ||
182 | * What is the identity of the peer? Returns a | ||
183 | * 'const struct GNUNET_PeerIdentity *'. Valid until | ||
184 | * 'GNUNET_TESTNIG_operation_done' is called. | ||
185 | */ | ||
186 | GNUNET_TESTBED_PIT_IDENTITY | ||
187 | |||
188 | }; | ||
189 | |||
190 | |||
191 | /** | ||
192 | * Argument to GNUNET_TESTBED_ControllerCallback with details about | ||
193 | * the event. | ||
194 | */ | ||
195 | struct GNUNET_TESTBED_EventInformation | ||
196 | { | ||
197 | |||
198 | /** | ||
199 | * Type of the event. | ||
200 | */ | ||
201 | enum GNUNET_TESTBED_EventType type; | ||
202 | |||
203 | /** | ||
204 | * Details about the event. | ||
205 | */ | ||
206 | union | ||
207 | { | ||
208 | |||
209 | /** | ||
210 | * Details about peer start event. | ||
211 | */ | ||
212 | struct | ||
213 | { | ||
214 | /** | ||
215 | * Handle for the host where the peer | ||
216 | * was started. | ||
217 | */ | ||
218 | struct GNUNET_TESTBED_Host *host; | ||
219 | |||
220 | /** | ||
221 | * Handle for the peer that was started. | ||
222 | */ | ||
223 | struct GNUNET_TESTBED_Peer *peer; | ||
224 | |||
225 | } peer_start; | ||
226 | |||
227 | /** | ||
228 | * Details about peer stop event. | ||
229 | */ | ||
230 | struct | ||
231 | { | ||
232 | |||
233 | /** | ||
234 | * Handle for the peer that was started. | ||
235 | */ | ||
236 | struct GNUNET_TESTBED_Peer *peer; | ||
237 | |||
238 | } peer_stop; | ||
239 | |||
240 | /** | ||
241 | * Details about connect event. | ||
242 | */ | ||
243 | struct | ||
244 | { | ||
245 | /** | ||
246 | * Handle for one of the connected peers. | ||
247 | */ | ||
248 | struct GNUNET_TESTBED_Peer *peer1; | ||
249 | |||
250 | /** | ||
251 | * Handle for one of the connected peers. | ||
252 | */ | ||
253 | struct GNUNET_TESTBED_Peer *peer2; | ||
254 | |||
255 | } peer_connect; | ||
256 | |||
257 | /** | ||
258 | * Details about disconnect event. | ||
259 | */ | ||
260 | struct | ||
261 | { | ||
262 | /** | ||
263 | * Handle for one of the disconnected peers. | ||
264 | */ | ||
265 | struct GNUNET_TESTBED_Peer *peer1; | ||
266 | |||
267 | /** | ||
268 | * Handle for one of the disconnected peers. | ||
269 | */ | ||
270 | struct GNUNET_TESTBED_Peer *peer2; | ||
271 | |||
272 | } peer_disconnect; | ||
273 | |||
274 | /** | ||
275 | * Details about an operation finished event. | ||
276 | */ | ||
277 | struct | ||
278 | { | ||
279 | |||
280 | /** | ||
281 | * Handle for the operation that was finished. | ||
282 | */ | ||
283 | struct GNUNET_TESTBED_Operation *operation; | ||
284 | |||
285 | /** | ||
286 | * Closure that was passed in when the event was | ||
287 | * requested. | ||
288 | */ | ||
289 | void *op_cls; | ||
290 | |||
291 | /** | ||
292 | * Error message for the operation, NULL on success. | ||
293 | */ | ||
294 | const char *emsg; | ||
295 | |||
296 | /** | ||
297 | * Peer information type; captures which of the types | ||
298 | * in the 'op_result' is actually in use. | ||
299 | */ | ||
300 | enum GNUNET_TESTBED_PeerInformationType pit; | ||
301 | |||
302 | /** | ||
303 | * Pointer to an operation-specific return value; NULL on error; | ||
304 | * can be NULL for certain operations. Valid until | ||
305 | * 'GNUNET_TESTBED_operation_done' is called. | ||
306 | */ | ||
307 | union | ||
308 | { | ||
309 | /** | ||
310 | * No result (NULL pointer) or generic result | ||
311 | * (whatever the GNUNET_TESTBED_ConnectAdapter returned). | ||
312 | */ | ||
313 | void *generic; | ||
314 | |||
315 | /** | ||
316 | * Identity of host running the peer. | ||
317 | */ | ||
318 | struct GNUNET_TESTBED_Host *host; | ||
319 | |||
320 | /** | ||
321 | * Identity of the peer. | ||
322 | */ | ||
323 | const struct GNUNET_PeerIdentity *pid; | ||
324 | |||
325 | /** | ||
326 | * Configuration of the peer. | ||
327 | */ | ||
328 | const struct GNUNET_CONFIGURATION_Handle *cfg; | ||
329 | |||
330 | } op_result; | ||
331 | |||
332 | } operation_finished; | ||
333 | |||
334 | |||
335 | /** | ||
336 | * Details about an testbed run completed event. | ||
337 | */ | ||
338 | struct | ||
339 | { | ||
340 | |||
341 | /** | ||
342 | * Error message for the operation, NULL on success. | ||
343 | */ | ||
344 | const char *emsg; | ||
345 | |||
346 | /** | ||
347 | * Array of peers now running (valid until | ||
348 | * 'GNUNET_TESTBED_testbed_stop' is called). Note that it is | ||
349 | * not allowed to call 'GNUNET_TESTBED_peer_destroy' on peers | ||
350 | * from this array. | ||
351 | */ | ||
352 | struct GNUNET_TESTBED_Peer **peers; | ||
353 | |||
354 | /** | ||
355 | * Size of the 'peers' array. | ||
356 | */ | ||
357 | unsigned int num_peers; | ||
358 | |||
359 | } testbed_run_finished; | ||
360 | |||
361 | } details; | ||
362 | |||
363 | }; | ||
364 | |||
365 | |||
366 | /** | ||
367 | * Signature of the event handler function called by the | ||
368 | * respective event controller. | ||
369 | * | ||
370 | * @param cls closure | ||
371 | * @param event information about the event | ||
372 | */ | ||
373 | typedef void (*GNUNET_TESTBED_ControllerCallback)(void *cls, | ||
374 | const struct GNUNET_TESTBED_EventInformation *event); | ||
375 | |||
376 | |||
377 | /** | ||
378 | * Start a controller process using the given configuration at the | ||
379 | * given host. | ||
380 | * | ||
381 | * @param cfg configuration to use | ||
382 | * @param host host to run the controller on, NULL for 'localhost' | ||
383 | * @param event_mask bit mask with set of events to call 'cc' for; | ||
384 | * or-ed values of "1LL" shifted by the | ||
385 | * respective 'enum GNUNET_TESTBED_EventType' | ||
386 | * (i.e. "(1LL << GNUNET_TESTBED_ET_CONNECT) | ...") | ||
387 | * @param cc controller callback to invoke on events | ||
388 | * @param cc_cls closure for cc | ||
389 | * @return handle to the controller | ||
390 | */ | ||
391 | struct GNUNET_TESTBED_Controller * | ||
392 | GNUNET_TESTBED_controller_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
393 | struct GNUNET_TESTBED_Host *host, | ||
394 | uint64_t event_mask, | ||
395 | GNUNET_TESTBED_ControllerCallback cc, | ||
396 | void *cc_cls); | ||
397 | |||
398 | |||
399 | /** | ||
400 | * Configure shared services at a controller. Using this function, | ||
401 | * you can specify that certain services (such as "resolver") | ||
402 | * should not be run for each peer but instead be shared | ||
403 | * across N peers on the specified host. This function | ||
404 | * must be called before any peers are created at the host. | ||
405 | * | ||
406 | * @param controller controller to configure | ||
407 | * @param service_name name of the service to share | ||
408 | * @param num_peers number of peers that should share one instance | ||
409 | * of the specified service (1 for no sharing is the default), | ||
410 | * use 0 to disable the service | ||
411 | */ | ||
412 | void | ||
413 | GNUNET_TESTBED_controller_configure_sharing (struct GNUNET_TESTBED_Controller *controller, | ||
414 | const char *service_name, | ||
415 | uint32_t num_peers); | ||
416 | |||
417 | |||
418 | /** | ||
419 | * Stop the given controller (also will terminate all peers and | ||
420 | * controllers dependent on this controller). This function | ||
421 | * blocks until the testbed has been fully terminated (!). | ||
422 | * | ||
423 | * @param controller handle to controller to stop | ||
424 | */ | ||
425 | void | ||
426 | GNUNET_TESTBED_controller_stop (struct GNUNET_TESTBED_Controller *controller); | ||
427 | |||
428 | |||
429 | /** | ||
430 | * Create a link from a 'master' controller to a slave controller. | ||
431 | * Whenever the master controller is asked to start a peer at the | ||
432 | * given 'delegated_host', it will delegate the request to the | ||
433 | * specified slave controller. Note that the slave controller runs at | ||
434 | * the 'slave_host', which may or may not be the same host as the | ||
435 | * 'delegated_host' (for hierarchical delegations). The configuration | ||
436 | * of the slave controller is given and to be used to either create | ||
437 | * the slave controller or to connect to an existing slave controller | ||
438 | * process. 'is_subordinate' specifies if the given slave controller | ||
439 | * should be started and managed by the master controller, or if the | ||
440 | * slave already has a master and this is just a secondary master that | ||
441 | * is also allowed to use the existing slave. | ||
442 | * | ||
443 | * @param master handle to the master controller who creates the association | ||
444 | * @param delegated_host requests to which host should be delegated | ||
445 | * @param slave_host which host is used to run the slave controller | ||
446 | * @param slave_cfg configuration to use for the slave controller | ||
447 | * @param is_subordinate GNUNET_YES if the slave should be started (and stopped) | ||
448 | * by the master controller; GNUNET_NO if we are just | ||
449 | * allowed to use the slave via TCP/IP | ||
450 | */ | ||
451 | void | ||
452 | GNUNET_TESTBED_controller_link (struct GNUNET_TESTBED_Controller *master, | ||
453 | struct GNUNET_TESTBED_Host *delegated_host, | ||
454 | struct GNUNET_TESTBED_Host *slave_host, | ||
455 | const struct GNUNET_CONFIGURATION_Handle *slave_cfg, | ||
456 | int is_subordinate); | ||
457 | |||
458 | |||
459 | /** | ||
460 | * Create the given peer at the specified host using the given | ||
461 | * controller. If the given controller is not running on the target | ||
462 | * host, it should find or create a controller at the target host and | ||
463 | * delegate creating the peer. Explicit delegation paths can be setup | ||
464 | * using 'GNUNET_TESTBED_controller_link'. If no explicit delegation | ||
465 | * path exists, a direct link with a subordinate controller is setup | ||
466 | * for the first delegated peer to a particular host; the subordinate | ||
467 | * controller is then destroyed once the last peer that was delegated | ||
468 | * to the remote host is stopped. | ||
469 | * | ||
470 | * Creating the peer only creates the handle to manipulate and further | ||
471 | * configure the peer; use "GNUNET_TESTBED_peer_start" and | ||
472 | * "GNUNET_TESTBED_peer_stop" to actually start/stop the peer's | ||
473 | * processes. | ||
474 | * | ||
475 | * Note that the given configuration will be adjusted by the | ||
476 | * controller to avoid port/path conflicts with other peers. | ||
477 | * The "final" configuration can be obtained using | ||
478 | * 'GNUNET_TESTBED_peer_get_information'. | ||
479 | * | ||
480 | * @param controller controller process to use | ||
481 | * @param host host to run the peer on | ||
482 | * @param cfg configuration to use for the peer | ||
483 | * @return handle to the peer (actual startup will happen asynchronously) | ||
484 | */ | ||
485 | struct GNUNET_TESTBED_Peer * | ||
486 | GNUNET_TESTBED_peer_create (struct GNUNET_TESTBED_Controller *controller, | ||
487 | struct GNUNET_TESTBED_Host *host, | ||
488 | const struct GNUNET_CONFIGURATION_Handle *cfg); | ||
489 | |||
490 | |||
491 | /** | ||
492 | * Start the given peer. | ||
493 | * | ||
494 | * @param peer peer to start | ||
495 | * @return handle to the operation | ||
496 | */ | ||
497 | struct GNUNET_TESTBED_Operation * | ||
498 | GNUNET_TESTBED_peer_start (struct GNUNET_TESTBED_Peer *peer); | ||
499 | |||
500 | |||
501 | /** | ||
502 | * Stop the given peer. The handle remains valid (use | ||
503 | * "GNUNET_TESTBED_peer_destroy" to fully clean up the | ||
504 | * state of the peer). | ||
505 | * | ||
506 | * @param peer peer to stop | ||
507 | * @return handle to the operation | ||
508 | */ | ||
509 | struct GNUNET_TESTBED_Operation * | ||
510 | GNUNET_TESTBED_peer_stop (struct GNUNET_TESTBED_Peer *peer); | ||
511 | |||
512 | |||
513 | /** | ||
514 | * Request information about a peer. | ||
515 | * | ||
516 | * @param peer peer to request information about | ||
517 | * @param pit desired information | ||
518 | * @return handle to the operation | ||
519 | */ | ||
520 | struct GNUNET_TESTBED_Operation * | ||
521 | GNUNET_TESTBED_peer_get_information (struct GNUNET_TESTBED_Peer *peer, | ||
522 | enum GNUNET_TESTBED_PeerInformationType pit); | ||
523 | |||
524 | |||
525 | /** | ||
526 | * Change peer configuration. Must only be called while the | ||
527 | * peer is stopped. Ports and paths cannot be changed this | ||
528 | * way. | ||
529 | * | ||
530 | * @param peer peer to change configuration for | ||
531 | * @param cfg new configuration (differences to existing | ||
532 | * configuration only) | ||
533 | * @return handle to the operation | ||
534 | */ | ||
535 | struct GNUNET_TESTBED_Operation * | ||
536 | GNUNET_TESTBED_peer_update_configuration (struct GNUNET_TESTBED_Peer *peer, | ||
537 | const struct GNUNET_CONFIGURATION_Handle *cfg); | ||
538 | |||
539 | |||
540 | /** | ||
541 | * Destroy the given peer; the peer should have been | ||
542 | * stopped first (if it was started). | ||
543 | * | ||
544 | * @param peer peer to stop | ||
545 | * @return handle to the operation | ||
546 | */ | ||
547 | struct GNUNET_TESTBED_Operation * | ||
548 | GNUNET_TESTBED_peer_destroy (struct GNUNET_TESTBED_Peer *peer); | ||
549 | |||
550 | |||
551 | /** | ||
552 | * Options for peer connections. | ||
553 | */ | ||
554 | enum GNUNET_TESTBED_ConnectOption | ||
555 | { | ||
556 | /** | ||
557 | * No option (not valid as an argument). | ||
558 | */ | ||
559 | GNUNET_TESTBED_CO_NONE = 0, | ||
560 | |||
561 | /** | ||
562 | * Allow or disallow a connection between the specified peers. | ||
563 | * Followed by GNUNET_NO (int) if a connection is disallowed | ||
564 | * or GNUNET_YES if a connection is allowed. Note that the | ||
565 | * default (all connections allowed or disallowed) is | ||
566 | * specified in the configuration of the controller. | ||
567 | */ | ||
568 | GNUNET_TESTBED_CO_ALLOW = 1, | ||
569 | |||
570 | /** | ||
571 | * FIXME: add (and implement) options to limit connection to | ||
572 | * particular transports, force simulation of particular latencies | ||
573 | * or message loss rates, or set bandwidth limitations. | ||
574 | */ | ||
575 | |||
576 | }; | ||
577 | |||
578 | |||
579 | /** | ||
580 | * Manipulate the P2P underlay topology by configuring a link | ||
581 | * between two peers. | ||
582 | * | ||
583 | * @param op_cls closure argument to give with the operation event | ||
584 | * @param p1 first peer | ||
585 | * @param p2 second peer | ||
586 | * @param co option to change | ||
587 | * @param ... option-specific values | ||
588 | * @return handle to the operation, NULL if configuring the link at this | ||
589 | * time is not allowed | ||
590 | */ | ||
591 | struct GNUNET_TESTBED_Operation * | ||
592 | GNUNET_TESTBED_underlay_configure_link_va (void *op_cls, | ||
593 | struct GNUNET_TESTBED_Peer *p1, | ||
594 | struct GNUNET_TESTBED_Peer *p2, | ||
595 | enum GNUNET_TESTBED_ConnectOption co, | ||
596 | va_list ap); | ||
597 | |||
598 | |||
599 | /** | ||
600 | * Manipulate the P2P underlay topology by configuring a link | ||
601 | * between two peers. | ||
602 | * | ||
603 | * @param op_cls closure argument to give with the operation event | ||
604 | * @param p1 first peer | ||
605 | * @param p2 second peer | ||
606 | * @param co option to change | ||
607 | * @param ... option-specific values | ||
608 | * @return handle to the operation, NULL if configuring the link at this | ||
609 | * time is not allowed | ||
610 | */ | ||
611 | struct GNUNET_TESTBED_Operation * | ||
612 | GNUNET_TESTBED_underlay_configure_link (void *op_cls, | ||
613 | struct GNUNET_TESTBED_Peer *p1, | ||
614 | struct GNUNET_TESTBED_Peer *p2, | ||
615 | enum GNUNET_TESTBED_ConnectOption co, ...); | ||
616 | |||
617 | |||
618 | |||
619 | /** | ||
620 | * Topologies supported for testbeds. | ||
621 | */ | ||
622 | enum GNUNET_TESTBED_TopologyOption | ||
623 | { | ||
624 | /** | ||
625 | * A clique (everyone connected to everyone else). No options. | ||
626 | */ | ||
627 | GNUNET_TESTBED_TOPOLOGY_CLIQUE, | ||
628 | |||
629 | /** | ||
630 | * Small-world network (2d torus plus random links). Followed | ||
631 | * by the number of random links to add (unsigned int). | ||
632 | */ | ||
633 | GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD, | ||
634 | |||
635 | /** | ||
636 | * Small-world network (ring plus random links). Followed | ||
637 | * by the number of random links to add (unsigned int). | ||
638 | */ | ||
639 | GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD_RING, | ||
640 | |||
641 | /** | ||
642 | * Ring topology. No options. | ||
643 | */ | ||
644 | GNUNET_TESTBED_TOPOLOGY_RING, | ||
645 | |||
646 | /** | ||
647 | * 2-d torus. No options. | ||
648 | */ | ||
649 | GNUNET_TESTBED_TOPOLOGY_2D_TORUS, | ||
650 | |||
651 | /** | ||
652 | * Random graph. Followed by the link density, that is the | ||
653 | * percentage of links present in relation to a clique | ||
654 | * (float). | ||
655 | */ | ||
656 | GNUNET_TESTBED_TOPOLOGY_ERDOS_RENYI, | ||
657 | |||
658 | /** | ||
659 | * Certain percentage of peers are unable to communicate directly | ||
660 | * replicating NAT conditions. Followed by the fraction of | ||
661 | * NAT'ed peers (float). | ||
662 | */ | ||
663 | GNUNET_TESTBED_TOPOLOGY_INTERNAT, | ||
664 | |||
665 | /** | ||
666 | * Scale free topology. FIXME: options? | ||
667 | */ | ||
668 | GNUNET_TESTBED_TOPOLOGY_SCALE_FREE, | ||
669 | |||
670 | /** | ||
671 | * Straight line topology. No options. | ||
672 | */ | ||
673 | GNUNET_TESTBED_TOPOLOGY_LINE, | ||
674 | |||
675 | /** | ||
676 | * All peers are disconnected. No options. | ||
677 | */ | ||
678 | GNUNET_TESTBED_TOPOLOGY_NONE, | ||
679 | |||
680 | /** | ||
681 | * Read a topology from a given file. Followed by the name of the file (const char *). | ||
682 | */ | ||
683 | GNUNET_TESTBED_TOPOLOGY_FROM_FILE | ||
684 | }; | ||
685 | |||
686 | |||
687 | /** | ||
688 | * Configure overall network topology to have a particular shape. | ||
689 | * | ||
690 | * @param op_cls closure argument to give with the operation event | ||
691 | * @param num_peers number of peers in 'peers' | ||
692 | * @param peers array of 'num_peers' with the peers to configure | ||
693 | * @param topo desired underlay topology to use | ||
694 | * @param ap topology-specific options | ||
695 | * @return handle to the operation, NULL if configuring the topology | ||
696 | * is not allowed at this time | ||
697 | */ | ||
698 | struct GNUNET_TESTBED_Operation * | ||
699 | GNUNET_TESTBED_underlay_configure_topology_va (void *op_cls, | ||
700 | unsigned int num_peers, | ||
701 | struct GNUNET_TESTBED_Peer **peers, | ||
702 | enum GNUNET_TESTBED_TopologyOption topo, | ||
703 | va_list ap); | ||
704 | |||
705 | |||
706 | /** | ||
707 | * Configure overall network topology to have a particular shape. | ||
708 | * | ||
709 | * @param op_cls closure argument to give with the operation event | ||
710 | * @param num_peers number of peers in 'peers' | ||
711 | * @param peers array of 'num_peers' with the peers to configure | ||
712 | * @param topo desired underlay topology to use | ||
713 | * @param ... topology-specific options | ||
714 | * @return handle to the operation, NULL if configuring the topology | ||
715 | * is not allowed at this time | ||
716 | */ | ||
717 | struct GNUNET_TESTBED_Operation * | ||
718 | GNUNET_TESTBED_underlay_configure_topology (void *op_cls, | ||
719 | unsigned int num_peers, | ||
720 | struct GNUNET_TESTBED_Peer **peers, | ||
721 | enum GNUNET_TESTBED_TopologyOption topo, | ||
722 | ...); | ||
723 | |||
724 | |||
725 | /** | ||
726 | * Both peers must have been started before calling this function. | ||
727 | * This function then obtains a HELLO from 'p1', gives it to 'p2' | ||
728 | * and asks 'p2' to connect to 'p1'. | ||
729 | * | ||
730 | * @param op_cls closure argument to give with the operation event | ||
731 | * @param p1 first peer | ||
732 | * @param p2 second peer | ||
733 | * @return handle to the operation, NULL if connecting these two | ||
734 | * peers is fundamentally not possible at this time (peers | ||
735 | * not running or underlay disallows) | ||
736 | */ | ||
737 | struct GNUNET_TESTBED_Operation * | ||
738 | GNUNET_TESTBED_overlay_connect (void *op_cls, | ||
739 | struct GNUNET_TESTBED_Peer *p1, | ||
740 | struct GNUNET_TESTBED_Peer *p2); | ||
741 | |||
742 | |||
743 | /** | ||
744 | * All peers must have been started before calling this function. | ||
745 | * This function then connects the given peers in the P2P overlay | ||
746 | * using the given topology. | ||
747 | * | ||
748 | * @param op_cls closure argument to give with the operation event | ||
749 | * @param num_peers number of peers in 'peers' | ||
750 | * @param peers array of 'num_peers' with the peers to configure | ||
751 | * @param topo desired underlay topology to use | ||
752 | * @param va topology-specific options | ||
753 | * @return handle to the operation, NULL if connecting these | ||
754 | * peers is fundamentally not possible at this time (peers | ||
755 | * not running or underlay disallows) | ||
756 | */ | ||
757 | struct GNUNET_TESTBED_Operation * | ||
758 | GNUNET_TESTBED_overlay_configure_topology_va (void *op_cls, | ||
759 | unsigned int num_peers, | ||
760 | struct GNUNET_TESTBED_Peer *peers, | ||
761 | enum GNUNET_TESTBED_TopologyOption topo, | ||
762 | va_list va); | ||
763 | |||
764 | |||
765 | /** | ||
766 | * All peers must have been started before calling this function. | ||
767 | * This function then connects the given peers in the P2P overlay | ||
768 | * using the given topology. | ||
769 | * | ||
770 | * @param op_cls closure argument to give with the operation event | ||
771 | * @param num_peers number of peers in 'peers' | ||
772 | * @param peers array of 'num_peers' with the peers to configure | ||
773 | * @param topo desired underlay topology to use | ||
774 | * @param ... topology-specific options | ||
775 | * @return handle to the operation, NULL if connecting these | ||
776 | * peers is fundamentally not possible at this time (peers | ||
777 | * not running or underlay disallows) | ||
778 | */ | ||
779 | struct GNUNET_TESTBED_Operation * | ||
780 | GNUNET_TESTBED_overlay_configure_topology (void *op_cls, | ||
781 | unsigned int num_peers, | ||
782 | struct GNUNET_TESTBED_Peer *peers, | ||
783 | enum GNUNET_TESTBED_TopologyOption topo, | ||
784 | ...); | ||
785 | |||
786 | |||
787 | |||
788 | /** | ||
789 | * Ask the testbed controller to write the current overlay topology to | ||
790 | * a file. Naturally, the file will only contain a snapshot as the | ||
791 | * topology may evolve all the time. | ||
792 | * | ||
793 | * @param controller overlay controller to inspect | ||
794 | * @param filename name of the file the topology should | ||
795 | * be written to. | ||
796 | */ | ||
797 | void | ||
798 | GNUNET_TESTBED_overlay_write_topology_to_file (struct GNUNET_TESTBED_Controller *controller, | ||
799 | const char *filename); | ||
800 | |||
801 | |||
802 | /** | ||
803 | * Adapter function called to establish a connection to | ||
804 | * a service. | ||
805 | * | ||
806 | * @param cls closure | ||
807 | * @param cfg configuration of the peer to connect to | ||
808 | * @return service handle to return in 'op_result', NULL on error | ||
809 | */ | ||
810 | typedef void * (*GNUNET_TESTBED_ConnectAdapter)(void *cls, | ||
811 | const struct GNUNET_CONFIGURATION_Handle *cfg); | ||
812 | |||
813 | |||
814 | /** | ||
815 | * Adapter function called to destroy a connection to | ||
816 | * a service. | ||
817 | * | ||
818 | * @param cls closure | ||
819 | * @param op_result service handle returned from the connect adapter | ||
820 | */ | ||
821 | typedef void (*GNUNET_TESTBED_DisconnectAdapter)(void *cls, | ||
822 | void *op_result); | ||
823 | |||
824 | |||
825 | /** | ||
826 | * Connect to a service offered by the given peer. Will ensure that | ||
827 | * the request is queued to not overwhelm our ability to create and | ||
828 | * maintain connections with other systems. The actual service | ||
829 | * handle is then returned via the 'op_result' member in the event | ||
830 | * callback. The 'ca' callback is used to create the connection | ||
831 | * when the time is right; the 'da' callback will be used to | ||
832 | * destroy the connection (upon 'GNUNET_TESTBED_operation_done'). | ||
833 | * 'GNUNET_TESTBED_operation_cancel' can be used to abort this | ||
834 | * operation until the event callback has been called. | ||
835 | * | ||
836 | * @param op_cls closure to pass in operation event | ||
837 | * @param peer peer that runs the service | ||
838 | * @param service_name name of the service to connect to | ||
839 | * @param ca helper function to establish the connection | ||
840 | * @param da helper function to close the connection | ||
841 | * @param cada_cls closure for ca and da | ||
842 | * @return handle for the operation | ||
843 | */ | ||
844 | struct GNUNET_TESTBED_Operation * | ||
845 | GNUNET_TESTBED_service_connect (void *op_cls, | ||
846 | struct GNUNET_TESTBED_Peer *peer, | ||
847 | const char *service_name, | ||
848 | GNUNET_TESTBED_ConnectAdapter ca, | ||
849 | GNUNET_TESTBED_DisconnectAdapter da, | ||
850 | void *cada_cls); | ||
851 | |||
852 | |||
853 | /** | ||
854 | * Cancel a pending operation. Releases all resources | ||
855 | * of the operation and will ensure that no event | ||
856 | * is generated for the operation. Does NOT guarantee | ||
857 | * that the operation will be fully undone (or that | ||
858 | * nothing ever happened). | ||
859 | * | ||
860 | * @param operation operation to cancel | ||
861 | */ | ||
862 | void | ||
863 | GNUNET_TESTBED_operation_cancel (struct GNUNET_TESTBED_Operation *operation); | ||
864 | |||
865 | |||
866 | /** | ||
867 | * Signal that the information from an operation has been fully | ||
868 | * processed. This function MUST be called for each event | ||
869 | * of type 'operation_finished' to fully remove the operation | ||
870 | * from the operation queue. After calling this function, the | ||
871 | * 'op_result' becomes invalid (!). | ||
872 | * | ||
873 | * @param operation operation to signal completion for | ||
874 | */ | ||
875 | void | ||
876 | GNUNET_TESTBED_operation_done (struct GNUNET_TESTBED_Operation *operation); | ||
877 | |||
878 | |||
879 | /** | ||
880 | * Configure and run a testbed using the given | ||
881 | * master controller on 'num_hosts' starting | ||
882 | * 'num_peers' using the given peer configuration. | ||
883 | * | ||
884 | * @param controller master controller for the testbed | ||
885 | * (must not be destroyed until after the | ||
886 | * testbed is destroyed). | ||
887 | * @param num_hosts number of hosts in 'hosts', 0 to only | ||
888 | * use 'localhost' | ||
889 | * @param hosts list of hosts to use for the testbed | ||
890 | * @param num_peers number of peers to start | ||
891 | * @param peer_cfg peer configuration template to use | ||
892 | * @param underlay_topology underlay topology to create | ||
893 | * @param va topology-specific options | ||
894 | * @return handle to the testbed | ||
895 | */ | ||
896 | struct GNUNET_TESTBED_Testbed * | ||
897 | GNUNET_TESTBED_create_va (struct GNUNET_TESTBED_Controller *controller, | ||
898 | unsigned int num_hosts, | ||
899 | struct GNUNET_TESTBED_Host **hosts, | ||
900 | unsigned int num_peers, | ||
901 | const struct GNUNET_CONFIGURATION_Handle *peer_cfg, | ||
902 | enum GNUNET_TESTBED_TopologyOption underlay_topology, | ||
903 | va_list va); | ||
904 | |||
905 | |||
906 | /** | ||
907 | * Configure and run a testbed using the given | ||
908 | * master controller on 'num_hosts' starting | ||
909 | * 'num_peers' using the given peer configuration. | ||
910 | * | ||
911 | * @param controller master controller for the testbed | ||
912 | * (must not be destroyed until after the | ||
913 | * testbed is destroyed). | ||
914 | * @param num_hosts number of hosts in 'hosts', 0 to only | ||
915 | * use 'localhost' | ||
916 | * @param hosts list of hosts to use for the testbed | ||
917 | * @param num_peers number of peers to start | ||
918 | * @param peer_cfg peer configuration template to use | ||
919 | * @param underlay_topology underlay topology to create | ||
920 | * @param ... topology-specific options | ||
921 | */ | ||
922 | struct GNUNET_TESTBED_Testbed * | ||
923 | GNUNET_TESTBED_create (struct GNUNET_TESTBED_Controller *controller, | ||
924 | unsigned int num_hosts, | ||
925 | struct GNUNET_TESTBED_Host **hosts, | ||
926 | unsigned int num_peers, | ||
927 | const struct GNUNET_CONFIGURATION_Handle *peer_cfg, | ||
928 | enum GNUNET_TESTBED_TopologyOption underlay_topology, | ||
929 | ...); | ||
930 | |||
931 | |||
932 | /** | ||
933 | * Destroy a testbed. Stops all running peers and then | ||
934 | * destroys all peers. Does NOT destroy the master controller. | ||
935 | * | ||
936 | * @param testbed testbed to destroy | ||
937 | */ | ||
938 | void | ||
939 | GNUNET_TESTBED_destroy (struct GNUNET_TESTBED_Testbed *testbed); | ||
940 | |||
941 | |||
942 | /** | ||
943 | * Convenience method for running a testbed with | ||
944 | * a single call. Underlay and overlay topology | ||
945 | * are configured using the "UNDERLAY" and "OVERLAY" | ||
946 | * options in the "[testbed]" section of the configuration\ | ||
947 | * (with possible options given in "UNDERLAY_XXX" and/or | ||
948 | * "OVERLAY_XXX"). | ||
949 | * | ||
950 | * The testbed is to be terminated using a call to | ||
951 | * "GNUNET_SCHEDULER_shutdown". | ||
952 | * | ||
953 | * @param host_filename name of the file with the 'hosts', NULL | ||
954 | * to run everything on 'localhost' | ||
955 | * @param cfg configuration to use (for testbed, controller and peers) | ||
956 | * @param num_peers number of peers to start; FIXME: maybe put that ALSO into cfg? | ||
957 | * @param event_mask bit mask with set of events to call 'cc' for; | ||
958 | * or-ed values of "1LL" shifted by the | ||
959 | * respective 'enum GNUNET_TESTBED_EventType' | ||
960 | * (i.e. "(1LL << GNUNET_TESTBED_ET_CONNECT) || ...") | ||
961 | * @param cc controller callback to invoke on events | ||
962 | * @param cc_cls closure for cc | ||
963 | * @param master task to run once the testbed is ready | ||
964 | * @param master_cls closure for 'task'. | ||
965 | */ | ||
966 | void | ||
967 | GNUNET_TESTBED_run (const char *host_filename, | ||
968 | const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
969 | unsigned int num_peers, | ||
970 | uint64_t event_mask, | ||
971 | GNUNET_TESTBED_ControllerCallback cc, | ||
972 | void *cc_cls, | ||
973 | GNUNET_SCHEDULER_Task master, | ||
974 | void *master_cls); | ||
975 | |||
976 | |||
977 | /** | ||
978 | * Signature of a main function for a testcase. | ||
979 | * | ||
980 | * @param cls closure | ||
981 | * @param num_peers number of peers in 'peers' | ||
982 | * @param peers handle to peers run in the testbed | ||
983 | */ | ||
984 | typedef void (*GNUNET_TESTBED_TestMaster)(void *cls, | ||
985 | unsigned int num_peers, | ||
986 | struct GNUNET_TESTBED_Peer **peers); | ||
987 | |||
988 | |||
989 | /** | ||
990 | * Convenience method for running a "simple" test on the local system | ||
991 | * with a single call from 'main'. Underlay and overlay topology are | ||
992 | * configured using the "UNDERLAY" and "OVERLAY" options in the | ||
993 | * "[testbed]" section of the configuration (with possible options | ||
994 | * given in "UNDERLAY_XXX" and/or "OVERLAY_XXX"). | ||
995 | * | ||
996 | * The test is to be terminated using a call to | ||
997 | * "GNUNET_SCHEDULER_shutdown". If starting the test fails, | ||
998 | * the program is stopped without 'master' ever being run. | ||
999 | * | ||
1000 | * NOTE: this function should be called from 'main', NOT from | ||
1001 | * within a GNUNET_SCHEDULER-loop. This function will initialze | ||
1002 | * the scheduler loop, the testbed and then pass control to | ||
1003 | * 'master'. | ||
1004 | * | ||
1005 | * @param testname name of the testcase (to configure logging, etc.) | ||
1006 | * @param cfg_filename configuration filename to use | ||
1007 | * (for testbed, controller and peers) | ||
1008 | * @param num_peers number of peers to start | ||
1009 | * @param test_master task to run once the test is ready | ||
1010 | * @param test_master_cls closure for 'task'. | ||
1011 | */ | ||
1012 | void | ||
1013 | GNUNET_TESTBED_test_run (const char *testname, | ||
1014 | const char *cfg_filename, | ||
1015 | unsigned int num_peers, | ||
1016 | GNUNET_TESTBED_TestMaster test_master, | ||
1017 | void *test_master_cls); | ||
1018 | |||
1019 | |||
1020 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
1021 | { | ||
1022 | #endif | ||
1023 | |||
1024 | |||
1025 | #ifdef __cplusplus | ||
1026 | } | ||
1027 | #endif | ||
1028 | |||
1029 | #endif | ||