diff options
author | Sree Harsha Totakura <totakura@in.tum.de> | 2012-09-05 10:50:56 +0000 |
---|---|---|
committer | Sree Harsha Totakura <totakura@in.tum.de> | 2012-09-05 10:50:56 +0000 |
commit | 270a6392703fe1cb99f69ed8a35c1be0c864b11f (patch) | |
tree | 1c65d01fefab939684c58757880987d2a00fd060 /src/include | |
parent | c09edda8e8071c6e5ca6b76e7c75a7b8402010ed (diff) | |
download | gnunet-270a6392703fe1cb99f69ed8a35c1be0c864b11f.tar.gz gnunet-270a6392703fe1cb99f69ed8a35c1be0c864b11f.zip |
changed testbed API to include convenience callbacks
Diffstat (limited to 'src/include')
-rw-r--r-- | src/include/gnunet_testbed_service-new.h | 1268 | ||||
-rw-r--r-- | src/include/gnunet_testbed_service.h | 120 |
2 files changed, 84 insertions, 1304 deletions
diff --git a/src/include/gnunet_testbed_service-new.h b/src/include/gnunet_testbed_service-new.h deleted file mode 100644 index 75f7a0ab2..000000000 --- a/src/include/gnunet_testbed_service-new.h +++ /dev/null | |||
@@ -1,1268 +0,0 @@ | |||
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 | #include "gnunet_testing_lib-new.h" | ||
33 | |||
34 | #ifdef __cplusplus | ||
35 | extern "C" | ||
36 | { | ||
37 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
38 | } | ||
39 | #endif | ||
40 | #endif | ||
41 | |||
42 | |||
43 | /** | ||
44 | * Opaque handle to a host running experiments managed by the testbed framework. | ||
45 | * The master process must be able to SSH to this host without password (via | ||
46 | * ssh-agent). | ||
47 | */ | ||
48 | struct GNUNET_TESTBED_Host; | ||
49 | |||
50 | /** | ||
51 | * Opaque handle to a peer controlled by the testbed framework. A peer runs | ||
52 | * at a particular host. | ||
53 | */ | ||
54 | struct GNUNET_TESTBED_Peer; | ||
55 | |||
56 | /** | ||
57 | * Opaque handle to an abstract operation to be executed by the testbed framework. | ||
58 | */ | ||
59 | struct GNUNET_TESTBED_Operation; | ||
60 | |||
61 | /** | ||
62 | * Handle to interact with a GNUnet testbed controller. Each | ||
63 | * controller has at least one master handle which is created when the | ||
64 | * controller is created; this master handle interacts with the | ||
65 | * controller process, destroying it destroys the controller (by | ||
66 | * closing stdin of the controller process). Additionally, | ||
67 | * controllers can interact with each other (in a P2P fashion); those | ||
68 | * links are established via TCP/IP on the controller's service port. | ||
69 | */ | ||
70 | struct GNUNET_TESTBED_Controller; | ||
71 | |||
72 | /** | ||
73 | * Handle to a large-scale testbed that is managed at a high level. | ||
74 | */ | ||
75 | struct GNUNET_TESTBED_Testbed; | ||
76 | |||
77 | |||
78 | /** | ||
79 | * Create a host to run peers and controllers on. | ||
80 | * | ||
81 | * @param hostname name of the host, use "NULL" for localhost | ||
82 | * @param username username to use for the login; may be NULL | ||
83 | * @param port port number to use for ssh; use 0 to let ssh decide | ||
84 | * @return handle to the host, NULL on error | ||
85 | */ | ||
86 | struct GNUNET_TESTBED_Host * | ||
87 | GNUNET_TESTBED_host_create (const char *hostname, | ||
88 | const char *username, | ||
89 | uint16_t port); | ||
90 | |||
91 | |||
92 | |||
93 | /** | ||
94 | * Create a host to run peers and controllers on. This function is used | ||
95 | * if a peer learns about a host via IPC between controllers (and thus | ||
96 | * some higher-level controller has already determined the unique IDs). | ||
97 | * | ||
98 | * @param id global host ID assigned to the host; 0 is | ||
99 | * reserved to always mean 'localhost' | ||
100 | * @param hostname name of the host, use "NULL" for localhost | ||
101 | * @param username username to use for the login; may be NULL | ||
102 | * @param port port number to use for ssh; use 0 to let ssh decide | ||
103 | * @return handle to the host, NULL on error | ||
104 | */ | ||
105 | struct GNUNET_TESTBED_Host * | ||
106 | GNUNET_TESTBED_host_create_with_id (uint32_t id, | ||
107 | const char *hostname, | ||
108 | const char *username, | ||
109 | uint16_t port); | ||
110 | |||
111 | |||
112 | /** | ||
113 | * Load a set of hosts from a configuration file. | ||
114 | * | ||
115 | * @param filename file with the host specification | ||
116 | * @param hosts set to the hosts found in the file | ||
117 | * @return number of hosts returned in 'hosts', 0 on error | ||
118 | */ | ||
119 | unsigned int | ||
120 | GNUNET_TESTBED_hosts_load_from_file (const char *filename, | ||
121 | struct GNUNET_TESTBED_Host **hosts); | ||
122 | |||
123 | |||
124 | /** | ||
125 | * Destroy a host handle. Must only be called once everything | ||
126 | * running on that host has been stopped. | ||
127 | * | ||
128 | * @param host handle to destroy | ||
129 | */ | ||
130 | void | ||
131 | GNUNET_TESTBED_host_destroy (struct GNUNET_TESTBED_Host *host); | ||
132 | |||
133 | |||
134 | /** | ||
135 | * Enumeration with (at most 64) possible event types that | ||
136 | * can be monitored using the testbed framework. | ||
137 | */ | ||
138 | enum GNUNET_TESTBED_EventType | ||
139 | { | ||
140 | /** | ||
141 | * A peer has been started. | ||
142 | */ | ||
143 | GNUNET_TESTBED_ET_PEER_START = 0, | ||
144 | |||
145 | /** | ||
146 | * A peer has been stopped. | ||
147 | */ | ||
148 | GNUNET_TESTBED_ET_PEER_STOP = 1, | ||
149 | |||
150 | /** | ||
151 | * A connection between two peers was established. | ||
152 | */ | ||
153 | GNUNET_TESTBED_ET_CONNECT = 2, | ||
154 | |||
155 | /** | ||
156 | * A connection between two peers was torn down. | ||
157 | */ | ||
158 | GNUNET_TESTBED_ET_DISCONNECT = 3, | ||
159 | |||
160 | /** | ||
161 | * A requested testbed operation has been completed. | ||
162 | */ | ||
163 | GNUNET_TESTBED_ET_OPERATION_FINISHED = 4, | ||
164 | |||
165 | /** | ||
166 | * The 'GNUNET_TESTBED_run' operation has been completed | ||
167 | */ | ||
168 | GNUNET_TESTBED_ET_TESTBED_ONLINE = 5 | ||
169 | |||
170 | }; | ||
171 | |||
172 | |||
173 | /** | ||
174 | * Types of information that can be requested about a peer. | ||
175 | */ | ||
176 | enum GNUNET_TESTBED_PeerInformationType | ||
177 | { | ||
178 | |||
179 | /** | ||
180 | * Special value (not valid for requesting information) | ||
181 | * that is used in the event struct if a 'generic' pointer | ||
182 | * is returned (for other operations not related to this | ||
183 | * enumeration). | ||
184 | */ | ||
185 | GNUNET_TESTBED_PIT_GENERIC = 0, | ||
186 | |||
187 | /** | ||
188 | * What configuration is the peer using? Returns a 'const struct | ||
189 | * GNUNET_CONFIGURATION_Handle *'. Valid until | ||
190 | * 'GNUNET_TESTNIG_operation_done' is called. However, the | ||
191 | * values may be inaccurate if the peer is reconfigured in | ||
192 | * the meantime. | ||
193 | */ | ||
194 | GNUNET_TESTBED_PIT_CONFIGURATION, | ||
195 | |||
196 | /** | ||
197 | * What is the identity of the peer? Returns a | ||
198 | * 'const struct GNUNET_PeerIdentity *'. Valid until | ||
199 | * 'GNUNET_TESTNIG_operation_done' is called. | ||
200 | */ | ||
201 | GNUNET_TESTBED_PIT_IDENTITY | ||
202 | |||
203 | }; | ||
204 | |||
205 | |||
206 | /** | ||
207 | * Argument to GNUNET_TESTBED_ControllerCallback with details about | ||
208 | * the event. | ||
209 | */ | ||
210 | struct GNUNET_TESTBED_EventInformation | ||
211 | { | ||
212 | |||
213 | /** | ||
214 | * Type of the event. | ||
215 | */ | ||
216 | enum GNUNET_TESTBED_EventType type; | ||
217 | |||
218 | /** | ||
219 | * Details about the event. | ||
220 | */ | ||
221 | union | ||
222 | { | ||
223 | |||
224 | /** | ||
225 | * Details about peer start event. | ||
226 | */ | ||
227 | struct | ||
228 | { | ||
229 | /** | ||
230 | * Handle for the host where the peer | ||
231 | * was started. | ||
232 | */ | ||
233 | struct GNUNET_TESTBED_Host *host; | ||
234 | |||
235 | /** | ||
236 | * Handle for the peer that was started. | ||
237 | */ | ||
238 | struct GNUNET_TESTBED_Peer *peer; | ||
239 | |||
240 | } peer_start; | ||
241 | |||
242 | /** | ||
243 | * Details about peer stop event. | ||
244 | */ | ||
245 | struct | ||
246 | { | ||
247 | |||
248 | /** | ||
249 | * Handle for the peer that was started. | ||
250 | */ | ||
251 | struct GNUNET_TESTBED_Peer *peer; | ||
252 | |||
253 | } peer_stop; | ||
254 | |||
255 | /** | ||
256 | * Details about connect event. | ||
257 | */ | ||
258 | struct | ||
259 | { | ||
260 | /** | ||
261 | * Handle for one of the connected peers. | ||
262 | */ | ||
263 | struct GNUNET_TESTBED_Peer *peer1; | ||
264 | |||
265 | /** | ||
266 | * Handle for one of the connected peers. | ||
267 | */ | ||
268 | struct GNUNET_TESTBED_Peer *peer2; | ||
269 | |||
270 | } peer_connect; | ||
271 | |||
272 | /** | ||
273 | * Details about disconnect event. | ||
274 | */ | ||
275 | struct | ||
276 | { | ||
277 | /** | ||
278 | * Handle for one of the disconnected peers. | ||
279 | */ | ||
280 | struct GNUNET_TESTBED_Peer *peer1; | ||
281 | |||
282 | /** | ||
283 | * Handle for one of the disconnected peers. | ||
284 | */ | ||
285 | struct GNUNET_TESTBED_Peer *peer2; | ||
286 | |||
287 | } peer_disconnect; | ||
288 | |||
289 | /** | ||
290 | * Details about an operation finished event. | ||
291 | */ | ||
292 | struct | ||
293 | { | ||
294 | |||
295 | /** | ||
296 | * Handle for the operation that was finished. | ||
297 | */ | ||
298 | struct GNUNET_TESTBED_Operation *operation; | ||
299 | |||
300 | /** | ||
301 | * Closure that was passed in when the event was | ||
302 | * requested. | ||
303 | */ | ||
304 | void *op_cls; | ||
305 | |||
306 | /** | ||
307 | * Error message for the operation, NULL on success. | ||
308 | */ | ||
309 | const char *emsg; | ||
310 | |||
311 | /** | ||
312 | * No result (NULL pointer) or generic result | ||
313 | * (whatever the GNUNET_TESTBED_ConnectAdapter returned). | ||
314 | */ | ||
315 | void *generic; | ||
316 | |||
317 | } operation_finished; | ||
318 | |||
319 | |||
320 | /** | ||
321 | * Details about an testbed run completed event. | ||
322 | */ | ||
323 | struct | ||
324 | { | ||
325 | |||
326 | /** | ||
327 | * Error message for the operation, NULL on success. | ||
328 | */ | ||
329 | const char *emsg; | ||
330 | |||
331 | /** | ||
332 | * Array of peers now running (valid until | ||
333 | * 'GNUNET_TESTBED_testbed_stop' is called). Note that it is | ||
334 | * not allowed to call 'GNUNET_TESTBED_peer_destroy' on peers | ||
335 | * from this array. | ||
336 | */ | ||
337 | struct GNUNET_TESTBED_Peer **peers; | ||
338 | |||
339 | /** | ||
340 | * Size of the 'peers' array. | ||
341 | */ | ||
342 | unsigned int num_peers; | ||
343 | |||
344 | } testbed_run_finished; | ||
345 | |||
346 | } details; | ||
347 | |||
348 | }; | ||
349 | |||
350 | |||
351 | /** | ||
352 | * Signature of the event handler function called by the | ||
353 | * respective event controller. | ||
354 | * | ||
355 | * @param cls closure | ||
356 | * @param event information about the event | ||
357 | */ | ||
358 | typedef void (*GNUNET_TESTBED_ControllerCallback)(void *cls, | ||
359 | const struct GNUNET_TESTBED_EventInformation *event); | ||
360 | |||
361 | |||
362 | /** | ||
363 | * Opaque Handle for Controller process | ||
364 | */ | ||
365 | struct GNUNET_TESTBED_ControllerProc; | ||
366 | |||
367 | |||
368 | /** | ||
369 | * Callback to signal successfull startup of the controller process | ||
370 | * | ||
371 | * @param cls the closure from GNUNET_TESTBED_controller_start() | ||
372 | * @param cfg the configuration with which the controller has been started; | ||
373 | * NULL if status is not GNUNET_OK | ||
374 | * @param status GNUNET_OK if the startup is successfull; GNUNET_SYSERR if not, | ||
375 | * GNUNET_TESTBED_controller_stop() shouldn't be called in this case | ||
376 | */ | ||
377 | typedef void (*GNUNET_TESTBED_ControllerStatusCallback) (void *cls, | ||
378 | const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
379 | int status); | ||
380 | |||
381 | |||
382 | /** | ||
383 | * Starts a controller process at the host. FIXME: add controller start callback | ||
384 | * with the configuration with which the controller is started | ||
385 | * | ||
386 | * @param controller_ip the ip address of the controller. Will be set as TRUSTED | ||
387 | * host when starting testbed controller at host | ||
388 | * @param host the host where the controller has to be started; NULL for | ||
389 | * localhost | ||
390 | * @param cfg template configuration to use for the remote controller; the | ||
391 | * remote controller will be started with a slightly modified | ||
392 | * configuration (port numbers, unix domain sockets and service home | ||
393 | * values are changed as per TESTING library on the remote host) | ||
394 | * @param cb function called when the controller is successfully started or | ||
395 | * dies unexpectedly; GNUNET_TESTBED_controller_stop shouldn't be | ||
396 | * called if cb is called with GNUNET_SYSERR as status. Will never be | ||
397 | * called in the same task as 'GNUNET_TESTBED_controller_start' | ||
398 | * (synchronous errors will be signalled by returning NULL). This | ||
399 | * parameter cannot be NULL. | ||
400 | * @param cls closure for above callbacks | ||
401 | * @return the controller process handle, NULL on errors | ||
402 | */ | ||
403 | struct GNUNET_TESTBED_ControllerProc * | ||
404 | GNUNET_TESTBED_controller_start (const char *controller_ip, | ||
405 | struct GNUNET_TESTBED_Host *host, | ||
406 | const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
407 | GNUNET_TESTBED_ControllerStatusCallback cb, | ||
408 | void *cls); | ||
409 | |||
410 | |||
411 | /** | ||
412 | * Stop the controller process (also will terminate all peers and controllers | ||
413 | * dependent on this controller). This function blocks until the testbed has | ||
414 | * been fully terminated (!). | ||
415 | * | ||
416 | * @param cproc the controller process handle | ||
417 | */ | ||
418 | void | ||
419 | GNUNET_TESTBED_controller_stop (struct GNUNET_TESTBED_ControllerProc *cproc); | ||
420 | |||
421 | |||
422 | /** | ||
423 | * Connect to a controller process using the given configuration at the | ||
424 | * given host. | ||
425 | * | ||
426 | * @param cfg configuration to use | ||
427 | * @param host host to run the controller on; This should be the same host if | ||
428 | * the controller was previously started with | ||
429 | * GNUNET_TESTBED_controller_start; NULL for localhost | ||
430 | * @param host host where this controller is being run; | ||
431 | * @param event_mask bit mask with set of events to call 'cc' for; | ||
432 | * or-ed values of "1LL" shifted by the | ||
433 | * respective 'enum GNUNET_TESTBED_EventType' | ||
434 | * (i.e. "(1LL << GNUNET_TESTBED_ET_CONNECT) | ...") | ||
435 | * @param cc controller callback to invoke on events | ||
436 | * @param cc_cls closure for cc | ||
437 | * @return handle to the controller | ||
438 | */ | ||
439 | struct GNUNET_TESTBED_Controller * | ||
440 | GNUNET_TESTBED_controller_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
441 | struct GNUNET_TESTBED_Host *host, | ||
442 | uint64_t event_mask, | ||
443 | GNUNET_TESTBED_ControllerCallback cc, | ||
444 | void *cc_cls); | ||
445 | |||
446 | |||
447 | /** | ||
448 | * Configure shared services at a controller. Using this function, | ||
449 | * you can specify that certain services (such as "resolver") | ||
450 | * should not be run for each peer but instead be shared | ||
451 | * across N peers on the specified host. This function | ||
452 | * must be called before any peers are created at the host. | ||
453 | * | ||
454 | * @param controller controller to configure | ||
455 | * @param service_name name of the service to share | ||
456 | * @param num_peers number of peers that should share one instance | ||
457 | * of the specified service (1 for no sharing is the default), | ||
458 | * use 0 to disable the service | ||
459 | */ | ||
460 | void | ||
461 | GNUNET_TESTBED_controller_configure_sharing (struct GNUNET_TESTBED_Controller *controller, | ||
462 | const char *service_name, | ||
463 | uint32_t num_peers); | ||
464 | |||
465 | |||
466 | /** | ||
467 | * Stop the given controller (also will terminate all peers and | ||
468 | * controllers dependent on this controller). This function | ||
469 | * blocks until the testbed has been fully terminated (!). | ||
470 | * | ||
471 | * @param controller handle to controller to stop | ||
472 | */ | ||
473 | void | ||
474 | GNUNET_TESTBED_controller_disconnect (struct GNUNET_TESTBED_Controller *controller); | ||
475 | |||
476 | |||
477 | /** | ||
478 | * Opaque handle for host registration | ||
479 | */ | ||
480 | struct GNUNET_TESTBED_HostRegistrationHandle; | ||
481 | |||
482 | |||
483 | /** | ||
484 | * Callback which will be called to after a host registration succeeded or failed | ||
485 | * | ||
486 | * @param cls the closure | ||
487 | * @param emsg the error message; NULL if host registration is successful | ||
488 | */ | ||
489 | typedef void (* GNUNET_TESTBED_HostRegistrationCompletion) (void *cls, | ||
490 | const char *emsg); | ||
491 | |||
492 | |||
493 | /** | ||
494 | * Register a host with the controller | ||
495 | * | ||
496 | * @param controller the controller handle | ||
497 | * @param host the host to register | ||
498 | * @param cc the completion callback to call to inform the status of | ||
499 | * registration. After calling this callback the registration handle | ||
500 | * will be invalid. Cannot be NULL | ||
501 | * @param cc_cls the closure for the cc | ||
502 | * @return handle to the host registration which can be used to cancel the | ||
503 | * registration; NULL if another registration handle is present and | ||
504 | * is not cancelled | ||
505 | */ | ||
506 | struct GNUNET_TESTBED_HostRegistrationHandle * | ||
507 | GNUNET_TESTBED_register_host (struct GNUNET_TESTBED_Controller *controller, | ||
508 | struct GNUNET_TESTBED_Host *host, | ||
509 | GNUNET_TESTBED_HostRegistrationCompletion cc, | ||
510 | void *cc_cls); | ||
511 | |||
512 | |||
513 | /** | ||
514 | * Cancel the pending registration. Note that the registration message will | ||
515 | * already be queued to be sent to the service, cancellation has only the | ||
516 | * effect that the registration completion callback for the registration is | ||
517 | * never called and from our perspective the host is not registered until the | ||
518 | * completion callback is called. | ||
519 | * | ||
520 | * @param handle the registration handle to cancel | ||
521 | */ | ||
522 | void | ||
523 | GNUNET_TESTBED_cancel_registration (struct GNUNET_TESTBED_HostRegistrationHandle | ||
524 | *handle); | ||
525 | |||
526 | |||
527 | /** | ||
528 | * Create a link from slave controller to delegated controller. Whenever the | ||
529 | * master controller is asked to start a peer at the delegated controller the | ||
530 | * request will be routed towards slave controller (if a route exists). The | ||
531 | * slave controller will then route it to the delegated controller. The | ||
532 | * configuration of the slave controller is given and to be used to either | ||
533 | * create the slave controller or to connect to an existing slave controller | ||
534 | * process. 'is_subordinate' specifies if the given slave controller should be | ||
535 | * started and managed by the master controller, or if the slave already has a | ||
536 | * master and this is just a secondary master that is also allowed to use the | ||
537 | * existing slave. | ||
538 | * | ||
539 | * @param master handle to the master controller who creates the association | ||
540 | * @param delegated_host requests to which host should be delegated; cannot be NULL | ||
541 | * @param slave_host which host is used to run the slave controller; use NULL to | ||
542 | * make the master controller connect to the delegated host | ||
543 | * @param slave_cfg configuration to use for the slave controller | ||
544 | * @param is_subordinate GNUNET_YES if the controller at delegated_host should | ||
545 | * be started by the master controller; GNUNET_NO if we are just | ||
546 | * allowed to use the slave via TCP/IP | ||
547 | * @return the operation handle | ||
548 | */ | ||
549 | struct GNUNET_TESTBED_Operation * | ||
550 | GNUNET_TESTBED_controller_link (struct GNUNET_TESTBED_Controller *master, | ||
551 | struct GNUNET_TESTBED_Host *delegated_host, | ||
552 | struct GNUNET_TESTBED_Host *slave_host, | ||
553 | const struct GNUNET_CONFIGURATION_Handle *slave_cfg, | ||
554 | int is_subordinate); | ||
555 | |||
556 | |||
557 | /** | ||
558 | * Same as the GNUNET_TESTBED_controller_link, however expects configuration in | ||
559 | * serialized and compressed | ||
560 | * | ||
561 | * @param master handle to the master controller who creates the association | ||
562 | * @param delegated_host requests to which host should be delegated; cannot be NULL | ||
563 | * @param slave_host which host is used to run the slave controller; use NULL to | ||
564 | * make the master controller connect to the delegated host | ||
565 | * @param sxcfg serialized and compressed configuration | ||
566 | * @param sxcfg_size the size scfg | ||
567 | * @param scfg_size the size of uncompressed serialized configuration | ||
568 | * @param is_subordinate GNUNET_YES if the controller at delegated_host should | ||
569 | * be started by the master controller; GNUNET_NO if we are just | ||
570 | * allowed to use the slave via TCP/IP | ||
571 | * @return the operation handle | ||
572 | */ | ||
573 | struct GNUNET_TESTBED_Operation * | ||
574 | GNUNET_TESTBED_controller_link_2 (struct GNUNET_TESTBED_Controller *master, | ||
575 | struct GNUNET_TESTBED_Host *delegated_host, | ||
576 | struct GNUNET_TESTBED_Host *slave_host, | ||
577 | const char *sxcfg, | ||
578 | size_t sxcfg_size, | ||
579 | size_t scfg_size, | ||
580 | int is_subordinate); | ||
581 | |||
582 | |||
583 | /** | ||
584 | * Functions of this signature are called when a peer has been successfully | ||
585 | * created | ||
586 | * | ||
587 | * @param cls the closure from GNUNET_TESTBED_peer_create() | ||
588 | * @param peer the handle for the created peer; NULL on any error during | ||
589 | * creation | ||
590 | * @param emsg NULL if peer is not NULL; else MAY contain the error description | ||
591 | */ | ||
592 | typedef void (*GNUNET_TESTBED_PeerCreateCallback) (void *cls, | ||
593 | struct GNUNET_TESTBED_Peer *peer, | ||
594 | const char *emsg); | ||
595 | |||
596 | |||
597 | /** | ||
598 | * Create the given peer at the specified host using the given | ||
599 | * controller. If the given controller is not running on the target | ||
600 | * host, it should find or create a controller at the target host and | ||
601 | * delegate creating the peer. Explicit delegation paths can be setup | ||
602 | * using 'GNUNET_TESTBED_controller_link'. If no explicit delegation | ||
603 | * path exists, a direct link with a subordinate controller is setup | ||
604 | * for the first delegated peer to a particular host; the subordinate | ||
605 | * controller is then destroyed once the last peer that was delegated | ||
606 | * to the remote host is stopped. | ||
607 | * | ||
608 | * Creating the peer only creates the handle to manipulate and further | ||
609 | * configure the peer; use "GNUNET_TESTBED_peer_start" and | ||
610 | * "GNUNET_TESTBED_peer_stop" to actually start/stop the peer's | ||
611 | * processes. | ||
612 | * | ||
613 | * Note that the given configuration will be adjusted by the | ||
614 | * controller to avoid port/path conflicts with other peers. | ||
615 | * The "final" configuration can be obtained using | ||
616 | * 'GNUNET_TESTBED_peer_get_information'. | ||
617 | * | ||
618 | * @param controller controller process to use | ||
619 | * @param host host to run the peer on | ||
620 | * @param cfg Template configuration to use for the peer. Should exist until | ||
621 | * operation is cancelled or GNUNET_TESTBED_operation_done() is called | ||
622 | * @param cb the callback to call when the peer has been created | ||
623 | * @param cls the closure to the above callback | ||
624 | * @return the operation handle | ||
625 | */ | ||
626 | struct GNUNET_TESTBED_Operation * | ||
627 | GNUNET_TESTBED_peer_create (struct GNUNET_TESTBED_Controller *controller, | ||
628 | struct GNUNET_TESTBED_Host *host, | ||
629 | const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
630 | GNUNET_TESTBED_PeerCreateCallback cb, | ||
631 | void *cls); | ||
632 | |||
633 | |||
634 | /** | ||
635 | * Start the given peer. | ||
636 | * | ||
637 | * @param peer peer to start | ||
638 | * @return handle to the operation | ||
639 | */ | ||
640 | struct GNUNET_TESTBED_Operation * | ||
641 | GNUNET_TESTBED_peer_start (struct GNUNET_TESTBED_Peer *peer); | ||
642 | |||
643 | |||
644 | /** | ||
645 | * Stop the given peer. The handle remains valid (use | ||
646 | * "GNUNET_TESTBED_peer_destroy" to fully clean up the | ||
647 | * state of the peer). | ||
648 | * | ||
649 | * @param peer peer to stop | ||
650 | * @return handle to the operation | ||
651 | */ | ||
652 | struct GNUNET_TESTBED_Operation * | ||
653 | GNUNET_TESTBED_peer_stop (struct GNUNET_TESTBED_Peer *peer); | ||
654 | |||
655 | |||
656 | /** | ||
657 | * Data returned from GNUNET_TESTBED_peer_get_information | ||
658 | */ | ||
659 | struct GNUNET_TESTBED_PeerInformation | ||
660 | { | ||
661 | /** | ||
662 | * Peer information type; captures which of the types | ||
663 | * in the 'op_result' is actually in use. | ||
664 | */ | ||
665 | enum GNUNET_TESTBED_PeerInformationType pit; | ||
666 | |||
667 | /** | ||
668 | * The result of the get information operation; Choose according to the pit | ||
669 | */ | ||
670 | union | ||
671 | { | ||
672 | /** | ||
673 | * The configuration of the peer | ||
674 | */ | ||
675 | struct GNUNET_CONFIGURATION_Handle *cfg; | ||
676 | |||
677 | /** | ||
678 | * The identity of the peer | ||
679 | */ | ||
680 | struct GNUNET_PeerIdentity *id; | ||
681 | |||
682 | /** | ||
683 | * The host where the peer is running | ||
684 | */ | ||
685 | struct GNUNET_TESTBED_Host *host; | ||
686 | } result; | ||
687 | }; | ||
688 | |||
689 | |||
690 | /** | ||
691 | * Callback to be called when the requested peer information is available | ||
692 | * | ||
693 | * @param cb_cls the closure from GNUNET_TETSBED_peer_get_information() | ||
694 | * @return | ||
695 | */ | ||
696 | typedef void (*GNUNET_TESTBED_PICallback) (void *cb_cls, | ||
697 | const struct | ||
698 | GNUNET_TESTBED_PeerInformation *pit); | ||
699 | |||
700 | |||
701 | |||
702 | /** | ||
703 | * Request information about a peer. The controller callback will be called with | ||
704 | * event type GNUNET_TESTBED_ET_OPERATION_FINISHED when result for this | ||
705 | * operation is available | ||
706 | * | ||
707 | * @param op_cls the closure for the operation | ||
708 | * @param peer peer to request information about | ||
709 | * @param pit desired information | ||
710 | * @param cb the convenience callback to be called when results for this | ||
711 | * operation are available | ||
712 | * @param cb_cls the closure for the above callback | ||
713 | * @return handle to the operation | ||
714 | */ | ||
715 | struct GNUNET_TESTBED_Operation * | ||
716 | GNUNET_TESTBED_peer_get_information (void *op_cls, | ||
717 | struct GNUNET_TESTBED_Peer *peer, | ||
718 | enum GNUNET_TESTBED_PeerInformationType | ||
719 | pit, | ||
720 | GNUNET_TESTBED_PICallback cb, | ||
721 | void *cb_cls); | ||
722 | |||
723 | |||
724 | /** | ||
725 | * Change peer configuration. Must only be called while the | ||
726 | * peer is stopped. Ports and paths cannot be changed this | ||
727 | * way. | ||
728 | * | ||
729 | * @param peer peer to change configuration for | ||
730 | * @param cfg new configuration (differences to existing | ||
731 | * configuration only) | ||
732 | * @return handle to the operation | ||
733 | */ | ||
734 | struct GNUNET_TESTBED_Operation * | ||
735 | GNUNET_TESTBED_peer_update_configuration (struct GNUNET_TESTBED_Peer *peer, | ||
736 | const struct GNUNET_CONFIGURATION_Handle *cfg); | ||
737 | |||
738 | |||
739 | /** | ||
740 | * Destroy the given peer; the peer should have been | ||
741 | * stopped first (if it was started). | ||
742 | * | ||
743 | * @param peer peer to stop | ||
744 | * @return handle to the operation | ||
745 | */ | ||
746 | struct GNUNET_TESTBED_Operation * | ||
747 | GNUNET_TESTBED_peer_destroy (struct GNUNET_TESTBED_Peer *peer); | ||
748 | |||
749 | |||
750 | /** | ||
751 | * Options for peer connections. | ||
752 | */ | ||
753 | enum GNUNET_TESTBED_ConnectOption | ||
754 | { | ||
755 | /** | ||
756 | * No option (not valid as an argument). | ||
757 | */ | ||
758 | GNUNET_TESTBED_CO_NONE = 0, | ||
759 | |||
760 | /** | ||
761 | * Allow or disallow a connection between the specified peers. | ||
762 | * Followed by GNUNET_NO (int) if a connection is disallowed | ||
763 | * or GNUNET_YES if a connection is allowed. Note that the | ||
764 | * default (all connections allowed or disallowed) is | ||
765 | * specified in the configuration of the controller. | ||
766 | */ | ||
767 | GNUNET_TESTBED_CO_ALLOW = 1, | ||
768 | |||
769 | /** | ||
770 | * FIXME: add (and implement) options to limit connection to | ||
771 | * particular transports, force simulation of particular latencies | ||
772 | * or message loss rates, or set bandwidth limitations. | ||
773 | */ | ||
774 | |||
775 | }; | ||
776 | |||
777 | |||
778 | /** | ||
779 | * Manipulate the P2P underlay topology by configuring a link | ||
780 | * between two peers. | ||
781 | * | ||
782 | * @param op_cls closure argument to give with the operation event | ||
783 | * @param p1 first peer | ||
784 | * @param p2 second peer | ||
785 | * @param co option to change | ||
786 | * @param ap option-specific values | ||
787 | * @return handle to the operation, NULL if configuring the link at this | ||
788 | * time is not allowed | ||
789 | */ | ||
790 | struct GNUNET_TESTBED_Operation * | ||
791 | GNUNET_TESTBED_underlay_configure_link_va (void *op_cls, | ||
792 | struct GNUNET_TESTBED_Peer *p1, | ||
793 | struct GNUNET_TESTBED_Peer *p2, | ||
794 | enum GNUNET_TESTBED_ConnectOption co, | ||
795 | va_list ap); | ||
796 | |||
797 | |||
798 | /** | ||
799 | * Manipulate the P2P underlay topology by configuring a link | ||
800 | * between two peers. | ||
801 | * | ||
802 | * @param op_cls closure argument to give with the operation event | ||
803 | * @param p1 first peer | ||
804 | * @param p2 second peer | ||
805 | * @param co option to change | ||
806 | * @param ... option-specific values | ||
807 | * @return handle to the operation, NULL if configuring the link at this | ||
808 | * time is not allowed | ||
809 | */ | ||
810 | struct GNUNET_TESTBED_Operation * | ||
811 | GNUNET_TESTBED_underlay_configure_link (void *op_cls, | ||
812 | struct GNUNET_TESTBED_Peer *p1, | ||
813 | struct GNUNET_TESTBED_Peer *p2, | ||
814 | enum GNUNET_TESTBED_ConnectOption co, ...); | ||
815 | |||
816 | |||
817 | |||
818 | /** | ||
819 | * Topologies supported for testbeds. | ||
820 | */ | ||
821 | enum GNUNET_TESTBED_TopologyOption | ||
822 | { | ||
823 | /** | ||
824 | * A clique (everyone connected to everyone else). No options. | ||
825 | */ | ||
826 | GNUNET_TESTBED_TOPOLOGY_CLIQUE, | ||
827 | |||
828 | /** | ||
829 | * Small-world network (2d torus plus random links). Followed | ||
830 | * by the number of random links to add (unsigned int). | ||
831 | */ | ||
832 | GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD, | ||
833 | |||
834 | /** | ||
835 | * Small-world network (ring plus random links). Followed | ||
836 | * by the number of random links to add (unsigned int). | ||
837 | */ | ||
838 | GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD_RING, | ||
839 | |||
840 | /** | ||
841 | * Ring topology. No options. | ||
842 | */ | ||
843 | GNUNET_TESTBED_TOPOLOGY_RING, | ||
844 | |||
845 | /** | ||
846 | * 2-d torus. No options. | ||
847 | */ | ||
848 | GNUNET_TESTBED_TOPOLOGY_2D_TORUS, | ||
849 | |||
850 | /** | ||
851 | * Random graph. Followed by the link density, that is the | ||
852 | * percentage of links present in relation to a clique | ||
853 | * (float). | ||
854 | */ | ||
855 | GNUNET_TESTBED_TOPOLOGY_ERDOS_RENYI, | ||
856 | |||
857 | /** | ||
858 | * Certain percentage of peers are unable to communicate directly | ||
859 | * replicating NAT conditions. Followed by the fraction of | ||
860 | * NAT'ed peers (float). | ||
861 | */ | ||
862 | GNUNET_TESTBED_TOPOLOGY_INTERNAT, | ||
863 | |||
864 | /** | ||
865 | * Scale free topology. FIXME: options? | ||
866 | */ | ||
867 | GNUNET_TESTBED_TOPOLOGY_SCALE_FREE, | ||
868 | |||
869 | /** | ||
870 | * Straight line topology. No options. | ||
871 | */ | ||
872 | GNUNET_TESTBED_TOPOLOGY_LINE, | ||
873 | |||
874 | /** | ||
875 | * All peers are disconnected. No options. | ||
876 | */ | ||
877 | GNUNET_TESTBED_TOPOLOGY_NONE, | ||
878 | |||
879 | /** | ||
880 | * Read a topology from a given file. Followed by the name of the file (const char *). | ||
881 | */ | ||
882 | GNUNET_TESTBED_TOPOLOGY_FROM_FILE | ||
883 | }; | ||
884 | |||
885 | |||
886 | /** | ||
887 | * Configure overall network topology to have a particular shape. | ||
888 | * | ||
889 | * @param op_cls closure argument to give with the operation event | ||
890 | * @param num_peers number of peers in 'peers' | ||
891 | * @param peers array of 'num_peers' with the peers to configure | ||
892 | * @param topo desired underlay topology to use | ||
893 | * @param ap topology-specific options | ||
894 | * @return handle to the operation, NULL if configuring the topology | ||
895 | * is not allowed at this time | ||
896 | */ | ||
897 | struct GNUNET_TESTBED_Operation * | ||
898 | GNUNET_TESTBED_underlay_configure_topology_va (void *op_cls, | ||
899 | unsigned int num_peers, | ||
900 | struct GNUNET_TESTBED_Peer **peers, | ||
901 | enum GNUNET_TESTBED_TopologyOption topo, | ||
902 | va_list ap); | ||
903 | |||
904 | |||
905 | /** | ||
906 | * Configure overall network topology to have a particular shape. | ||
907 | * | ||
908 | * @param op_cls closure argument to give with the operation event | ||
909 | * @param num_peers number of peers in 'peers' | ||
910 | * @param peers array of 'num_peers' with the peers to configure | ||
911 | * @param topo desired underlay topology to use | ||
912 | * @param ... topology-specific options | ||
913 | * @return handle to the operation, NULL if configuring the topology | ||
914 | * is not allowed at this time | ||
915 | */ | ||
916 | struct GNUNET_TESTBED_Operation * | ||
917 | GNUNET_TESTBED_underlay_configure_topology (void *op_cls, | ||
918 | unsigned int num_peers, | ||
919 | struct GNUNET_TESTBED_Peer **peers, | ||
920 | enum GNUNET_TESTBED_TopologyOption topo, | ||
921 | ...); | ||
922 | |||
923 | |||
924 | /** | ||
925 | * Callback to be called when an operation is completed | ||
926 | * | ||
927 | * @param cls the callback closure from functions generating an operation | ||
928 | * @param op the operation that has been finished | ||
929 | * @param emsg error message in case the operation has failed; will be NULL if | ||
930 | * operation has executed successfully. | ||
931 | */ | ||
932 | typedef void (*GNUNET_TESTBED_OperationCompletionCallback) (void *cls, | ||
933 | struct | ||
934 | GNUNET_TESTBED_Operation | ||
935 | *op, | ||
936 | const char *emsg); | ||
937 | |||
938 | |||
939 | /** | ||
940 | * Both peers must have been started before calling this function. | ||
941 | * This function then obtains a HELLO from 'p1', gives it to 'p2' | ||
942 | * and asks 'p2' to connect to 'p1'. | ||
943 | * | ||
944 | * @param op_cls closure argument to give with the operation event | ||
945 | * @param cb the callback to call when this operation has finished | ||
946 | * @param cb_cls the closure for the above callback | ||
947 | * @param p1 first peer | ||
948 | * @param p2 second peer | ||
949 | * @return handle to the operation, NULL if connecting these two | ||
950 | * peers is fundamentally not possible at this time (peers | ||
951 | * not running or underlay disallows) | ||
952 | */ | ||
953 | struct GNUNET_TESTBED_Operation * | ||
954 | GNUNET_TESTBED_overlay_connect (void *op_cls, | ||
955 | GNUNET_TESTBED_OperationCompletionCallback cb, | ||
956 | void *cb_cls, | ||
957 | struct GNUNET_TESTBED_Peer *p1, | ||
958 | struct GNUNET_TESTBED_Peer *p2); | ||
959 | |||
960 | |||
961 | /** | ||
962 | * All peers must have been started before calling this function. | ||
963 | * This function then connects the given peers in the P2P overlay | ||
964 | * using the given topology. | ||
965 | * | ||
966 | * @param op_cls closure argument to give with the operation event | ||
967 | * @param num_peers number of peers in 'peers' | ||
968 | * @param peers array of 'num_peers' with the peers to configure | ||
969 | * @param topo desired underlay topology to use | ||
970 | * @param va topology-specific options | ||
971 | * @return handle to the operation, NULL if connecting these | ||
972 | * peers is fundamentally not possible at this time (peers | ||
973 | * not running or underlay disallows) | ||
974 | */ | ||
975 | struct GNUNET_TESTBED_Operation * | ||
976 | GNUNET_TESTBED_overlay_configure_topology_va (void *op_cls, | ||
977 | unsigned int num_peers, | ||
978 | struct GNUNET_TESTBED_Peer *peers, | ||
979 | enum GNUNET_TESTBED_TopologyOption topo, | ||
980 | va_list va); | ||
981 | |||
982 | |||
983 | /** | ||
984 | * All peers must have been started before calling this function. | ||
985 | * This function then connects the given peers in the P2P overlay | ||
986 | * using the given topology. | ||
987 | * | ||
988 | * @param op_cls closure argument to give with the operation event | ||
989 | * @param num_peers number of peers in 'peers' | ||
990 | * @param peers array of 'num_peers' with the peers to configure | ||
991 | * @param topo desired underlay topology to use | ||
992 | * @param ... topology-specific options | ||
993 | * @return handle to the operation, NULL if connecting these | ||
994 | * peers is fundamentally not possible at this time (peers | ||
995 | * not running or underlay disallows) | ||
996 | */ | ||
997 | struct GNUNET_TESTBED_Operation * | ||
998 | GNUNET_TESTBED_overlay_configure_topology (void *op_cls, | ||
999 | unsigned int num_peers, | ||
1000 | struct GNUNET_TESTBED_Peer *peers, | ||
1001 | enum GNUNET_TESTBED_TopologyOption topo, | ||
1002 | ...); | ||
1003 | |||
1004 | |||
1005 | /** | ||
1006 | * Ask the testbed controller to write the current overlay topology to | ||
1007 | * a file. Naturally, the file will only contain a snapshot as the | ||
1008 | * topology may evolve all the time. | ||
1009 | * | ||
1010 | * @param controller overlay controller to inspect | ||
1011 | * @param filename name of the file the topology should | ||
1012 | * be written to. | ||
1013 | */ | ||
1014 | void | ||
1015 | GNUNET_TESTBED_overlay_write_topology_to_file (struct GNUNET_TESTBED_Controller *controller, | ||
1016 | const char *filename); | ||
1017 | |||
1018 | |||
1019 | /** | ||
1020 | * Adapter function called to establish a connection to | ||
1021 | * a service. | ||
1022 | * | ||
1023 | * @param cls closure | ||
1024 | * @param cfg configuration of the peer to connect to; will be available until | ||
1025 | * GNUNET_TESTBED_operation_done() is called on the operation returned | ||
1026 | * from GNUNET_TESTBED_service_connect() | ||
1027 | * @return service handle to return in 'op_result', NULL on error | ||
1028 | */ | ||
1029 | typedef void * (*GNUNET_TESTBED_ConnectAdapter)(void *cls, | ||
1030 | const struct GNUNET_CONFIGURATION_Handle *cfg); | ||
1031 | |||
1032 | |||
1033 | /** | ||
1034 | * Adapter function called to destroy a connection to | ||
1035 | * a service. | ||
1036 | * | ||
1037 | * @param cls closure | ||
1038 | * @param op_result service handle returned from the connect adapter | ||
1039 | */ | ||
1040 | typedef void (*GNUNET_TESTBED_DisconnectAdapter)(void *cls, | ||
1041 | void *op_result); | ||
1042 | |||
1043 | |||
1044 | /** | ||
1045 | * Connect to a service offered by the given peer. Will ensure that | ||
1046 | * the request is queued to not overwhelm our ability to create and | ||
1047 | * maintain connections with other systems. The actual service | ||
1048 | * handle is then returned via the 'op_result' member in the event | ||
1049 | * callback. The 'ca' callback is used to create the connection | ||
1050 | * when the time is right; the 'da' callback will be used to | ||
1051 | * destroy the connection (upon 'GNUNET_TESTBED_operation_done'). | ||
1052 | * 'GNUNET_TESTBED_operation_cancel' can be used to abort this | ||
1053 | * operation until the event callback has been called. | ||
1054 | * | ||
1055 | * @param op_cls closure to pass in operation event | ||
1056 | * @param peer peer that runs the service | ||
1057 | * @param service_name name of the service to connect to | ||
1058 | * @param cb the callback to call when this operation finishes | ||
1059 | * @param cb_cls closure for the above callback | ||
1060 | * @param ca helper function to establish the connection | ||
1061 | * @param da helper function to close the connection | ||
1062 | * @param cada_cls closure for ca and da | ||
1063 | * @return handle for the operation | ||
1064 | */ | ||
1065 | struct GNUNET_TESTBED_Operation * | ||
1066 | GNUNET_TESTBED_service_connect (void *op_cls, | ||
1067 | struct GNUNET_TESTBED_Peer *peer, | ||
1068 | const char *service_name, | ||
1069 | GNUNET_TESTBED_OperationCompletionCallback cb, | ||
1070 | void *cb_cls, | ||
1071 | GNUNET_TESTBED_ConnectAdapter ca, | ||
1072 | GNUNET_TESTBED_DisconnectAdapter da, | ||
1073 | void *cada_cls); | ||
1074 | |||
1075 | |||
1076 | /** | ||
1077 | * Cancel a pending operation. Releases all resources | ||
1078 | * of the operation and will ensure that no event | ||
1079 | * is generated for the operation. Does NOT guarantee | ||
1080 | * that the operation will be fully undone (or that | ||
1081 | * nothing ever happened). | ||
1082 | * | ||
1083 | * @param operation operation to cancel | ||
1084 | */ | ||
1085 | void | ||
1086 | GNUNET_TESTBED_operation_cancel (struct GNUNET_TESTBED_Operation *operation); | ||
1087 | |||
1088 | |||
1089 | /** | ||
1090 | * Signal that the information from an operation has been fully | ||
1091 | * processed. This function MUST be called for each event | ||
1092 | * of type 'operation_finished' to fully remove the operation | ||
1093 | * from the operation queue. After calling this function, the | ||
1094 | * 'op_result' becomes invalid (!). | ||
1095 | * | ||
1096 | * @param operation operation to signal completion for | ||
1097 | */ | ||
1098 | void | ||
1099 | GNUNET_TESTBED_operation_done (struct GNUNET_TESTBED_Operation *operation); | ||
1100 | |||
1101 | |||
1102 | /** | ||
1103 | * Configure and run a testbed using the given | ||
1104 | * master controller on 'num_hosts' starting | ||
1105 | * 'num_peers' using the given peer configuration. | ||
1106 | * | ||
1107 | * @param controller master controller for the testbed | ||
1108 | * (must not be destroyed until after the | ||
1109 | * testbed is destroyed). | ||
1110 | * @param num_hosts number of hosts in 'hosts', 0 to only | ||
1111 | * use 'localhost' | ||
1112 | * @param hosts list of hosts to use for the testbed | ||
1113 | * @param num_peers number of peers to start | ||
1114 | * @param peer_cfg peer configuration template to use | ||
1115 | * @param underlay_topology underlay topology to create | ||
1116 | * @param va topology-specific options | ||
1117 | * @return handle to the testbed | ||
1118 | */ | ||
1119 | struct GNUNET_TESTBED_Testbed * | ||
1120 | GNUNET_TESTBED_create_va (struct GNUNET_TESTBED_Controller *controller, | ||
1121 | unsigned int num_hosts, | ||
1122 | struct GNUNET_TESTBED_Host **hosts, | ||
1123 | unsigned int num_peers, | ||
1124 | const struct GNUNET_CONFIGURATION_Handle *peer_cfg, | ||
1125 | enum GNUNET_TESTBED_TopologyOption underlay_topology, | ||
1126 | va_list va); | ||
1127 | |||
1128 | |||
1129 | /** | ||
1130 | * Configure and run a testbed using the given | ||
1131 | * master controller on 'num_hosts' starting | ||
1132 | * 'num_peers' using the given peer configuration. | ||
1133 | * | ||
1134 | * @param controller master controller for the testbed | ||
1135 | * (must not be destroyed until after the | ||
1136 | * testbed is destroyed). | ||
1137 | * @param num_hosts number of hosts in 'hosts', 0 to only | ||
1138 | * use 'localhost' | ||
1139 | * @param hosts list of hosts to use for the testbed | ||
1140 | * @param num_peers number of peers to start | ||
1141 | * @param peer_cfg peer configuration template to use | ||
1142 | * @param underlay_topology underlay topology to create | ||
1143 | * @param ... topology-specific options | ||
1144 | */ | ||
1145 | struct GNUNET_TESTBED_Testbed * | ||
1146 | GNUNET_TESTBED_create (struct GNUNET_TESTBED_Controller *controller, | ||
1147 | unsigned int num_hosts, | ||
1148 | struct GNUNET_TESTBED_Host **hosts, | ||
1149 | unsigned int num_peers, | ||
1150 | const struct GNUNET_CONFIGURATION_Handle *peer_cfg, | ||
1151 | enum GNUNET_TESTBED_TopologyOption underlay_topology, | ||
1152 | ...); | ||
1153 | |||
1154 | |||
1155 | /** | ||
1156 | * Destroy a testbed. Stops all running peers and then | ||
1157 | * destroys all peers. Does NOT destroy the master controller. | ||
1158 | * | ||
1159 | * @param testbed testbed to destroy | ||
1160 | */ | ||
1161 | void | ||
1162 | GNUNET_TESTBED_destroy (struct GNUNET_TESTBED_Testbed *testbed); | ||
1163 | |||
1164 | |||
1165 | /** | ||
1166 | * Convenience method for running a testbed with | ||
1167 | * a single call. Underlay and overlay topology | ||
1168 | * are configured using the "UNDERLAY" and "OVERLAY" | ||
1169 | * options in the "[testbed]" section of the configuration\ | ||
1170 | * (with possible options given in "UNDERLAY_XXX" and/or | ||
1171 | * "OVERLAY_XXX"). | ||
1172 | * | ||
1173 | * The testbed is to be terminated using a call to | ||
1174 | * "GNUNET_SCHEDULER_shutdown". | ||
1175 | * | ||
1176 | * @param host_filename name of the file with the 'hosts', NULL | ||
1177 | * to run everything on 'localhost' | ||
1178 | * @param cfg configuration to use (for testbed, controller and peers) | ||
1179 | * @param num_peers number of peers to start; FIXME: maybe put that ALSO into | ||
1180 | * cfg?; should be greater than 0 | ||
1181 | * @param event_mask bit mask with set of events to call 'cc' for; | ||
1182 | * or-ed values of "1LL" shifted by the | ||
1183 | * respective 'enum GNUNET_TESTBED_EventType' | ||
1184 | * (i.e. "(1LL << GNUNET_TESTBED_ET_CONNECT) || ...") | ||
1185 | * @param cc controller callback to invoke on events; This callback is called | ||
1186 | * for all peer start events even if GNUNET_TESTBED_ET_PEER_START isn't | ||
1187 | * set in the event_mask as this is the only way get access to the | ||
1188 | * handle of each peer | ||
1189 | * @param cc_cls closure for cc | ||
1190 | * @param master task to run once the testbed is ready | ||
1191 | * @param master_cls closure for 'task'. | ||
1192 | */ | ||
1193 | void | ||
1194 | GNUNET_TESTBED_run (const char *host_filename, | ||
1195 | const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
1196 | unsigned int num_peers, | ||
1197 | uint64_t event_mask, | ||
1198 | GNUNET_TESTBED_ControllerCallback cc, | ||
1199 | void *cc_cls, | ||
1200 | GNUNET_SCHEDULER_Task master, | ||
1201 | void *master_cls); | ||
1202 | |||
1203 | |||
1204 | /** | ||
1205 | * Signature of a main function for a testcase. | ||
1206 | * | ||
1207 | * @param cls closure | ||
1208 | * @param num_peers number of peers in 'peers' | ||
1209 | * @param peers handle to peers run in the testbed | ||
1210 | */ | ||
1211 | typedef void (*GNUNET_TESTBED_TestMaster)(void *cls, | ||
1212 | unsigned int num_peers, | ||
1213 | struct GNUNET_TESTBED_Peer **peers); | ||
1214 | |||
1215 | |||
1216 | /** | ||
1217 | * Convenience method for running a "simple" test on the local system | ||
1218 | * with a single call from 'main'. Underlay and overlay topology are | ||
1219 | * configured using the "UNDERLAY" and "OVERLAY" options in the | ||
1220 | * "[testbed]" section of the configuration (with possible options | ||
1221 | * given in "UNDERLAY_XXX" and/or "OVERLAY_XXX"). | ||
1222 | * | ||
1223 | * The test is to be terminated using a call to | ||
1224 | * "GNUNET_SCHEDULER_shutdown". If starting the test fails, | ||
1225 | * the program is stopped without 'master' ever being run. | ||
1226 | * | ||
1227 | * NOTE: this function should be called from 'main', NOT from | ||
1228 | * within a GNUNET_SCHEDULER-loop. This function will initialze | ||
1229 | * the scheduler loop, the testbed and then pass control to | ||
1230 | * 'master'. | ||
1231 | * | ||
1232 | * @param testname name of the testcase (to configure logging, etc.) | ||
1233 | * @param cfg_filename configuration filename to use | ||
1234 | * (for testbed, controller and peers) | ||
1235 | * @param num_peers number of peers to start; should be greter than 0 | ||
1236 | * @param event_mask bit mask with set of events to call 'cc' for; | ||
1237 | * or-ed values of "1LL" shifted by the | ||
1238 | * respective 'enum GNUNET_TESTBED_EventType' | ||
1239 | * (i.e. "(1LL << GNUNET_TESTBED_ET_CONNECT) || ...") | ||
1240 | * @param cc controller callback to invoke on events; This callback is called | ||
1241 | * for all peer start events even if GNUNET_TESTBED_ET_PEER_START isn't | ||
1242 | * set in the event_mask as this is the only way get access to the | ||
1243 | * handle of each peer | ||
1244 | * @param cc_cls closure for cc | ||
1245 | * @param test_master task to run once the test is ready | ||
1246 | * @param test_master_cls closure for 'task'. | ||
1247 | */ | ||
1248 | void | ||
1249 | GNUNET_TESTBED_test_run (const char *testname, | ||
1250 | const char *cfg_filename, | ||
1251 | unsigned int num_peers, | ||
1252 | uint64_t event_mask, | ||
1253 | GNUNET_TESTBED_ControllerCallback cc, | ||
1254 | void *cc_cls, | ||
1255 | GNUNET_TESTBED_TestMaster test_master, | ||
1256 | void *test_master_cls); | ||
1257 | |||
1258 | |||
1259 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
1260 | { | ||
1261 | #endif | ||
1262 | |||
1263 | |||
1264 | #ifdef __cplusplus | ||
1265 | } | ||
1266 | #endif | ||
1267 | |||
1268 | #endif | ||
diff --git a/src/include/gnunet_testbed_service.h b/src/include/gnunet_testbed_service.h index 1be35c098..249b40752 100644 --- a/src/include/gnunet_testbed_service.h +++ b/src/include/gnunet_testbed_service.h | |||
@@ -309,41 +309,11 @@ struct GNUNET_TESTBED_EventInformation | |||
309 | const char *emsg; | 309 | const char *emsg; |
310 | 310 | ||
311 | /** | 311 | /** |
312 | * Peer information type; captures which of the types | 312 | * No result (NULL pointer) or generic result |
313 | * in the 'op_result' is actually in use. | 313 | * (whatever the GNUNET_TESTBED_ConnectAdapter returned). |
314 | */ | 314 | */ |
315 | enum GNUNET_TESTBED_PeerInformationType pit; | 315 | void *generic; |
316 | 316 | ||
317 | /** | ||
318 | * Pointer to an operation-specific return value; NULL on error; | ||
319 | * can be NULL for certain operations. Valid until | ||
320 | * 'GNUNET_TESTBED_operation_done' is called. | ||
321 | */ | ||
322 | union | ||
323 | { | ||
324 | /** | ||
325 | * No result (NULL pointer) or generic result | ||
326 | * (whatever the GNUNET_TESTBED_ConnectAdapter returned). | ||
327 | */ | ||
328 | void *generic; | ||
329 | |||
330 | /** | ||
331 | * Identity of host running the peer. | ||
332 | */ | ||
333 | struct GNUNET_TESTBED_Host *host; | ||
334 | |||
335 | /** | ||
336 | * Identity of the peer. | ||
337 | */ | ||
338 | const struct GNUNET_PeerIdentity *pid; | ||
339 | |||
340 | /** | ||
341 | * Configuration of the peer. | ||
342 | */ | ||
343 | const struct GNUNET_CONFIGURATION_Handle *cfg; | ||
344 | |||
345 | } op_result; | ||
346 | |||
347 | } operation_finished; | 317 | } operation_finished; |
348 | 318 | ||
349 | 319 | ||
@@ -555,6 +525,21 @@ GNUNET_TESTBED_cancel_registration (struct GNUNET_TESTBED_HostRegistrationHandle | |||
555 | 525 | ||
556 | 526 | ||
557 | /** | 527 | /** |
528 | * Callback to be called when an operation is completed | ||
529 | * | ||
530 | * @param cls the callback closure from functions generating an operation | ||
531 | * @param op the operation that has been finished | ||
532 | * @param emsg error message in case the operation has failed; will be NULL if | ||
533 | * operation has executed successfully. | ||
534 | */ | ||
535 | typedef void (*GNUNET_TESTBED_OperationCompletionCallback) (void *cls, | ||
536 | struct | ||
537 | GNUNET_TESTBED_Operation | ||
538 | *op, | ||
539 | const char *emsg); | ||
540 | |||
541 | |||
542 | /** | ||
558 | * Create a link from slave controller to delegated controller. Whenever the | 543 | * Create a link from slave controller to delegated controller. Whenever the |
559 | * master controller is asked to start a peer at the delegated controller the | 544 | * master controller is asked to start a peer at the delegated controller the |
560 | * request will be routed towards slave controller (if a route exists). The | 545 | * request will be routed towards slave controller (if a route exists). The |
@@ -684,15 +669,70 @@ GNUNET_TESTBED_peer_stop (struct GNUNET_TESTBED_Peer *peer); | |||
684 | 669 | ||
685 | 670 | ||
686 | /** | 671 | /** |
687 | * Request information about a peer. | 672 | * Data returned from GNUNET_TESTBED_peer_get_information |
673 | */ | ||
674 | struct GNUNET_TESTBED_PeerInformation | ||
675 | { | ||
676 | /** | ||
677 | * Peer information type; captures which of the types | ||
678 | * in the 'op_result' is actually in use. | ||
679 | */ | ||
680 | enum GNUNET_TESTBED_PeerInformationType pit; | ||
681 | |||
682 | /** | ||
683 | * The result of the get information operation; Choose according to the pit | ||
684 | */ | ||
685 | union | ||
686 | { | ||
687 | /** | ||
688 | * The configuration of the peer | ||
689 | */ | ||
690 | struct GNUNET_CONFIGURATION_Handle *cfg; | ||
691 | |||
692 | /** | ||
693 | * The identity of the peer | ||
694 | */ | ||
695 | struct GNUNET_PeerIdentity *id; | ||
696 | } result; | ||
697 | }; | ||
698 | |||
699 | |||
700 | /** | ||
701 | * Callback to be called when the requested peer information is available | ||
702 | * | ||
703 | * @param cb_cls the closure from GNUNET_TETSBED_peer_get_information() | ||
704 | * @param op the operation this callback corresponds to | ||
705 | * @param pinfo the result; will be NULL if the operation has failed | ||
706 | * @param emsg error message if the operation has failed; will be NULL if the | ||
707 | * operation is successfull | ||
708 | */ | ||
709 | typedef void (*GNUNET_TESTBED_PeerInfoCallback) (void *cb_cls, | ||
710 | struct GNUNET_TESTBED_Operation | ||
711 | *op, | ||
712 | const struct | ||
713 | GNUNET_TESTBED_PeerInformation | ||
714 | *pinfo, | ||
715 | const char *emsg); | ||
716 | |||
717 | |||
718 | /** | ||
719 | * Request information about a peer. The controller callback will be called with | ||
720 | * event type GNUNET_TESTBED_ET_OPERATION_FINISHED when result for this | ||
721 | * operation is available | ||
688 | * | 722 | * |
689 | * @param peer peer to request information about | 723 | * @param peer peer to request information about |
690 | * @param pit desired information | 724 | * @param pit desired information |
725 | * @param cb the convenience callback to be called when results for this | ||
726 | * operation are available | ||
727 | * @param cb_cls the closure for the above callback | ||
691 | * @return handle to the operation | 728 | * @return handle to the operation |
692 | */ | 729 | */ |
693 | struct GNUNET_TESTBED_Operation * | 730 | struct GNUNET_TESTBED_Operation * |
694 | GNUNET_TESTBED_peer_get_information (struct GNUNET_TESTBED_Peer *peer, | 731 | GNUNET_TESTBED_peer_get_information (struct GNUNET_TESTBED_Peer *peer, |
695 | enum GNUNET_TESTBED_PeerInformationType pit); | 732 | enum GNUNET_TESTBED_PeerInformationType |
733 | pit, | ||
734 | GNUNET_TESTBED_PeerInfoCallback cb, | ||
735 | void *cb_cls); | ||
696 | 736 | ||
697 | 737 | ||
698 | /** | 738 | /** |
@@ -901,6 +941,8 @@ GNUNET_TESTBED_underlay_configure_topology (void *op_cls, | |||
901 | * and asks 'p2' to connect to 'p1'. | 941 | * and asks 'p2' to connect to 'p1'. |
902 | * | 942 | * |
903 | * @param op_cls closure argument to give with the operation event | 943 | * @param op_cls closure argument to give with the operation event |
944 | * @param cb the callback to call when this operation has finished | ||
945 | * @param cb_cls the closure for the above callback | ||
904 | * @param p1 first peer | 946 | * @param p1 first peer |
905 | * @param p2 second peer | 947 | * @param p2 second peer |
906 | * @return handle to the operation, NULL if connecting these two | 948 | * @return handle to the operation, NULL if connecting these two |
@@ -909,6 +951,8 @@ GNUNET_TESTBED_underlay_configure_topology (void *op_cls, | |||
909 | */ | 951 | */ |
910 | struct GNUNET_TESTBED_Operation * | 952 | struct GNUNET_TESTBED_Operation * |
911 | GNUNET_TESTBED_overlay_connect (void *op_cls, | 953 | GNUNET_TESTBED_overlay_connect (void *op_cls, |
954 | GNUNET_TESTBED_OperationCompletionCallback cb, | ||
955 | void *cb_cls, | ||
912 | struct GNUNET_TESTBED_Peer *p1, | 956 | struct GNUNET_TESTBED_Peer *p1, |
913 | struct GNUNET_TESTBED_Peer *p2); | 957 | struct GNUNET_TESTBED_Peer *p2); |
914 | 958 | ||
@@ -1010,6 +1054,8 @@ typedef void (*GNUNET_TESTBED_DisconnectAdapter)(void *cls, | |||
1010 | * @param op_cls closure to pass in operation event | 1054 | * @param op_cls closure to pass in operation event |
1011 | * @param peer peer that runs the service | 1055 | * @param peer peer that runs the service |
1012 | * @param service_name name of the service to connect to | 1056 | * @param service_name name of the service to connect to |
1057 | * @param cb the callback to call when this operation finishes | ||
1058 | * @param cb_cls closure for the above callback | ||
1013 | * @param ca helper function to establish the connection | 1059 | * @param ca helper function to establish the connection |
1014 | * @param da helper function to close the connection | 1060 | * @param da helper function to close the connection |
1015 | * @param cada_cls closure for ca and da | 1061 | * @param cada_cls closure for ca and da |
@@ -1019,6 +1065,8 @@ struct GNUNET_TESTBED_Operation * | |||
1019 | GNUNET_TESTBED_service_connect (void *op_cls, | 1065 | GNUNET_TESTBED_service_connect (void *op_cls, |
1020 | struct GNUNET_TESTBED_Peer *peer, | 1066 | struct GNUNET_TESTBED_Peer *peer, |
1021 | const char *service_name, | 1067 | const char *service_name, |
1068 | GNUNET_TESTBED_OperationCompletionCallback cb, | ||
1069 | void *cb_cls, | ||
1022 | GNUNET_TESTBED_ConnectAdapter ca, | 1070 | GNUNET_TESTBED_ConnectAdapter ca, |
1023 | GNUNET_TESTBED_DisconnectAdapter da, | 1071 | GNUNET_TESTBED_DisconnectAdapter da, |
1024 | void *cada_cls); | 1072 | void *cada_cls); |