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