diff options
Diffstat (limited to 'src/include/gnunet_testbed_service.h')
-rw-r--r-- | src/include/gnunet_testbed_service.h | 1747 |
1 files changed, 0 insertions, 1747 deletions
diff --git a/src/include/gnunet_testbed_service.h b/src/include/gnunet_testbed_service.h deleted file mode 100644 index acb444de4..000000000 --- a/src/include/gnunet_testbed_service.h +++ /dev/null | |||
@@ -1,1747 +0,0 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet | ||
3 | Copyright (C) 2008--2013 GNUnet e.V. | ||
4 | |||
5 | GNUnet is free software: you can redistribute it and/or modify it | ||
6 | under the terms of the GNU Affero General Public License as published | ||
7 | by the Free Software Foundation, either version 3 of the License, | ||
8 | or (at your option) any later version. | ||
9 | |||
10 | GNUnet is distributed in the hope that it will be useful, but | ||
11 | WITHOUT ANY WARRANTY; without even the implied warranty of | ||
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
13 | Affero General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU Affero General Public License | ||
16 | along with this program. If not, see <http://www.gnu.org/licenses/>. | ||
17 | |||
18 | SPDX-License-Identifier: AGPL3.0-or-later | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @author Christian Grothoff | ||
23 | * | ||
24 | * @file | ||
25 | * API for writing tests and creating large-scale emulation testbeds for GNUnet. | ||
26 | * | ||
27 | * @defgroup testbed Testbed service | ||
28 | * Writing tests and creating large-scale emulation testbeds for GNUnet. | ||
29 | * | ||
30 | * @see [Documentation](https://docs.gnunet.org/handbook/gnunet.html#TESTBED-Subsystem) | ||
31 | * | ||
32 | * @{ | ||
33 | */ | ||
34 | |||
35 | #ifndef GNUNET_TESTBED_SERVICE_H | ||
36 | #define GNUNET_TESTBED_SERVICE_H | ||
37 | |||
38 | #include "gnunet_util_lib.h" | ||
39 | #include "gnunet_testing_lib.h" | ||
40 | |||
41 | #ifdef __cplusplus | ||
42 | extern "C" | ||
43 | { | ||
44 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
45 | } | ||
46 | #endif | ||
47 | #endif | ||
48 | |||
49 | |||
50 | /** | ||
51 | * Opaque handle to a host running experiments managed by the testbed framework. | ||
52 | * The master process must be able to SSH to this host without password (via | ||
53 | * ssh-agent). | ||
54 | */ | ||
55 | struct GNUNET_TESTBED_Host; | ||
56 | |||
57 | /** | ||
58 | * Opaque handle to a peer controlled by the testbed framework. A peer runs | ||
59 | * at a particular host. | ||
60 | */ | ||
61 | struct GNUNET_TESTBED_Peer; | ||
62 | |||
63 | /** | ||
64 | * Opaque handle to an abstract operation to be executed by the testbed framework. | ||
65 | */ | ||
66 | struct GNUNET_TESTBED_Operation; | ||
67 | |||
68 | /** | ||
69 | * Handle to interact with a GNUnet testbed controller. Each | ||
70 | * controller has at least one master handle which is created when the | ||
71 | * controller is created; this master handle interacts with the | ||
72 | * controller process, destroying it destroys the controller (by | ||
73 | * closing stdin of the controller process). Additionally, | ||
74 | * controllers can interact with each other (in a P2P fashion); those | ||
75 | * links are established via TCP/IP on the controller's service port. | ||
76 | */ | ||
77 | struct GNUNET_TESTBED_Controller; | ||
78 | |||
79 | |||
80 | /** | ||
81 | * Create a host to run peers and controllers on. | ||
82 | * | ||
83 | * @param hostname name of the host, use "NULL" for localhost | ||
84 | * @param username username to use for the login; may be NULL | ||
85 | * @param cfg the configuration to use as a template while starting a controller | ||
86 | * on this host. Operation queue sizes specific to a host are also | ||
87 | * read from this configuration handle | ||
88 | * @param port port number to use for ssh; use 0 to let ssh decide | ||
89 | * @return handle to the host, NULL on error | ||
90 | */ | ||
91 | struct GNUNET_TESTBED_Host * | ||
92 | GNUNET_TESTBED_host_create (const char *hostname, | ||
93 | const char *username, | ||
94 | const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
95 | uint16_t port); | ||
96 | |||
97 | |||
98 | /** | ||
99 | * Create a host to run peers and controllers on. This function is used | ||
100 | * if a peer learns about a host via IPC between controllers (and thus | ||
101 | * some higher-level controller has already determined the unique IDs). | ||
102 | * | ||
103 | * @param id global host ID assigned to the host; 0 is | ||
104 | * reserved to always mean 'localhost' | ||
105 | * @param hostname name of the host, use "NULL" for localhost | ||
106 | * @param username username to use for the login; may be NULL | ||
107 | * @param cfg the configuration to use as a template while starting a controller | ||
108 | * on this host. Operation queue sizes specific to a host are also | ||
109 | * read from this configuration handle | ||
110 | * @param port port number to use for ssh; use 0 to let ssh decide | ||
111 | * @return handle to the host, NULL on error | ||
112 | */ | ||
113 | struct GNUNET_TESTBED_Host * | ||
114 | GNUNET_TESTBED_host_create_with_id (uint32_t id, | ||
115 | const char *hostname, | ||
116 | const char *username, | ||
117 | const struct GNUNET_CONFIGURATION_Handle | ||
118 | *cfg, | ||
119 | uint16_t port); | ||
120 | |||
121 | |||
122 | /** | ||
123 | * Load a set of hosts from a configuration file. The hostfile format is | ||
124 | * specified at https://gnunet.org/content/hosts-file-format | ||
125 | * | ||
126 | * @param filename file with the host specification | ||
127 | * @param cfg the configuration to use as a template while starting a controller | ||
128 | * on any of the loaded hosts. Operation queue sizes specific to a host | ||
129 | * are also read from this configuration handle | ||
130 | * @param hosts set to the hosts found in the file; caller must free this if | ||
131 | * number of hosts returned is greater than 0 | ||
132 | * @return number of hosts returned in 'hosts', 0 on error | ||
133 | */ | ||
134 | unsigned int | ||
135 | GNUNET_TESTBED_hosts_load_from_file (const char *filename, | ||
136 | const struct GNUNET_CONFIGURATION_Handle | ||
137 | *cfg, | ||
138 | struct GNUNET_TESTBED_Host ***hosts); | ||
139 | |||
140 | |||
141 | /** | ||
142 | * Loads the set of host allocated by the LoadLeveler Job Scheduler. This | ||
143 | * function is only available when compiled with support for LoadLeveler and is | ||
144 | * used for running on the SuperMUC | ||
145 | * | ||
146 | * @param cfg the configuration to use as a template while starting a controller | ||
147 | * on any of the loaded hosts. Operation queue sizes specific to a host | ||
148 | * are also read from this configuration handle | ||
149 | * @param hosts set to the hosts found in the file; caller must free this if | ||
150 | * number of hosts returned is greater than 0 | ||
151 | * @return number of hosts returned in 'hosts', 0 on error | ||
152 | */ | ||
153 | unsigned int | ||
154 | GNUNET_TESTBED_hosts_load_from_loadleveler (const struct | ||
155 | GNUNET_CONFIGURATION_Handle *cfg, | ||
156 | struct GNUNET_TESTBED_Host | ||
157 | ***hosts); | ||
158 | |||
159 | /** | ||
160 | * Destroy a host handle. Must only be called once everything | ||
161 | * running on that host has been stopped. | ||
162 | * | ||
163 | * @param host handle to destroy | ||
164 | */ | ||
165 | void | ||
166 | GNUNET_TESTBED_host_destroy (struct GNUNET_TESTBED_Host *host); | ||
167 | |||
168 | |||
169 | /** | ||
170 | * The handle for whether a host is habitable or not | ||
171 | */ | ||
172 | struct GNUNET_TESTBED_HostHabitableCheckHandle; | ||
173 | |||
174 | |||
175 | /** | ||
176 | * Callbacks of this type are called by GNUNET_TESTBED_is_host_habitable to | ||
177 | * inform whether the given host is habitable or not. The Handle returned by | ||
178 | * GNUNET_TESTBED_is_host_habitable() is invalid after this callback is called | ||
179 | * | ||
180 | * @param cls the closure given to GNUNET_TESTBED_is_host_habitable() | ||
181 | * @param host the host whose status is being reported; will be NULL if the host | ||
182 | * given to GNUNET_TESTBED_is_host_habitable() is NULL | ||
183 | * @param status GNUNET_YES if it is habitable; GNUNET_NO if not | ||
184 | */ | ||
185 | typedef void | ||
186 | (*GNUNET_TESTBED_HostHabitableCallback) (void *cls, | ||
187 | const struct GNUNET_TESTBED_Host *host, | ||
188 | int status); | ||
189 | |||
190 | |||
191 | /** | ||
192 | * Checks whether a host can be used to start testbed service | ||
193 | * | ||
194 | * @param host the host to check | ||
195 | * @param config the configuration handle to lookup the path of the testbed | ||
196 | * helper | ||
197 | * @param cb the callback to call to inform about habitability of the given host | ||
198 | * @param cb_cls the closure for the callback | ||
199 | * @return NULL upon any error or a handle which can be passed to | ||
200 | * GNUNET_TESTBED_is_host_habitable_cancel() | ||
201 | */ | ||
202 | struct GNUNET_TESTBED_HostHabitableCheckHandle * | ||
203 | GNUNET_TESTBED_is_host_habitable (const struct GNUNET_TESTBED_Host *host, | ||
204 | const struct GNUNET_CONFIGURATION_Handle | ||
205 | *config, | ||
206 | GNUNET_TESTBED_HostHabitableCallback cb, | ||
207 | void *cb_cls); | ||
208 | |||
209 | |||
210 | /** | ||
211 | * Function to cancel a request started using GNUNET_TESTBED_is_host_habitable() | ||
212 | * | ||
213 | * @param handle the habitability check handle | ||
214 | */ | ||
215 | void | ||
216 | GNUNET_TESTBED_is_host_habitable_cancel (struct | ||
217 | GNUNET_TESTBED_HostHabitableCheckHandle | ||
218 | *handle); | ||
219 | |||
220 | /** | ||
221 | * Obtain the host's hostname. | ||
222 | * | ||
223 | * @param host handle to the host, NULL means 'localhost' | ||
224 | * @return hostname of the host | ||
225 | */ | ||
226 | const char * | ||
227 | GNUNET_TESTBED_host_get_hostname (const struct GNUNET_TESTBED_Host *host); | ||
228 | |||
229 | |||
230 | /** | ||
231 | * Enumeration with (at most 64) possible event types that | ||
232 | * can be monitored using the testbed framework. | ||
233 | */ | ||
234 | enum GNUNET_TESTBED_EventType | ||
235 | { | ||
236 | /** | ||
237 | * A peer has been started. | ||
238 | */ | ||
239 | GNUNET_TESTBED_ET_PEER_START = 0, | ||
240 | |||
241 | /** | ||
242 | * A peer has been stopped. | ||
243 | */ | ||
244 | GNUNET_TESTBED_ET_PEER_STOP = 1, | ||
245 | |||
246 | /** | ||
247 | * A connection between two peers was established. | ||
248 | */ | ||
249 | GNUNET_TESTBED_ET_CONNECT = 2, | ||
250 | |||
251 | /** | ||
252 | * A connection between two peers was torn down. | ||
253 | */ | ||
254 | GNUNET_TESTBED_ET_DISCONNECT = 3, | ||
255 | |||
256 | /** | ||
257 | * A requested testbed operation has been completed. | ||
258 | */ | ||
259 | GNUNET_TESTBED_ET_OPERATION_FINISHED = 4, | ||
260 | }; | ||
261 | |||
262 | |||
263 | /** | ||
264 | * Types of information that can be requested about a peer. | ||
265 | */ | ||
266 | enum GNUNET_TESTBED_PeerInformationType | ||
267 | { | ||
268 | /** | ||
269 | * Special value (not valid for requesting information) | ||
270 | * that is used in the event struct if a 'generic' pointer | ||
271 | * is returned (for other operations not related to this | ||
272 | * enumeration). | ||
273 | */ | ||
274 | GNUNET_TESTBED_PIT_GENERIC = 0, | ||
275 | |||
276 | /** | ||
277 | * What configuration is the peer using? Returns a 'const struct | ||
278 | * GNUNET_CONFIGURATION_Handle *'. Valid until | ||
279 | * 'GNUNET_TESTNIG_operation_done' is called. However, the | ||
280 | * values may be inaccurate if the peer is reconfigured in | ||
281 | * the meantime. | ||
282 | */ | ||
283 | GNUNET_TESTBED_PIT_CONFIGURATION, | ||
284 | |||
285 | /** | ||
286 | * What is the identity of the peer? Returns a | ||
287 | * 'const struct GNUNET_PeerIdentity *'. Valid until | ||
288 | * 'GNUNET_TESTNIG_operation_done' is called. | ||
289 | */ | ||
290 | GNUNET_TESTBED_PIT_IDENTITY | ||
291 | }; | ||
292 | |||
293 | |||
294 | /** | ||
295 | * Argument to GNUNET_TESTBED_ControllerCallback with details about | ||
296 | * the event. | ||
297 | */ | ||
298 | struct GNUNET_TESTBED_EventInformation | ||
299 | { | ||
300 | /** | ||
301 | * Type of the event. | ||
302 | */ | ||
303 | enum GNUNET_TESTBED_EventType type; | ||
304 | |||
305 | /** | ||
306 | * Handle for the corresponding operation that generated this event | ||
307 | */ | ||
308 | struct GNUNET_TESTBED_Operation *op; | ||
309 | |||
310 | /** | ||
311 | * Closure given while creating the above operation | ||
312 | */ | ||
313 | void *op_cls; | ||
314 | |||
315 | /** | ||
316 | * Details about the event. | ||
317 | */ | ||
318 | union | ||
319 | { | ||
320 | /** | ||
321 | * Details about peer start event. | ||
322 | */ | ||
323 | struct | ||
324 | { | ||
325 | /** | ||
326 | * Handle for the host where the peer | ||
327 | * was started. | ||
328 | */ | ||
329 | struct GNUNET_TESTBED_Host *host; | ||
330 | |||
331 | /** | ||
332 | * Handle for the peer that was started. | ||
333 | */ | ||
334 | struct GNUNET_TESTBED_Peer *peer; | ||
335 | } peer_start; | ||
336 | |||
337 | /** | ||
338 | * Details about peer stop event. | ||
339 | */ | ||
340 | struct | ||
341 | { | ||
342 | /** | ||
343 | * Handle for the peer that was started. | ||
344 | */ | ||
345 | struct GNUNET_TESTBED_Peer *peer; | ||
346 | } peer_stop; | ||
347 | |||
348 | /** | ||
349 | * Details about connect event. | ||
350 | */ | ||
351 | struct | ||
352 | { | ||
353 | /** | ||
354 | * Handle for one of the connected peers. | ||
355 | */ | ||
356 | struct GNUNET_TESTBED_Peer *peer1; | ||
357 | |||
358 | /** | ||
359 | * Handle for one of the connected peers. | ||
360 | */ | ||
361 | struct GNUNET_TESTBED_Peer *peer2; | ||
362 | } peer_connect; | ||
363 | |||
364 | /** | ||
365 | * Details about disconnect event. | ||
366 | */ | ||
367 | struct | ||
368 | { | ||
369 | /** | ||
370 | * Handle for one of the disconnected peers. | ||
371 | */ | ||
372 | struct GNUNET_TESTBED_Peer *peer1; | ||
373 | |||
374 | /** | ||
375 | * Handle for one of the disconnected peers. | ||
376 | */ | ||
377 | struct GNUNET_TESTBED_Peer *peer2; | ||
378 | } peer_disconnect; | ||
379 | |||
380 | /** | ||
381 | * Details about an operation finished event. | ||
382 | */ | ||
383 | struct | ||
384 | { | ||
385 | /** | ||
386 | * Error message for the operation, NULL on success. | ||
387 | */ | ||
388 | const char *emsg; | ||
389 | |||
390 | /** | ||
391 | * No result (NULL pointer) or generic result | ||
392 | * (whatever the GNUNET_TESTBED_ConnectAdapter returned). | ||
393 | */ | ||
394 | void *generic; | ||
395 | } operation_finished; | ||
396 | } details; | ||
397 | }; | ||
398 | |||
399 | |||
400 | /** | ||
401 | * Signature of the event handler function called by the | ||
402 | * respective event controller. | ||
403 | * | ||
404 | * @param cls closure | ||
405 | * @param event information about the event | ||
406 | */ | ||
407 | typedef void | ||
408 | (*GNUNET_TESTBED_ControllerCallback)(void *cls, | ||
409 | const struct | ||
410 | GNUNET_TESTBED_EventInformation *event); | ||
411 | |||
412 | |||
413 | /** | ||
414 | * Opaque Handle for Controller process | ||
415 | */ | ||
416 | struct GNUNET_TESTBED_ControllerProc; | ||
417 | |||
418 | |||
419 | /** | ||
420 | * Callback to signal successful startup of the controller process | ||
421 | * | ||
422 | * @param cls the closure from GNUNET_TESTBED_controller_start() | ||
423 | * @param cfg the configuration with which the controller has been started; | ||
424 | * NULL if status is not #GNUNET_OK | ||
425 | * @param status #GNUNET_OK if the startup is successful; #GNUNET_SYSERR if not, | ||
426 | * GNUNET_TESTBED_controller_stop() shouldn't be called in this case | ||
427 | */ | ||
428 | typedef void | ||
429 | (*GNUNET_TESTBED_ControllerStatusCallback) (void *cls, | ||
430 | const struct | ||
431 | GNUNET_CONFIGURATION_Handle *cfg, | ||
432 | int status); | ||
433 | |||
434 | |||
435 | /** | ||
436 | * Starts a controller process at the given host. The given host's configuration | ||
437 | * is used as a Template configuration to use for the remote controller; the | ||
438 | * remote controller will be started with a slightly modified configuration | ||
439 | * (port numbers, unix domain sockets and service home values are changed as per | ||
440 | * TESTING library on the remote host). The modified configuration replaces the | ||
441 | * host's existing configuration before signalling success through the | ||
442 | * GNUNET_TESTBED_ControllerStatusCallback() | ||
443 | * | ||
444 | * @param trusted_ip the ip address of the controller which will be set as TRUSTED | ||
445 | * HOST(all connections form this ip are permitted by the testbed) when | ||
446 | * starting testbed controller at host. This can either be a single ip | ||
447 | * address or a network address in CIDR notation. | ||
448 | * @param host the host where the controller has to be started. CANNOT be NULL. | ||
449 | * @param cb function called when the controller is successfully started or | ||
450 | * dies unexpectedly; GNUNET_TESTBED_controller_stop shouldn't be | ||
451 | * called if cb is called with GNUNET_SYSERR as status. Will never be | ||
452 | * called in the same task as 'GNUNET_TESTBED_controller_start' | ||
453 | * (synchronous errors will be signalled by returning NULL). This | ||
454 | * parameter cannot be NULL. | ||
455 | * @param cls closure for above callbacks | ||
456 | * @return the controller process handle, NULL on errors | ||
457 | */ | ||
458 | struct GNUNET_TESTBED_ControllerProc * | ||
459 | GNUNET_TESTBED_controller_start (const char *trusted_ip, | ||
460 | struct GNUNET_TESTBED_Host *host, | ||
461 | GNUNET_TESTBED_ControllerStatusCallback cb, | ||
462 | void *cls); | ||
463 | |||
464 | |||
465 | /** | ||
466 | * Stop the controller process (also will terminate all peers and controllers | ||
467 | * dependent on this controller). This function blocks until the testbed has | ||
468 | * been fully terminated (!). The controller status cb from | ||
469 | * GNUNET_TESTBED_controller_start() will not be called. | ||
470 | * | ||
471 | * @param cproc the controller process handle | ||
472 | */ | ||
473 | void | ||
474 | GNUNET_TESTBED_controller_stop (struct GNUNET_TESTBED_ControllerProc *cproc); | ||
475 | |||
476 | |||
477 | /** | ||
478 | * Connect to a controller process. The configuration to use for the connection | ||
479 | * is retrieved from the given host where a controller is started using | ||
480 | * GNUNET_TESTBED_controller_start(). | ||
481 | * | ||
482 | * @param host host to run the controller on; This should be the same host if | ||
483 | * the controller was previously started with | ||
484 | * GNUNET_TESTBED_controller_start() | ||
485 | * @param event_mask bit mask with set of events to call 'cc' for; | ||
486 | * or-ed values of "1LL" shifted by the | ||
487 | * respective 'enum GNUNET_TESTBED_EventType' | ||
488 | * (e.g. "(1LL << GNUNET_TESTBED_ET_CONNECT) | ...") | ||
489 | * @param cc controller callback to invoke on events | ||
490 | * @param cc_cls closure for cc | ||
491 | * @return handle to the controller | ||
492 | */ | ||
493 | struct GNUNET_TESTBED_Controller * | ||
494 | GNUNET_TESTBED_controller_connect (struct GNUNET_TESTBED_Host *host, | ||
495 | uint64_t event_mask, | ||
496 | GNUNET_TESTBED_ControllerCallback cc, | ||
497 | void *cc_cls); | ||
498 | |||
499 | |||
500 | /** | ||
501 | * Stop the given controller (also will terminate all peers and | ||
502 | * controllers dependent on this controller). This function | ||
503 | * blocks until the testbed has been fully terminated (!). | ||
504 | * | ||
505 | * @param c handle to controller to stop | ||
506 | */ | ||
507 | void | ||
508 | GNUNET_TESTBED_controller_disconnect (struct GNUNET_TESTBED_Controller *c); | ||
509 | |||
510 | |||
511 | /** | ||
512 | * Opaque handle for host registration | ||
513 | */ | ||
514 | struct GNUNET_TESTBED_HostRegistrationHandle; | ||
515 | |||
516 | |||
517 | /** | ||
518 | * Callback which will be called to after a host registration succeeded or failed | ||
519 | * | ||
520 | * @param cls the closure | ||
521 | * @param emsg the error message; NULL if host registration is successful | ||
522 | */ | ||
523 | typedef void | ||
524 | (*GNUNET_TESTBED_HostRegistrationCompletion) (void *cls, | ||
525 | const char *emsg); | ||
526 | |||
527 | |||
528 | /** | ||
529 | * Register a host with the controller. This makes the controller aware of the | ||
530 | * host. A host should be registered at the controller before starting a | ||
531 | * sub-controller on that host using GNUNET_TESTBED_controller_link(). | ||
532 | * | ||
533 | * @param controller the controller handle | ||
534 | * @param host the host to register | ||
535 | * @param cc the completion callback to call to inform the status of | ||
536 | * registration. After calling this callback the registration handle | ||
537 | * will be invalid. Cannot be NULL | ||
538 | * @param cc_cls the closure for the cc | ||
539 | * @return handle to the host registration which can be used to cancel the | ||
540 | * registration; NULL if another registration handle is present and | ||
541 | * is not cancelled | ||
542 | */ | ||
543 | struct GNUNET_TESTBED_HostRegistrationHandle * | ||
544 | GNUNET_TESTBED_register_host (struct GNUNET_TESTBED_Controller *controller, | ||
545 | struct GNUNET_TESTBED_Host *host, | ||
546 | GNUNET_TESTBED_HostRegistrationCompletion cc, | ||
547 | void *cc_cls); | ||
548 | |||
549 | |||
550 | /** | ||
551 | * Cancel the pending registration. Note that the registration message will | ||
552 | * already be queued to be sent to the service, cancellation has only the | ||
553 | * effect that the registration completion callback for the registration is | ||
554 | * never called and from our perspective the host is not registered until the | ||
555 | * completion callback is called. | ||
556 | * | ||
557 | * @param handle the registration handle to cancel | ||
558 | */ | ||
559 | void | ||
560 | GNUNET_TESTBED_cancel_registration (struct GNUNET_TESTBED_HostRegistrationHandle | ||
561 | *handle); | ||
562 | |||
563 | |||
564 | /** | ||
565 | * Callback to be called when an operation is completed | ||
566 | * | ||
567 | * @param cls the callback closure from functions generating an operation | ||
568 | * @param op the operation that has been finished | ||
569 | * @param emsg error message in case the operation has failed; will be NULL if | ||
570 | * operation has executed successfully. | ||
571 | */ | ||
572 | typedef void | ||
573 | (*GNUNET_TESTBED_OperationCompletionCallback) (void *cls, | ||
574 | struct GNUNET_TESTBED_Operation * | ||
575 | op, | ||
576 | const char *emsg); | ||
577 | |||
578 | |||
579 | /** | ||
580 | * Create a link from slave controller to delegated controller. Whenever the | ||
581 | * master controller is asked to start a peer at the delegated controller the | ||
582 | * request will be routed towards slave controller (if a route exists). The | ||
583 | * slave controller will then route it to the delegated controller. The | ||
584 | * configuration of the delegated controller is given and is used to either | ||
585 | * create the delegated controller or to connect to an existing controller. Note | ||
586 | * that while starting the delegated controller the configuration will be | ||
587 | * modified to accommodate available free ports. the 'is_subordinate' specifies | ||
588 | * if the given delegated controller should be started and managed by the slave | ||
589 | * controller, or if the delegated controller already has a master and the slave | ||
590 | * controller connects to it as a non master controller. The success or failure | ||
591 | * of this operation will be signalled through the | ||
592 | * GNUNET_TESTBED_ControllerCallback() with an event of type | ||
593 | * #GNUNET_TESTBED_ET_OPERATION_FINISHED | ||
594 | * | ||
595 | * @param op_cls the operation closure for the event which is generated to | ||
596 | * signal success or failure of this operation | ||
597 | * @param master handle to the master controller who creates the association | ||
598 | * @param delegated_host requests to which host should be delegated; cannot be NULL | ||
599 | * @param slave_host which host is used to run the slave controller; use NULL to | ||
600 | * make the master controller connect to the delegated host | ||
601 | * @param is_subordinate #GNUNET_YES if the controller at delegated_host should | ||
602 | * be started by the slave controller; #GNUNET_NO if the slave | ||
603 | * controller has to connect to the already started delegated | ||
604 | * controller via TCP/IP | ||
605 | * @return the operation handle | ||
606 | */ | ||
607 | struct GNUNET_TESTBED_Operation * | ||
608 | GNUNET_TESTBED_controller_link (void *op_cls, | ||
609 | struct GNUNET_TESTBED_Controller *master, | ||
610 | struct GNUNET_TESTBED_Host *delegated_host, | ||
611 | struct GNUNET_TESTBED_Host *slave_host, | ||
612 | int is_subordinate); | ||
613 | |||
614 | |||
615 | /** | ||
616 | * Function to acquire the configuration of a running slave controller. The | ||
617 | * completion of the operation is signalled through the controller_cb from | ||
618 | * GNUNET_TESTBED_controller_connect(). If the operation is successful the | ||
619 | * handle to the configuration is available in the generic pointer of | ||
620 | * operation_finished field of `struct GNUNET_TESTBED_EventInformation`. | ||
621 | * | ||
622 | * @param op_cls the closure for the operation | ||
623 | * @param master the handle to master controller | ||
624 | * @param slave_host the host where the slave controller is running; the handle | ||
625 | * to the slave_host should remain valid until this operation is | ||
626 | * cancelled or marked as finished | ||
627 | * @return the operation handle; NULL if the slave_host is not registered at | ||
628 | * master | ||
629 | */ | ||
630 | struct GNUNET_TESTBED_Operation * | ||
631 | GNUNET_TESTBED_get_slave_config (void *op_cls, | ||
632 | struct GNUNET_TESTBED_Controller *master, | ||
633 | struct GNUNET_TESTBED_Host *slave_host); | ||
634 | |||
635 | |||
636 | /** | ||
637 | * Functions of this signature are called when a peer has been successfully | ||
638 | * created | ||
639 | * | ||
640 | * @param cls the closure from GNUNET_TESTBED_peer_create() | ||
641 | * @param peer the handle for the created peer; NULL on any error during | ||
642 | * creation | ||
643 | * @param emsg NULL if peer is not NULL; else MAY contain the error description | ||
644 | */ | ||
645 | typedef void | ||
646 | (*GNUNET_TESTBED_PeerCreateCallback) (void *cls, | ||
647 | struct GNUNET_TESTBED_Peer *peer, | ||
648 | const char *emsg); | ||
649 | |||
650 | |||
651 | /** | ||
652 | * Create the given peer at the specified host using the given | ||
653 | * controller. If the given controller is not running on the target | ||
654 | * host, it should find or create a controller at the target host and | ||
655 | * delegate creating the peer. Explicit delegation paths can be setup | ||
656 | * using 'GNUNET_TESTBED_controller_link'. If no explicit delegation | ||
657 | * path exists, a direct link with a subordinate controller is setup | ||
658 | * for the first delegated peer to a particular host; the subordinate | ||
659 | * controller is then destroyed once the last peer that was delegated | ||
660 | * to the remote host is stopped. | ||
661 | * | ||
662 | * Creating the peer only creates the handle to manipulate and further | ||
663 | * configure the peer; use #GNUNET_TESTBED_peer_start and | ||
664 | * #GNUNET_TESTBED_peer_stop to actually start/stop the peer's | ||
665 | * processes. | ||
666 | * | ||
667 | * Note that the given configuration will be adjusted by the | ||
668 | * controller to avoid port/path conflicts with other peers. | ||
669 | * The "final" configuration can be obtained using | ||
670 | * #GNUNET_TESTBED_peer_get_information. | ||
671 | * | ||
672 | * @param controller controller process to use | ||
673 | * @param host host to run the peer on; cannot be NULL | ||
674 | * @param cfg Template configuration to use for the peer. Should exist until | ||
675 | * operation is cancelled or GNUNET_TESTBED_operation_done() is called | ||
676 | * @param cb the callback to call when the peer has been created | ||
677 | * @param cls the closure to the above callback | ||
678 | * @return the operation handle | ||
679 | */ | ||
680 | struct GNUNET_TESTBED_Operation * | ||
681 | GNUNET_TESTBED_peer_create (struct GNUNET_TESTBED_Controller *controller, | ||
682 | struct GNUNET_TESTBED_Host *host, | ||
683 | const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
684 | GNUNET_TESTBED_PeerCreateCallback cb, | ||
685 | void *cls); | ||
686 | |||
687 | |||
688 | /** | ||
689 | * Functions of this signature are called when a peer has been successfully | ||
690 | * started or stopped. | ||
691 | * | ||
692 | * @param cls the closure from GNUNET_TESTBED_peer_start/stop() | ||
693 | * @param emsg NULL on success; otherwise an error description | ||
694 | */ | ||
695 | typedef void | ||
696 | (*GNUNET_TESTBED_PeerChurnCallback) (void *cls, | ||
697 | const char *emsg); | ||
698 | |||
699 | |||
700 | /** | ||
701 | * Start the given peer. | ||
702 | * | ||
703 | * @param op_cls the closure for this operation; will be set in the event | ||
704 | * information | ||
705 | * @param peer peer to start | ||
706 | * @param pcc function to call upon completion | ||
707 | * @param pcc_cls closure for 'pcc' | ||
708 | * @return handle to the operation | ||
709 | */ | ||
710 | struct GNUNET_TESTBED_Operation * | ||
711 | GNUNET_TESTBED_peer_start (void *op_cls, | ||
712 | struct GNUNET_TESTBED_Peer *peer, | ||
713 | GNUNET_TESTBED_PeerChurnCallback pcc, | ||
714 | void *pcc_cls); | ||
715 | |||
716 | |||
717 | /** | ||
718 | * Stop the given peer. The handle remains valid (use | ||
719 | * #GNUNET_TESTBED_peer_destroy to fully clean up the | ||
720 | * state of the peer). | ||
721 | * | ||
722 | * @param op_cls the closure for this operation; will be set in the event | ||
723 | * information | ||
724 | * @param peer peer to stop | ||
725 | * @param pcc function to call upon completion | ||
726 | * @param pcc_cls closure for 'pcc' | ||
727 | * @return handle to the operation | ||
728 | */ | ||
729 | struct GNUNET_TESTBED_Operation * | ||
730 | GNUNET_TESTBED_peer_stop (void *op_cls, | ||
731 | struct GNUNET_TESTBED_Peer *peer, | ||
732 | GNUNET_TESTBED_PeerChurnCallback pcc, | ||
733 | void *pcc_cls); | ||
734 | |||
735 | |||
736 | /** | ||
737 | * Data returned from GNUNET_TESTBED_peer_get_information | ||
738 | */ | ||
739 | struct GNUNET_TESTBED_PeerInformation | ||
740 | { | ||
741 | /** | ||
742 | * Peer information type; captures which of the types | ||
743 | * in the 'op_result' is actually in use. | ||
744 | */ | ||
745 | enum GNUNET_TESTBED_PeerInformationType pit; | ||
746 | |||
747 | /** | ||
748 | * The result of the get information operation; Choose according to the pit | ||
749 | */ | ||
750 | union | ||
751 | { | ||
752 | /** | ||
753 | * The configuration of the peer | ||
754 | */ | ||
755 | struct GNUNET_CONFIGURATION_Handle *cfg; | ||
756 | |||
757 | /** | ||
758 | * The identity of the peer | ||
759 | */ | ||
760 | struct GNUNET_PeerIdentity *id; | ||
761 | } result; | ||
762 | }; | ||
763 | |||
764 | |||
765 | /** | ||
766 | * Callback to be called when the requested peer information is available | ||
767 | * The peer information in the callback is valid until the operation 'op' is canceled. | ||
768 | * | ||
769 | * @param cb_cls the closure from GNUNET_TETSBED_peer_get_information() | ||
770 | * @param op the operation this callback corresponds to | ||
771 | * @param pinfo the result; will be NULL if the operation has failed | ||
772 | * @param emsg error message if the operation has failed; will be NULL if the | ||
773 | * operation is successful | ||
774 | */ | ||
775 | typedef void | ||
776 | (*GNUNET_TESTBED_PeerInfoCallback) (void *cb_cls, | ||
777 | struct GNUNET_TESTBED_Operation *op, | ||
778 | const struct | ||
779 | GNUNET_TESTBED_PeerInformation *pinfo, | ||
780 | const char *emsg); | ||
781 | |||
782 | |||
783 | /** | ||
784 | * Request information about a peer. The controller callback will not be called | ||
785 | * with event type #GNUNET_TESTBED_ET_OPERATION_FINISHED when result for this | ||
786 | * operation is available. Instead, the GNUNET_TESTBED_PeerInfoCallback() will | ||
787 | * be called. | ||
788 | * The peer information in the callback is valid until the operation is canceled. | ||
789 | * | ||
790 | * @param peer peer to request information about | ||
791 | * @param pit desired information | ||
792 | * @param cb the convenience callback to be called when results for this | ||
793 | * operation are available | ||
794 | * @param cb_cls the closure for @a cb | ||
795 | * @return handle to the operation | ||
796 | */ | ||
797 | struct GNUNET_TESTBED_Operation * | ||
798 | GNUNET_TESTBED_peer_get_information (struct GNUNET_TESTBED_Peer *peer, | ||
799 | enum GNUNET_TESTBED_PeerInformationType | ||
800 | pit, | ||
801 | GNUNET_TESTBED_PeerInfoCallback cb, | ||
802 | void *cb_cls); | ||
803 | |||
804 | |||
805 | /** | ||
806 | * Change @a peer configuration. Ports and paths cannot be changed this | ||
807 | * way. | ||
808 | * | ||
809 | * @param peer peer to change configuration for | ||
810 | * @param cfg new configuration | ||
811 | * @return handle to the operation | ||
812 | */ | ||
813 | struct GNUNET_TESTBED_Operation * | ||
814 | GNUNET_TESTBED_peer_update_configuration (struct GNUNET_TESTBED_Peer *peer, | ||
815 | const struct | ||
816 | GNUNET_CONFIGURATION_Handle *cfg); | ||
817 | |||
818 | |||
819 | /** | ||
820 | * Destroy the given peer; the peer should have been | ||
821 | * stopped first (if it was started). | ||
822 | * | ||
823 | * @param peer peer to stop | ||
824 | * @return handle to the operation | ||
825 | */ | ||
826 | struct GNUNET_TESTBED_Operation * | ||
827 | GNUNET_TESTBED_peer_destroy (struct GNUNET_TESTBED_Peer *peer); | ||
828 | |||
829 | |||
830 | /** | ||
831 | * Start or stop given service at a peer. This should not be called to | ||
832 | * start/stop the peer's ARM service. Use GNUNET_TESTBED_peer_start(), | ||
833 | * GNUNET_TESTBED_peer_stop() for starting/stopping peer's ARM service. Success | ||
834 | * or failure of the generated operation is signalled through the controller | ||
835 | * event callback and/or operation completion callback. | ||
836 | * | ||
837 | * @param op_cls the closure for the operation | ||
838 | * @param peer the peer whose service is to be started/stopped | ||
839 | * @param service_name the name of the service | ||
840 | * @param cb the operation completion callback | ||
841 | * @param cb_cls the closure for @a cb | ||
842 | * @param start 1 to start the service; 0 to stop the service | ||
843 | * @return an operation handle; NULL upon error (peer not running) | ||
844 | */ | ||
845 | struct GNUNET_TESTBED_Operation * | ||
846 | GNUNET_TESTBED_peer_manage_service (void *op_cls, | ||
847 | struct GNUNET_TESTBED_Peer *peer, | ||
848 | const char *service_name, | ||
849 | GNUNET_TESTBED_OperationCompletionCallback | ||
850 | cb, | ||
851 | void *cb_cls, | ||
852 | unsigned int start); | ||
853 | |||
854 | |||
855 | /** | ||
856 | * Stops and destroys all peers. Is equivalent of calling | ||
857 | * GNUNET_TESTBED_peer_stop() and GNUNET_TESTBED_peer_destroy() on all peers, | ||
858 | * except that the peer stop event and operation finished event corresponding to | ||
859 | * the respective functions are not generated. This function should be called | ||
860 | * when there are no other pending operations. If there are pending operations, | ||
861 | * it will return NULL | ||
862 | * | ||
863 | * @param c the controller to send this message to | ||
864 | * @param op_cls closure for the operation | ||
865 | * @param cb the callback to call when all peers are stopped and destroyed | ||
866 | * @param cb_cls the closure for the callback | ||
867 | * @return operation handle on success; NULL if any pending operations are | ||
868 | * present | ||
869 | */ | ||
870 | struct GNUNET_TESTBED_Operation * | ||
871 | GNUNET_TESTBED_shutdown_peers (struct GNUNET_TESTBED_Controller *c, | ||
872 | void *op_cls, | ||
873 | GNUNET_TESTBED_OperationCompletionCallback cb, | ||
874 | void *cb_cls); | ||
875 | |||
876 | |||
877 | /** | ||
878 | * Options for peer connections. | ||
879 | */ | ||
880 | enum GNUNET_TESTBED_ConnectOption | ||
881 | { | ||
882 | /** | ||
883 | * No option (not valid as an argument). | ||
884 | */ | ||
885 | GNUNET_TESTBED_CO_NONE = 0, | ||
886 | |||
887 | /** | ||
888 | * Allow or disallow a connection between the specified peers. | ||
889 | * Followed by #GNUNET_NO (int) if a connection is disallowed | ||
890 | * or #GNUNET_YES if a connection is allowed. Note that the | ||
891 | * default (all connections allowed or disallowed) is | ||
892 | * specified in the configuration of the controller. | ||
893 | */ | ||
894 | GNUNET_TESTBED_CO_ALLOW = 1, | ||
895 | |||
896 | /** | ||
897 | * FIXME: add (and implement) options to limit connection to | ||
898 | * particular transports, force simulation of particular latencies | ||
899 | * or message loss rates, or set bandwidth limitations. | ||
900 | */ | ||
901 | }; | ||
902 | |||
903 | |||
904 | /** | ||
905 | * Manipulate the P2P underlay topology by configuring a link | ||
906 | * between two peers. | ||
907 | * | ||
908 | * @param op_cls closure argument to give with the operation event | ||
909 | * @param p1 first peer | ||
910 | * @param p2 second peer | ||
911 | * @param co option to change | ||
912 | * @param ap option-specific values | ||
913 | * @return handle to the operation, NULL if configuring the link at this | ||
914 | * time is not allowed | ||
915 | */ | ||
916 | struct GNUNET_TESTBED_Operation * | ||
917 | GNUNET_TESTBED_underlay_configure_link_va (void *op_cls, | ||
918 | struct GNUNET_TESTBED_Peer *p1, | ||
919 | struct GNUNET_TESTBED_Peer *p2, | ||
920 | enum GNUNET_TESTBED_ConnectOption co, | ||
921 | va_list ap); | ||
922 | |||
923 | |||
924 | /** | ||
925 | * Manipulate the P2P underlay topology by configuring a link | ||
926 | * between two peers. | ||
927 | * | ||
928 | * @param op_cls closure argument to give with the operation event | ||
929 | * @param p1 first peer | ||
930 | * @param p2 second peer | ||
931 | * @param co option to change | ||
932 | * @param ... option-specific values | ||
933 | * @return handle to the operation, NULL if configuring the link at this | ||
934 | * time is not allowed | ||
935 | */ | ||
936 | struct GNUNET_TESTBED_Operation * | ||
937 | GNUNET_TESTBED_underlay_configure_link (void *op_cls, | ||
938 | struct GNUNET_TESTBED_Peer *p1, | ||
939 | struct GNUNET_TESTBED_Peer *p2, | ||
940 | enum GNUNET_TESTBED_ConnectOption co, | ||
941 | ...); | ||
942 | |||
943 | |||
944 | /** | ||
945 | * Topologies and topology options supported for testbeds. Options should always | ||
946 | * end with #GNUNET_TESTBED_TOPOLOGY_OPTION_END | ||
947 | */ | ||
948 | enum GNUNET_TESTBED_TopologyOption | ||
949 | { | ||
950 | /** | ||
951 | * A clique (everyone connected to everyone else). No options. If there are N | ||
952 | * peers this topology results in (N * (N -1)) connections. | ||
953 | */ | ||
954 | GNUNET_TESTBED_TOPOLOGY_CLIQUE, | ||
955 | |||
956 | /** | ||
957 | * Small-world network (2d torus plus random links). Followed | ||
958 | * by the number of random links to add (unsigned int). | ||
959 | */ | ||
960 | GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD, | ||
961 | |||
962 | /** | ||
963 | * Small-world network (ring plus random links). Followed | ||
964 | * by the number of random links to add (unsigned int). | ||
965 | */ | ||
966 | GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD_RING, | ||
967 | |||
968 | /** | ||
969 | * Ring topology. No options. | ||
970 | */ | ||
971 | GNUNET_TESTBED_TOPOLOGY_RING, | ||
972 | |||
973 | /** | ||
974 | * Star topology. No options. | ||
975 | */ | ||
976 | GNUNET_TESTBED_TOPOLOGY_STAR, | ||
977 | |||
978 | /** | ||
979 | * 2-d torus. No options. | ||
980 | */ | ||
981 | GNUNET_TESTBED_TOPOLOGY_2D_TORUS, | ||
982 | |||
983 | /** | ||
984 | * Random graph. Followed by the number of random links to be established | ||
985 | * (unsigned int) | ||
986 | */ | ||
987 | GNUNET_TESTBED_TOPOLOGY_ERDOS_RENYI, | ||
988 | |||
989 | /** | ||
990 | * Certain percentage of peers are unable to communicate directly | ||
991 | * replicating NAT conditions. Followed by the fraction of | ||
992 | * NAT'ed peers (float). | ||
993 | */ | ||
994 | GNUNET_TESTBED_TOPOLOGY_INTERNAT, | ||
995 | |||
996 | /** | ||
997 | * Scale free topology. It is generated according to the method described in | ||
998 | * "Emergence of Scaling in Random Networks." Science 286, 509-512, 1999. | ||
999 | * | ||
1000 | * This options takes two arguments in the following order: an uint16_t to | ||
1001 | * determine the maximum number of edges a peer is permitted to have while | ||
1002 | * generating scale free topology, a good value for this argument is 70; and | ||
1003 | * an uint8_t to determine the number of edges to be established when adding a | ||
1004 | * new node to the scale free network, a good value for this argument is 4. | ||
1005 | */ | ||
1006 | GNUNET_TESTBED_TOPOLOGY_SCALE_FREE, | ||
1007 | |||
1008 | /** | ||
1009 | * Straight line topology. No options. | ||
1010 | */ | ||
1011 | GNUNET_TESTBED_TOPOLOGY_LINE, | ||
1012 | |||
1013 | /** | ||
1014 | * Read a topology from a given file. Followed by the name of the file (const char *). | ||
1015 | */ | ||
1016 | GNUNET_TESTBED_TOPOLOGY_FROM_FILE, | ||
1017 | |||
1018 | /** | ||
1019 | * All peers are disconnected. No options. | ||
1020 | */ | ||
1021 | GNUNET_TESTBED_TOPOLOGY_NONE, | ||
1022 | |||
1023 | /** | ||
1024 | * The options should always end with this | ||
1025 | */ | ||
1026 | GNUNET_TESTBED_TOPOLOGY_OPTION_END, | ||
1027 | |||
1028 | /* The following are not topologies but influence how the topology has to be | ||
1029 | setup. These options should follow the topology specific options (if | ||
1030 | required by the chosen topology). Note that these should be given before | ||
1031 | GNUNET_TESTBED_TOPOLOGY_OPTION_END */ | ||
1032 | |||
1033 | /** | ||
1034 | * How many times should the failed overlay connect operations be retried | ||
1035 | * before giving up. The default if this option is not specified is to retry | ||
1036 | * 3 times. This option takes and unsigned integer as a parameter. Use this | ||
1037 | * option with parameter 0 to disable retrying of failed overlay connect | ||
1038 | * operations. | ||
1039 | */ | ||
1040 | GNUNET_TESTBED_TOPOLOGY_RETRY_CNT | ||
1041 | }; | ||
1042 | |||
1043 | |||
1044 | /** | ||
1045 | * Configure overall network topology to have a particular shape. | ||
1046 | * | ||
1047 | * @param op_cls closure argument to give with the operation event | ||
1048 | * @param num_peers number of peers in 'peers' | ||
1049 | * @param peers array of 'num_peers' with the peers to configure | ||
1050 | * @param topo desired underlay topology to use | ||
1051 | * @param ap topology-specific options | ||
1052 | * @return handle to the operation, NULL if configuring the topology | ||
1053 | * is not allowed at this time | ||
1054 | */ | ||
1055 | struct GNUNET_TESTBED_Operation * | ||
1056 | GNUNET_TESTBED_underlay_configure_topology_va (void *op_cls, | ||
1057 | unsigned int num_peers, | ||
1058 | struct GNUNET_TESTBED_Peer ** | ||
1059 | peers, | ||
1060 | enum | ||
1061 | GNUNET_TESTBED_TopologyOption | ||
1062 | topo, | ||
1063 | va_list ap); | ||
1064 | |||
1065 | |||
1066 | /** | ||
1067 | * Configure overall network topology to have a particular shape. | ||
1068 | * | ||
1069 | * @param op_cls closure argument to give with the operation event | ||
1070 | * @param num_peers number of peers in 'peers' | ||
1071 | * @param peers array of 'num_peers' with the peers to configure | ||
1072 | * @param topo desired underlay topology to use | ||
1073 | * @param ... topology-specific options | ||
1074 | * @return handle to the operation, NULL if configuring the topology | ||
1075 | * is not allowed at this time | ||
1076 | */ | ||
1077 | struct GNUNET_TESTBED_Operation * | ||
1078 | GNUNET_TESTBED_underlay_configure_topology (void *op_cls, | ||
1079 | unsigned int num_peers, | ||
1080 | struct GNUNET_TESTBED_Peer **peers, | ||
1081 | enum GNUNET_TESTBED_TopologyOption | ||
1082 | topo, | ||
1083 | ...); | ||
1084 | |||
1085 | |||
1086 | /** | ||
1087 | * Both peers must have been started before calling this function. | ||
1088 | * This function then obtains a HELLO from @a p1, gives it to @a p2 | ||
1089 | * and asks @a p2 to connect to @a p1. | ||
1090 | * | ||
1091 | * @param op_cls closure argument to give with the operation event | ||
1092 | * @param cb the callback to call when this operation has finished | ||
1093 | * @param cb_cls the closure for @a cb | ||
1094 | * @param p1 first peer | ||
1095 | * @param p2 second peer | ||
1096 | * @return handle to the operation, NULL if connecting these two | ||
1097 | * peers is fundamentally not possible at this time (peers | ||
1098 | * not running or underlay disallows) | ||
1099 | */ | ||
1100 | struct GNUNET_TESTBED_Operation * | ||
1101 | GNUNET_TESTBED_overlay_connect (void *op_cls, | ||
1102 | GNUNET_TESTBED_OperationCompletionCallback cb, | ||
1103 | void *cb_cls, | ||
1104 | struct GNUNET_TESTBED_Peer *p1, | ||
1105 | struct GNUNET_TESTBED_Peer *p2); | ||
1106 | |||
1107 | |||
1108 | /** | ||
1109 | * Callbacks of this type are called when topology configuration is completed | ||
1110 | * | ||
1111 | * @param cls the operation closure given to | ||
1112 | * GNUNET_TESTBED_overlay_configure_topology_va() and | ||
1113 | * GNUNET_TESTBED_overlay_configure() calls | ||
1114 | * @param nsuccess the number of successful overlay connects | ||
1115 | * @param nfailures the number of overlay connects which failed | ||
1116 | */ | ||
1117 | typedef void (*GNUNET_TESTBED_TopologyCompletionCallback) (void *cls, | ||
1118 | unsigned int | ||
1119 | nsuccess, | ||
1120 | unsigned int | ||
1121 | nfailures); | ||
1122 | |||
1123 | |||
1124 | /** | ||
1125 | * All peers must have been started before calling this function. | ||
1126 | * This function then connects the given peers in the P2P overlay | ||
1127 | * using the given topology. | ||
1128 | * | ||
1129 | * @param op_cls closure argument to give with the peer connect operation events | ||
1130 | * generated through this function | ||
1131 | * @param num_peers number of peers in 'peers' | ||
1132 | * @param peers array of 'num_peers' with the peers to configure | ||
1133 | * @param max_connections the maximums number of overlay connections that will | ||
1134 | * be made to achieve the given topology | ||
1135 | * @param comp_cb the completion callback to call when the topology generation | ||
1136 | * is completed | ||
1137 | * @param comp_cb_cls closure for the @a comp_cb | ||
1138 | * @param topo desired underlay topology to use | ||
1139 | * @param va topology-specific options | ||
1140 | * @return handle to the operation, NULL if connecting these | ||
1141 | * peers is fundamentally not possible at this time (peers | ||
1142 | * not running or underlay disallows) or if num_peers is less than 2 | ||
1143 | */ | ||
1144 | struct GNUNET_TESTBED_Operation * | ||
1145 | GNUNET_TESTBED_overlay_configure_topology_va (void *op_cls, | ||
1146 | unsigned int num_peers, | ||
1147 | struct GNUNET_TESTBED_Peer **peers, | ||
1148 | unsigned int *max_connections, | ||
1149 | GNUNET_TESTBED_TopologyCompletionCallback | ||
1150 | comp_cb, | ||
1151 | void *comp_cb_cls, | ||
1152 | enum GNUNET_TESTBED_TopologyOption | ||
1153 | topo, | ||
1154 | va_list va); | ||
1155 | |||
1156 | |||
1157 | /** | ||
1158 | * All peers must have been started before calling this function. | ||
1159 | * This function then connects the given peers in the P2P overlay | ||
1160 | * using the given topology. | ||
1161 | * | ||
1162 | * @param op_cls closure argument to give with the peer connect operation events | ||
1163 | * generated through this function | ||
1164 | * @param num_peers number of peers in 'peers' | ||
1165 | * @param peers array of 'num_peers' with the peers to configure | ||
1166 | * @param max_connections the maximums number of overlay connections that will | ||
1167 | * be made to achieve the given topology | ||
1168 | * @param comp_cb the completion callback to call when the topology generation | ||
1169 | * is completed | ||
1170 | * @param comp_cb_cls closure for the above completion callback | ||
1171 | * @param topo desired underlay topology to use | ||
1172 | * @param ... topology-specific options | ||
1173 | * @return handle to the operation, NULL if connecting these | ||
1174 | * peers is fundamentally not possible at this time (peers | ||
1175 | * not running or underlay disallows) or if num_peers is less than 2 | ||
1176 | */ | ||
1177 | struct GNUNET_TESTBED_Operation * | ||
1178 | GNUNET_TESTBED_overlay_configure_topology (void *op_cls, | ||
1179 | unsigned int num_peers, | ||
1180 | struct GNUNET_TESTBED_Peer **peers, | ||
1181 | unsigned int *max_connections, | ||
1182 | GNUNET_TESTBED_TopologyCompletionCallback | ||
1183 | comp_cb, | ||
1184 | void *comp_cb_cls, | ||
1185 | enum GNUNET_TESTBED_TopologyOption | ||
1186 | topo, | ||
1187 | ...); | ||
1188 | |||
1189 | |||
1190 | /** | ||
1191 | * Ask the testbed controller to write the current overlay topology to | ||
1192 | * a file. Naturally, the file will only contain a snapshot as the | ||
1193 | * topology may evolve all the time. | ||
1194 | * FIXME: needs continuation!? | ||
1195 | * | ||
1196 | * @param controller overlay controller to inspect | ||
1197 | * @param filename name of the file the topology should | ||
1198 | * be written to. | ||
1199 | */ | ||
1200 | void | ||
1201 | GNUNET_TESTBED_overlay_write_topology_to_file (struct | ||
1202 | GNUNET_TESTBED_Controller * | ||
1203 | controller, | ||
1204 | const char *filename); | ||
1205 | |||
1206 | |||
1207 | /** | ||
1208 | * Adapter function called to establish a connection to | ||
1209 | * a service. | ||
1210 | * | ||
1211 | * @param cls closure | ||
1212 | * @param cfg configuration of the peer to connect to; will be available until | ||
1213 | * GNUNET_TESTBED_operation_done() is called on the operation returned | ||
1214 | * from GNUNET_TESTBED_service_connect() | ||
1215 | * @return service handle to return in 'op_result', NULL on error | ||
1216 | */ | ||
1217 | typedef void * | ||
1218 | (*GNUNET_TESTBED_ConnectAdapter)(void *cls, | ||
1219 | const struct GNUNET_CONFIGURATION_Handle *cfg); | ||
1220 | |||
1221 | |||
1222 | /** | ||
1223 | * Adapter function called to destroy a connection to | ||
1224 | * a service. | ||
1225 | * | ||
1226 | * @param cls closure | ||
1227 | * @param op_result service handle returned from the connect adapter | ||
1228 | */ | ||
1229 | typedef void | ||
1230 | (*GNUNET_TESTBED_DisconnectAdapter)(void *cls, | ||
1231 | void *op_result); | ||
1232 | |||
1233 | |||
1234 | /** | ||
1235 | * Callback to be called when a service connect operation is completed | ||
1236 | * | ||
1237 | * @param cls the callback closure from functions generating an operation | ||
1238 | * @param op the operation that has been finished | ||
1239 | * @param ca_result the service handle returned from GNUNET_TESTBED_ConnectAdapter() | ||
1240 | * @param emsg error message in case the operation has failed; will be NULL if | ||
1241 | * operation has executed successfully. | ||
1242 | */ | ||
1243 | typedef void | ||
1244 | (*GNUNET_TESTBED_ServiceConnectCompletionCallback) (void *cls, | ||
1245 | struct | ||
1246 | GNUNET_TESTBED_Operation *op, | ||
1247 | void *ca_result, | ||
1248 | const char *emsg); | ||
1249 | |||
1250 | |||
1251 | /** | ||
1252 | * Connect to a service offered by the given peer. Will ensure that | ||
1253 | * the request is queued to not overwhelm our ability to create and | ||
1254 | * maintain connections with other systems. The actual service | ||
1255 | * handle is then returned via the 'op_result' member in the event | ||
1256 | * callback. The @a ca callback is used to create the connection | ||
1257 | * when the time is right; the @a da callback will be used to | ||
1258 | * destroy the connection (upon #GNUNET_TESTBED_operation_done). | ||
1259 | * #GNUNET_TESTBED_operation_done can be used to abort this | ||
1260 | * operation until the event callback has been called. | ||
1261 | * | ||
1262 | * @param op_cls closure to pass in operation event // FIXME: didn't we say we'd no longer use the global callback for these? -CG | ||
1263 | * @param peer peer that runs the service | ||
1264 | * @param service_name name of the service to connect to | ||
1265 | * @param cb the callback to call when this operation is ready (that is, | ||
1266 | * right after the connect adapter returns) | ||
1267 | * @param cb_cls closure for @a cb | ||
1268 | * @param ca helper function to establish the connection | ||
1269 | * @param da helper function to close the connection | ||
1270 | * @param cada_cls closure for @a ca and @a da | ||
1271 | * @return handle for the operation | ||
1272 | */ | ||
1273 | struct GNUNET_TESTBED_Operation * | ||
1274 | GNUNET_TESTBED_service_connect (void *op_cls, | ||
1275 | struct GNUNET_TESTBED_Peer *peer, | ||
1276 | const char *service_name, | ||
1277 | GNUNET_TESTBED_ServiceConnectCompletionCallback | ||
1278 | cb, | ||
1279 | void *cb_cls, | ||
1280 | GNUNET_TESTBED_ConnectAdapter ca, | ||
1281 | GNUNET_TESTBED_DisconnectAdapter da, | ||
1282 | void *cada_cls); | ||
1283 | |||
1284 | |||
1285 | /** | ||
1286 | * This function is used to signal that the event information (struct | ||
1287 | * GNUNET_TESTBED_EventInformation) from an operation has been fully processed | ||
1288 | * i.e. if the event callback is ever called for this operation. If the event | ||
1289 | * callback for this operation has not yet been called, calling this function | ||
1290 | * cancels the operation, frees its resources and ensures the no event is | ||
1291 | * generated with respect to this operation. Note that however cancelling an | ||
1292 | * operation does NOT guarantee that the operation will be fully undone (or that | ||
1293 | * nothing ever happened). | ||
1294 | * | ||
1295 | * This function MUST be called for every operation to fully remove the | ||
1296 | * operation from the operation queue. After calling this function, if | ||
1297 | * operation is completed and its event information is of type | ||
1298 | * GNUNET_TESTBED_ET_OPERATION_FINISHED, the 'op_result' becomes invalid (!). | ||
1299 | |||
1300 | * If the operation is generated from GNUNET_TESTBED_service_connect() then | ||
1301 | * calling this function on such as operation calls the disconnect adapter if | ||
1302 | * the connect adapter was ever called. | ||
1303 | * | ||
1304 | * @param operation operation to signal completion or cancellation | ||
1305 | */ | ||
1306 | void | ||
1307 | GNUNET_TESTBED_operation_done (struct GNUNET_TESTBED_Operation *operation); | ||
1308 | |||
1309 | |||
1310 | /** | ||
1311 | * Callback function to process statistic values from all peers. | ||
1312 | * | ||
1313 | * @param cls closure | ||
1314 | * @param peer the peer the statistic belong to | ||
1315 | * @param subsystem name of subsystem that created the statistic | ||
1316 | * @param name the name of the datum | ||
1317 | * @param value the current value | ||
1318 | * @param is_persistent #GNUNET_YES if the value is persistent, #GNUNET_NO if not | ||
1319 | * @return #GNUNET_OK to continue, #GNUNET_SYSERR to abort iteration | ||
1320 | */ | ||
1321 | typedef int | ||
1322 | (*GNUNET_TESTBED_StatisticsIterator) (void *cls, | ||
1323 | const struct GNUNET_TESTBED_Peer *peer, | ||
1324 | const char *subsystem, | ||
1325 | const char *name, | ||
1326 | uint64_t value, | ||
1327 | int is_persistent); | ||
1328 | |||
1329 | |||
1330 | /** | ||
1331 | * Convenience method that iterates over all (running) peers | ||
1332 | * and retrieves all statistics from each peer. | ||
1333 | * | ||
1334 | * @param num_peers number of peers to iterate over | ||
1335 | * @param peers array of peers to iterate over | ||
1336 | * @param subsystem limit to the specified subsystem, NULL for all subsystems | ||
1337 | * @param name name of the statistic value, NULL for all values | ||
1338 | * @param proc processing function for each statistic retrieved | ||
1339 | * @param cont continuation to call once call is completed. The completion of this | ||
1340 | * operation is *ONLY* signalled through this callback -- no | ||
1341 | * GNUNET_TESTBED_ET_OPERATION_FINISHED is generated | ||
1342 | * @param cls closure to pass to proc and cont | ||
1343 | * @return operation handle to cancel the operation | ||
1344 | */ | ||
1345 | struct GNUNET_TESTBED_Operation * | ||
1346 | GNUNET_TESTBED_get_statistics (unsigned int num_peers, | ||
1347 | struct GNUNET_TESTBED_Peer **peers, | ||
1348 | const char *subsystem, const char *name, | ||
1349 | GNUNET_TESTBED_StatisticsIterator proc, | ||
1350 | GNUNET_TESTBED_OperationCompletionCallback cont, | ||
1351 | void *cls); | ||
1352 | |||
1353 | |||
1354 | /** | ||
1355 | * Return the index of the peer inside of the total peer array, | ||
1356 | * aka. the peer's "unique ID". | ||
1357 | * | ||
1358 | * @param peer Peer handle. | ||
1359 | * | ||
1360 | * @return The peer's unique ID. | ||
1361 | */ | ||
1362 | uint32_t | ||
1363 | GNUNET_TESTBED_get_index (const struct GNUNET_TESTBED_Peer *peer); | ||
1364 | |||
1365 | |||
1366 | /** | ||
1367 | * Handle for testbed run helper functions | ||
1368 | */ | ||
1369 | struct GNUNET_TESTBED_RunHandle; | ||
1370 | |||
1371 | |||
1372 | /** | ||
1373 | * Signature of a main function for a testcase. | ||
1374 | * | ||
1375 | * @param cls closure | ||
1376 | * @param h the run handle | ||
1377 | * @param num_peers number of peers in 'peers' | ||
1378 | * @param peers handle to peers run in the testbed. NULL upon timeout (see | ||
1379 | * GNUNET_TESTBED_test_run()). | ||
1380 | * @param links_succeeded the number of overlay link connection attempts that | ||
1381 | * succeeded | ||
1382 | * @param links_failed the number of overlay link connection attempts that | ||
1383 | * failed | ||
1384 | * @see GNUNET_TESTBED_test_run() | ||
1385 | */ | ||
1386 | typedef void | ||
1387 | (*GNUNET_TESTBED_TestMaster)(void *cls, | ||
1388 | struct GNUNET_TESTBED_RunHandle *h, | ||
1389 | unsigned int num_peers, | ||
1390 | struct GNUNET_TESTBED_Peer **peers, | ||
1391 | unsigned int links_succeeded, | ||
1392 | unsigned int links_failed); | ||
1393 | |||
1394 | |||
1395 | /** | ||
1396 | * Convenience method for running a testbed with | ||
1397 | * a single call. Underlay and overlay topology | ||
1398 | * are configured using the "UNDERLAY" and "OVERLAY" | ||
1399 | * options in the "[testbed]" section of the configuration\ | ||
1400 | * (with possible options given in "UNDERLAY_XXX" and/or | ||
1401 | * "OVERLAY_XXX"). | ||
1402 | * | ||
1403 | * The test_master callback will be called once the testbed setup is finished or | ||
1404 | * upon a timeout. This timeout is given through the configuration file by | ||
1405 | * setting the option "SETUP_TIMEOUT" in "[TESTBED]" section. | ||
1406 | * | ||
1407 | * The testbed is to be terminated using a call to | ||
1408 | * "GNUNET_SCHEDULER_shutdown". | ||
1409 | * | ||
1410 | * @param host_filename name of the file with the 'hosts', NULL | ||
1411 | * to run everything on 'localhost' | ||
1412 | * @param cfg configuration to use (for testbed, controller and peers) | ||
1413 | * @param num_peers number of peers to start; FIXME: maybe put that ALSO into | ||
1414 | * cfg?; should be greater than 0 | ||
1415 | * @param event_mask bit mask with set of events to call 'cc' for; | ||
1416 | * or-ed values of "1LL" shifted by the | ||
1417 | * respective 'enum GNUNET_TESTBED_EventType' | ||
1418 | * (e.g. "(1LL << GNUNET_TESTBED_ET_CONNECT) || ...") | ||
1419 | * @param cc controller callback to invoke on events; This callback is called | ||
1420 | * for all peer start events even if GNUNET_TESTBED_ET_PEER_START isn't | ||
1421 | * set in the event_mask as this is the only way get access to the | ||
1422 | * handle of each peer | ||
1423 | * @param cc_cls closure for cc | ||
1424 | * @param test_master this callback will be called once the test is ready or | ||
1425 | * upon timeout | ||
1426 | * @param test_master_cls closure for 'test_master'. | ||
1427 | */ | ||
1428 | void | ||
1429 | GNUNET_TESTBED_run (const char *host_filename, | ||
1430 | const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
1431 | unsigned int num_peers, | ||
1432 | uint64_t event_mask, | ||
1433 | GNUNET_TESTBED_ControllerCallback cc, | ||
1434 | void *cc_cls, | ||
1435 | GNUNET_TESTBED_TestMaster test_master, | ||
1436 | void *test_master_cls); | ||
1437 | |||
1438 | |||
1439 | /** | ||
1440 | * Convenience method for running a "simple" test on the local system | ||
1441 | * with a single call from 'main'. Underlay and overlay topology are | ||
1442 | * configured using the "UNDERLAY" and "OVERLAY" options in the | ||
1443 | * "[TESTBED]" section of the configuration (with possible options | ||
1444 | * given in "UNDERLAY_XXX" and/or "OVERLAY_XXX"). | ||
1445 | * | ||
1446 | * The test_master callback will be called once the testbed setup is finished or | ||
1447 | * upon a timeout. This timeout is given through the configuration file by | ||
1448 | * setting the option "SETUP_TIMEOUT" in "[TESTBED]" section. | ||
1449 | * | ||
1450 | * The test is to be terminated using a call to | ||
1451 | * "GNUNET_SCHEDULER_shutdown". If starting the test fails, | ||
1452 | * the program is stopped without 'master' ever being run. | ||
1453 | * | ||
1454 | * NOTE: this function should be called from 'main', NOT from | ||
1455 | * within a GNUNET_SCHEDULER-loop. This function will initialize | ||
1456 | * the scheduler loop, the testbed and then pass control to | ||
1457 | * 'master'. | ||
1458 | * | ||
1459 | * @param testname name of the testcase (to configure logging, etc.) | ||
1460 | * @param cfg_filename configuration filename to use | ||
1461 | * (for testbed, controller and peers) | ||
1462 | * @param num_peers number of peers to start; should be greter than 0 | ||
1463 | * @param event_mask bit mask with set of events to call 'cc' for; | ||
1464 | * or-ed values of "1LL" shifted by the | ||
1465 | * respective 'enum GNUNET_TESTBED_EventType' | ||
1466 | * (e.g. "(1LL << GNUNET_TESTBED_ET_CONNECT) || ...") | ||
1467 | * @param cc controller callback to invoke on events; This callback is called | ||
1468 | * for all peer start events even if #GNUNET_TESTBED_ET_PEER_START isn't | ||
1469 | * set in the event_mask as this is the only way get access to the | ||
1470 | * handle of each peer | ||
1471 | * @param cc_cls closure for @a cc | ||
1472 | * @param test_master this callback will be called once the test is ready or | ||
1473 | * upon timeout | ||
1474 | * @param test_master_cls closure for @a test_master. | ||
1475 | * @return #GNUNET_SYSERR on error, #GNUNET_OK on success | ||
1476 | */ | ||
1477 | int | ||
1478 | GNUNET_TESTBED_test_run (const char *testname, | ||
1479 | const char *cfg_filename, | ||
1480 | unsigned int num_peers, | ||
1481 | uint64_t event_mask, | ||
1482 | GNUNET_TESTBED_ControllerCallback cc, | ||
1483 | void *cc_cls, | ||
1484 | GNUNET_TESTBED_TestMaster test_master, | ||
1485 | void *test_master_cls); | ||
1486 | |||
1487 | |||
1488 | /** | ||
1489 | * Obtain handle to the master controller from a testbed run. The handle | ||
1490 | * returned should not be disconnected. | ||
1491 | * | ||
1492 | * @param h the testbed run handle | ||
1493 | * @return handle to the master controller | ||
1494 | */ | ||
1495 | struct GNUNET_TESTBED_Controller * | ||
1496 | GNUNET_TESTBED_run_get_controller_handle (struct GNUNET_TESTBED_RunHandle *h); | ||
1497 | |||
1498 | |||
1499 | /** | ||
1500 | * Opaque handle for barrier | ||
1501 | */ | ||
1502 | struct GNUNET_TESTBED_Barrier; | ||
1503 | |||
1504 | |||
1505 | /** | ||
1506 | * Status of a barrier | ||
1507 | */ | ||
1508 | enum GNUNET_TESTBED_BarrierStatus | ||
1509 | { | ||
1510 | /** | ||
1511 | * Barrier initialised successfully | ||
1512 | */ | ||
1513 | GNUNET_TESTBED_BARRIERSTATUS_INITIALISED = 1, | ||
1514 | |||
1515 | /** | ||
1516 | * Barrier is crossed | ||
1517 | */ | ||
1518 | GNUNET_TESTBED_BARRIERSTATUS_CROSSED, | ||
1519 | |||
1520 | /** | ||
1521 | * Error status | ||
1522 | */ | ||
1523 | GNUNET_TESTBED_BARRIERSTATUS_ERROR, | ||
1524 | }; | ||
1525 | |||
1526 | |||
1527 | /** | ||
1528 | * Functions of this type are to be given as callback argument to | ||
1529 | * GNUNET_TESTBED_barrier_init(). The callback will be called when status | ||
1530 | * information is available for the barrier. | ||
1531 | * | ||
1532 | * @param cls the closure given to GNUNET_TESTBED_barrier_init() | ||
1533 | * @param name the name of the barrier | ||
1534 | * @param barrier the barrier handle | ||
1535 | * @param status status of the barrier. The barrier is removed once it has been | ||
1536 | * crossed or an error occurs while processing it. Therefore it is | ||
1537 | * invalid to call GNUNET_TESTBED_barrier_cancel() on a crossed or | ||
1538 | * errored barrier. | ||
1539 | * @param emsg if the status were to be #GNUNET_SYSERR, this parameter has the | ||
1540 | * error message | ||
1541 | */ | ||
1542 | typedef void | ||
1543 | (*GNUNET_TESTBED_barrier_status_cb) (void *cls, | ||
1544 | const char *name, | ||
1545 | struct GNUNET_TESTBED_Barrier *barrier, | ||
1546 | enum GNUNET_TESTBED_BarrierStatus status, | ||
1547 | const char *emsg); | ||
1548 | |||
1549 | |||
1550 | /** | ||
1551 | * Initialise a barrier and call the given callback when the required percentage | ||
1552 | * of peers (quorum) reach the barrier. | ||
1553 | * | ||
1554 | * @param controller the handle to the controller | ||
1555 | * @param name identification name of the barrier | ||
1556 | * @param quorum the percentage of peers that is required to reach the barrier. | ||
1557 | * Peers signal reaching a barrier by calling | ||
1558 | * GNUNET_TESTBED_barrier_reached(). | ||
1559 | * @param cb the callback to call when the barrier is reached or upon error. | ||
1560 | * Cannot be NULL. | ||
1561 | * @param cb_cls closure for @a cb | ||
1562 | * @return barrier handle | ||
1563 | */ | ||
1564 | struct GNUNET_TESTBED_Barrier * | ||
1565 | GNUNET_TESTBED_barrier_init (struct GNUNET_TESTBED_Controller *controller, | ||
1566 | const char *name, | ||
1567 | unsigned int quorum, | ||
1568 | GNUNET_TESTBED_barrier_status_cb cb, | ||
1569 | void *cb_cls); | ||
1570 | |||
1571 | |||
1572 | /** | ||
1573 | * Cancel a barrier. | ||
1574 | * | ||
1575 | * @param barrier the barrier handle | ||
1576 | */ | ||
1577 | void | ||
1578 | GNUNET_TESTBED_barrier_cancel (struct GNUNET_TESTBED_Barrier *barrier); | ||
1579 | |||
1580 | |||
1581 | /** | ||
1582 | * Opaque handle for barrier wait | ||
1583 | */ | ||
1584 | struct GNUNET_TESTBED_BarrierWaitHandle; | ||
1585 | |||
1586 | |||
1587 | /** | ||
1588 | * Functions of this type are to be given as acallback argument to | ||
1589 | * GNUNET_TESTBED_barrier_wait(). The callback will be called when the barrier | ||
1590 | * corresponding given in GNUNET_TESTBED_barrier_wait() is crossed or cancelled. | ||
1591 | * | ||
1592 | * @param cls closure pointer given to GNUNET_TESTBED_barrier_wait() | ||
1593 | * @param name the barrier name | ||
1594 | * @param status #GNUNET_SYSERR in case of error while waiting for the barrier; | ||
1595 | * #GNUNET_OK if the barrier is crossed | ||
1596 | */ | ||
1597 | typedef void | ||
1598 | (*GNUNET_TESTBED_barrier_wait_cb) (void *cls, | ||
1599 | const char *name, | ||
1600 | int status); | ||
1601 | |||
1602 | |||
1603 | /** | ||
1604 | * Wait for a barrier to be crossed. This function should be called by the | ||
1605 | * peers which have been started by the testbed. If the peer is not started by | ||
1606 | * testbed this function may return error | ||
1607 | * | ||
1608 | * @param name the name of the barrier | ||
1609 | * @param cb the barrier wait callback | ||
1610 | * @param cls the closure for the above callback | ||
1611 | * @return barrier wait handle which can be used to cancel the waiting at | ||
1612 | * anytime before the callback is called. NULL upon error. | ||
1613 | */ | ||
1614 | struct GNUNET_TESTBED_BarrierWaitHandle * | ||
1615 | GNUNET_TESTBED_barrier_wait (const char *name, | ||
1616 | GNUNET_TESTBED_barrier_wait_cb cb, | ||
1617 | void *cls); | ||
1618 | |||
1619 | |||
1620 | /** | ||
1621 | * Cancel a barrier wait handle. Should not be called in or after the callback | ||
1622 | * given to GNUNET_TESTBED_barrier_wait() has been called. | ||
1623 | * | ||
1624 | * @param h the barrier wait handle | ||
1625 | */ | ||
1626 | void | ||
1627 | GNUNET_TESTBED_barrier_wait_cancel (struct GNUNET_TESTBED_BarrierWaitHandle *h); | ||
1628 | |||
1629 | |||
1630 | /** | ||
1631 | * Model for configuring underlay links of a peer | ||
1632 | * @ingroup underlay | ||
1633 | */ | ||
1634 | struct GNUNET_TESTBED_UnderlayLinkModel; | ||
1635 | |||
1636 | |||
1637 | /** | ||
1638 | * The type of GNUNET_TESTBED_UnderlayLinkModel | ||
1639 | * @ingroup underlay | ||
1640 | */ | ||
1641 | enum GNUNET_TESTBED_UnderlayLinkModelType | ||
1642 | { | ||
1643 | /** | ||
1644 | * The model is based on white listing of peers to which underlay connections | ||
1645 | * are permitted. Underlay connections to all other peers will not be | ||
1646 | * permitted. | ||
1647 | */ | ||
1648 | GNUNET_TESTBED_UNDERLAYLINKMODELTYPE_BLACKLIST, | ||
1649 | |||
1650 | /** | ||
1651 | * The model is based on black listing of peers to which underlay connections | ||
1652 | * are not permitted. Underlay connections to all other peers will be | ||
1653 | * permitted | ||
1654 | */ | ||
1655 | GNUNET_TESTBED_UNDERLAYLINKMODELTYPE_WHITELIST | ||
1656 | }; | ||
1657 | |||
1658 | |||
1659 | /** | ||
1660 | * Create a GNUNET_TESTBED_UnderlayLinkModel for the given peer. A peer can | ||
1661 | * have ONLY ONE model and it can be either a blacklist or whitelist based one. | ||
1662 | * | ||
1663 | * @ingroup underlay | ||
1664 | * @param peer the peer for which the model has to be created | ||
1665 | * @param type the type of the model | ||
1666 | * @return the model | ||
1667 | */ | ||
1668 | struct GNUNET_TESTBED_UnderlayLinkModel * | ||
1669 | GNUNET_TESTBED_underlaylinkmodel_create (struct GNUNET_TESTBED_Peer *peer, | ||
1670 | enum | ||
1671 | GNUNET_TESTBED_UnderlayLinkModelType | ||
1672 | type); | ||
1673 | |||
1674 | |||
1675 | /** | ||
1676 | * Add a peer to the given model. Underlay connections to the given peer will | ||
1677 | * be permitted if the model is whitelist based; otherwise they will not be | ||
1678 | * permitted. | ||
1679 | * | ||
1680 | * @ingroup underlay | ||
1681 | * @param model the model | ||
1682 | * @param peer the peer to add | ||
1683 | */ | ||
1684 | void | ||
1685 | GNUNET_TESTBED_underlaylinkmodel_add_peer (struct | ||
1686 | GNUNET_TESTBED_UnderlayLinkModel * | ||
1687 | model, | ||
1688 | struct GNUNET_TESTBED_Peer *peer); | ||
1689 | |||
1690 | |||
1691 | /** | ||
1692 | * Set the metrics for a link to the given peer in the underlay model. The link | ||
1693 | * SHOULD be permittable according to the given model. | ||
1694 | * | ||
1695 | * @ingroup underlay | ||
1696 | * @param model the model | ||
1697 | * @param peer the other end peer of the link | ||
1698 | * @param latency latency of the link in microseconds | ||
1699 | * @param loss data loss of the link expressed as a percentage | ||
1700 | * @param bandwidth bandwidth of the link in kilobytes per second [kB/s] | ||
1701 | */ | ||
1702 | void | ||
1703 | GNUNET_TESTBED_underlaylinkmodel_set_link (struct | ||
1704 | GNUNET_TESTBED_UnderlayLinkModel * | ||
1705 | model, | ||
1706 | struct GNUNET_TESTBED_Peer *peer, | ||
1707 | uint32_t latency, | ||
1708 | uint32_t loss, | ||
1709 | uint32_t bandwidth); | ||
1710 | |||
1711 | |||
1712 | /** | ||
1713 | * Commit the model. The model is freed in this function(!). | ||
1714 | * | ||
1715 | * @ingroup underlay | ||
1716 | * @param model the model to commit | ||
1717 | */ | ||
1718 | void | ||
1719 | GNUNET_TESTBED_underlaylinkmodel_commit (struct | ||
1720 | GNUNET_TESTBED_UnderlayLinkModel *model); | ||
1721 | |||
1722 | |||
1723 | /** | ||
1724 | * Free the resources of the model. Use this function only if the model has not | ||
1725 | * be committed and has to be unallocated. The peer can then have another model | ||
1726 | * created. | ||
1727 | * | ||
1728 | * @ingroup underlay | ||
1729 | * @param model the model to unallocate | ||
1730 | */ | ||
1731 | void | ||
1732 | GNUNET_TESTBED_underlaylinkmodel_free (struct | ||
1733 | GNUNET_TESTBED_UnderlayLinkModel *model); | ||
1734 | |||
1735 | |||
1736 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
1737 | { | ||
1738 | #endif | ||
1739 | |||
1740 | |||
1741 | #ifdef __cplusplus | ||
1742 | } | ||
1743 | #endif | ||
1744 | |||
1745 | #endif | ||
1746 | |||
1747 | /** @} */ /* end of group */ | ||