diff options
author | Christian Grothoff <christian@grothoff.org> | 2009-06-18 02:21:46 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2009-06-18 02:21:46 +0000 |
commit | d5e417f094cac294282deafe46409342796263c6 (patch) | |
tree | 0f050bb7602193a9e829d2727171fbccf9b03e6a /src/include | |
parent | c3ca725eb3c48d1f1726d3abd2c9816af924d222 (diff) | |
download | gnunet-d5e417f094cac294282deafe46409342796263c6.tar.gz gnunet-d5e417f094cac294282deafe46409342796263c6.zip |
testing-design
Diffstat (limited to 'src/include')
-rw-r--r-- | src/include/Makefile.am | 1 | ||||
-rw-r--r-- | src/include/gnunet_testing_lib.h | 343 |
2 files changed, 344 insertions, 0 deletions
diff --git a/src/include/Makefile.am b/src/include/Makefile.am index bc832c444..2a0ef3729 100644 --- a/src/include/Makefile.am +++ b/src/include/Makefile.am | |||
@@ -37,6 +37,7 @@ gnunetinclude_HEADERS = \ | |||
37 | gnunet_signatures.h \ | 37 | gnunet_signatures.h \ |
38 | gnunet_statistics_service.h \ | 38 | gnunet_statistics_service.h \ |
39 | gnunet_strings_lib.h \ | 39 | gnunet_strings_lib.h \ |
40 | gnunet_testing_lib.h \ | ||
40 | gnunet_time_lib.h \ | 41 | gnunet_time_lib.h \ |
41 | gnunet_transport_service.h \ | 42 | gnunet_transport_service.h \ |
42 | gnunet_upnp_service.h \ | 43 | gnunet_upnp_service.h \ |
diff --git a/src/include/gnunet_testing_lib.h b/src/include/gnunet_testing_lib.h new file mode 100644 index 000000000..f0e7d34a0 --- /dev/null +++ b/src/include/gnunet_testing_lib.h | |||
@@ -0,0 +1,343 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet | ||
3 | (C) 2008, 2009 Christian Grothoff (and other contributing authors) | ||
4 | |||
5 | GNUnet is free software; you can redistribute it and/or modify | ||
6 | it under the terms of the GNU General Public License as published | ||
7 | by the Free Software Foundation; either version 2, or (at your | ||
8 | option) any later version. | ||
9 | |||
10 | GNUnet is distributed in the hope that it will be useful, but | ||
11 | WITHOUT ANY WARRANTY; without even the implied warranty of | ||
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
13 | General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU General Public License | ||
16 | along with GNUnet; see the file COPYING. If not, write to the | ||
17 | Free Software Foundation, Inc., 59 Temple Place - Suite 330, | ||
18 | Boston, MA 02111-1307, USA. | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @file include/gnunet_testing_lib.h | ||
23 | * @brief convenience API for writing testcases for GNUnet | ||
24 | * Many testcases need to start and stop gnunetd, | ||
25 | * and this library is supposed to make that easier | ||
26 | * for TESTCASES. Normal programs should always | ||
27 | * use functions from gnunet_{util,arm}_lib.h. This API is | ||
28 | * ONLY for writing testcases! | ||
29 | * @author Christian Grothoff | ||
30 | */ | ||
31 | |||
32 | #ifndef GNUNET_TESTING_LIB_H | ||
33 | #define GNUNET_TESTING_LIB_H | ||
34 | |||
35 | #include "gnunet_util_lib.h" | ||
36 | |||
37 | #ifdef __cplusplus | ||
38 | extern "C" | ||
39 | { | ||
40 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
41 | } | ||
42 | #endif | ||
43 | #endif | ||
44 | |||
45 | |||
46 | |||
47 | /** | ||
48 | * Handle for a GNUnet daemon (technically a set of | ||
49 | * daemons; the handle is really for the master ARM | ||
50 | * daemon) started by the testing library. | ||
51 | */ | ||
52 | struct GNUNET_TESTING_Daemon; | ||
53 | |||
54 | |||
55 | /** | ||
56 | * Prototype of a function that will be called whenever | ||
57 | * a daemon was started by the testing library. | ||
58 | * | ||
59 | * @param cls closure | ||
60 | * @param id identifier for the daemon, NULL on error | ||
61 | * @param d handle to the daemon, NULL if starting the daemon failed | ||
62 | */ | ||
63 | typedef void (*GNUNET_TESTING_NotifyDaemonRunning)(void *cls, | ||
64 | const struct GNUNET_PeerIdentity *id, | ||
65 | struct GNUNET_TESTING_Daemon *d); | ||
66 | |||
67 | |||
68 | /** | ||
69 | * Starts a GNUnet daemon. | ||
70 | * | ||
71 | * @param service_home directory to use as the service home directory | ||
72 | * @param transports transport services that should be loaded | ||
73 | * @param applications application services and daemons that should be started | ||
74 | * @param port_offset offset to add to all ports for all services | ||
75 | * @param hostname name of the machine where to run GNUnet | ||
76 | * (use NULL for localhost). | ||
77 | * @param cb function to call with the result | ||
78 | * @param cb_cls closure for cb | ||
79 | */ | ||
80 | void | ||
81 | GNUNET_TESTING_daemon_start (struct GNUNET_SCHEDULER_Handle *sched, | ||
82 | struct GNUNET_CONFIGURATION_Handle *cfg, | ||
83 | const char *service_home, | ||
84 | const char *transports, | ||
85 | const char *applications, | ||
86 | uint16_t port_offset, | ||
87 | const char *hostname, | ||
88 | GNUNET_TESTING_NotifyDaemonRunning cb, | ||
89 | void *cb_cls); | ||
90 | |||
91 | |||
92 | /** | ||
93 | * Prototype of a function that will be called when a | ||
94 | * particular operation was completed the testing library. | ||
95 | * | ||
96 | * @param cls closure | ||
97 | * @param success GNUNET_YES on success | ||
98 | */ | ||
99 | typedef void (*GNUNET_TESTING_NotifyCompletion)(void *cls, | ||
100 | int success); | ||
101 | |||
102 | |||
103 | /** | ||
104 | * Stops a GNUnet daemon. | ||
105 | * | ||
106 | * @param d the daemon that should be stopped | ||
107 | * @param cb function called once the daemon was stopped | ||
108 | * @param cb_cls closure for cb | ||
109 | */ | ||
110 | void GNUNET_TESTING_daemon_stop (struct GNUNET_TESTING_Daemon *d, | ||
111 | GNUNET_TESTING_NotifyCompletion cb, | ||
112 | void * cb_cls); | ||
113 | |||
114 | |||
115 | |||
116 | /** | ||
117 | * Establish a connection between two GNUnet daemons. | ||
118 | * | ||
119 | * @param d1 handle for the first daemon | ||
120 | * @param d2 handle for the second daemon | ||
121 | * @param cb function to call at the end | ||
122 | * @param cb_cls closure for cb | ||
123 | */ | ||
124 | void GNUNET_TESTING_daemons_connect (struct GNUNET_TESTING_Daemon *d1, | ||
125 | struct GNUNET_TESTING_Daemon *d2, | ||
126 | GNUNET_TESTING_NotifyCompletion cb, | ||
127 | void *cb_cls); | ||
128 | |||
129 | |||
130 | |||
131 | /** | ||
132 | * Start count gnunetd processes with the same set of | ||
133 | * transports and applications. The port numbers will | ||
134 | * be computed by adding delta each time (zero | ||
135 | * times for the first peer). | ||
136 | * | ||
137 | * @param total number of daemons to start | ||
138 | * @param service_home_prefix path to use as the prefix for the home of the services | ||
139 | * @param transports which transports should all peers use | ||
140 | * @param applications which applications should be used? | ||
141 | * @param timeout how long is this allowed to take? | ||
142 | * @param cb function to call on each daemon that was started | ||
143 | * @param cb_cls closure for cb | ||
144 | * @param cbe function to call at the end | ||
145 | * @param cbe_cls closure for cbe | ||
146 | * @param hostname where to run the peers; can be NULL (to run | ||
147 | * everything on localhost). Additional | ||
148 | * hosts can be specified using a NULL-terminated list of | ||
149 | * varargs, hosts will then be used round-robin from that | ||
150 | * list. | ||
151 | */ | ||
152 | void | ||
153 | GNUNET_TESTING_daemons_start (struct GNUNET_SCHEDULER_Handle *sched, | ||
154 | struct GNUNET_CONFIGURATION_Handle *cfg, | ||
155 | unsigned int total, | ||
156 | const char *service_home_prefix, | ||
157 | const char *transports, | ||
158 | const char *applications, | ||
159 | GNUNET_TESTING_NotifyDaemonRunning cb, | ||
160 | void *cb_cls, | ||
161 | GNUNET_TESTING_NotifyCompletion cbe, | ||
162 | void *cbe_cls, | ||
163 | const char *hostname, | ||
164 | ...); | ||
165 | |||
166 | |||
167 | /** | ||
168 | * Handle to an entire testbed of GNUnet peers. | ||
169 | */ | ||
170 | struct GNUNET_TESTING_Testbed; | ||
171 | |||
172 | /** | ||
173 | * Prototype of a function that will be called when | ||
174 | * a testbed is being created. | ||
175 | * | ||
176 | * @param cls closure | ||
177 | * @param tb NULL on error | ||
178 | */ | ||
179 | typedef void (*GNUNET_TESTING_NotifyTestbedRunning)(void *cls, | ||
180 | struct GNUNET_TESTING_Testbed *tb); | ||
181 | |||
182 | |||
183 | /** | ||
184 | * Topologies supported for testbeds. | ||
185 | */ | ||
186 | enum GNUNET_TESTING_Topology | ||
187 | { | ||
188 | /** | ||
189 | * A clique (everyone connected to everyone else). | ||
190 | */ | ||
191 | GNUNET_TESTING_TOPOLOGY_CLIQUE, | ||
192 | |||
193 | /** | ||
194 | * Small-world network (2d torus plus random links). | ||
195 | */ | ||
196 | GNUNET_TESTING_TOPOLOGY_SMALL_WORLD, | ||
197 | |||
198 | /** | ||
199 | * Ring topology. | ||
200 | */ | ||
201 | GNUNET_TESTING_TOPOLOGY_RING, | ||
202 | |||
203 | /** | ||
204 | * 2-d torus. | ||
205 | */ | ||
206 | GNUNET_TESTING_TOPOLOGY_2D_TORUS, | ||
207 | |||
208 | /** | ||
209 | * Random graph. | ||
210 | */ | ||
211 | GNUNET_TESTING_TOPOLOGY_ERDOS_RENYI, | ||
212 | |||
213 | /** | ||
214 | * All peers are disconnected. | ||
215 | */ | ||
216 | GNUNET_TESTING_TOPOLOGY_NONE | ||
217 | }; | ||
218 | |||
219 | |||
220 | |||
221 | /** | ||
222 | * Start count GNUnet daemons with a particular | ||
223 | * topology. | ||
224 | * | ||
225 | * @param size number of peers the testbed should have | ||
226 | * @param topology desired topology (enforced via F2F) | ||
227 | * @param service_home_prefix path to use as the prefix for the home of the services | ||
228 | * @param transports which transports should all peers use | ||
229 | * @param applications which applications should be used? | ||
230 | * @param timeout how long is this allowed to take? | ||
231 | * @param cb function to call on each daemon that was started | ||
232 | * @param cb_cls closure for cb | ||
233 | * @param cte function to call at the end | ||
234 | * @param cte_cls closure for cbe | ||
235 | * @param hostname where to run the peers; can be NULL (to run | ||
236 | * everything on localhost). Additional | ||
237 | * hosts can be specified using a NULL-terminated list of | ||
238 | * varargs, hosts will then be used round-robin from that | ||
239 | * list. | ||
240 | */ | ||
241 | void | ||
242 | GNUNET_TESTING_testbed_start (struct GNUNET_SCHEDULER_Handle *sched, | ||
243 | struct GNUNET_CONFIGURATION_Handle *cfg, | ||
244 | unsigned int size, | ||
245 | enum GNUNET_TESTING_Topology topology, | ||
246 | const char *service_home_prefix, | ||
247 | const char *transports, | ||
248 | const char *applications, | ||
249 | GNUNET_TESTING_NotifyDaemonRunning cb, | ||
250 | void *cb_cls, | ||
251 | GNUNET_TESTING_NotifyTestbedRunning cte, | ||
252 | void *cte_cls, | ||
253 | const char *hostname, | ||
254 | ...); | ||
255 | |||
256 | |||
257 | /** | ||
258 | * Start count GNUnet daemons with a particular | ||
259 | * topology. | ||
260 | * | ||
261 | * @param size number of peers the testbed should have | ||
262 | * @param topology desired topology (enforced via F2F) | ||
263 | * @param service_home_prefix path to use as the prefix for the home of the services | ||
264 | * @param transports which transports should all peers use | ||
265 | * @param applications which applications should be used? | ||
266 | * @param timeout how long is this allowed to take? | ||
267 | * @param cb function to call on each daemon that was started | ||
268 | * @param cb_cls closure for cb | ||
269 | * @param cte function to call at the end | ||
270 | * @param cte_cls closure for cbe | ||
271 | * @param hostname where to run the peers; can be NULL (to run | ||
272 | * everything on localhost). | ||
273 | * @param va Additional hosts can be specified using a NULL-terminated list of | ||
274 | * varargs, hosts will then be used round-robin from that | ||
275 | * list; va only contains anything if hostname != NULL. | ||
276 | */ | ||
277 | void | ||
278 | GNUNET_TESTING_testbed_start_va (struct GNUNET_SCHEDULER_Handle *sched, | ||
279 | struct GNUNET_CONFIGURATION_Handle *cfg, | ||
280 | unsigned int size, | ||
281 | enum GNUNET_TESTING_Topology topology, | ||
282 | const char *service_home_prefix, | ||
283 | const char *transports, | ||
284 | const char *applications, | ||
285 | GNUNET_TESTING_NotifyDaemonRunning cb, | ||
286 | void *cb_cls, | ||
287 | GNUNET_TESTING_NotifyTestbedRunning cte, | ||
288 | void *cte_cls, | ||
289 | const char *hostname, | ||
290 | va_list ap); | ||
291 | |||
292 | |||
293 | /** | ||
294 | * Stop all of the daemons started with the start function. | ||
295 | * | ||
296 | * @param tb handle for the testbed | ||
297 | * @param cb function to call at the end | ||
298 | * @param cb_cls closure for cb | ||
299 | */ | ||
300 | void | ||
301 | GNUNET_TESTING_testbed_stop (struct GNUNET_TESTING_Testbed *tb, | ||
302 | GNUNET_TESTING_NotifyCompletion cb, | ||
303 | void *cb_cls ); | ||
304 | |||
305 | |||
306 | |||
307 | /** | ||
308 | * Simulate churn in the testbed by stopping some peers (and possibly | ||
309 | * re-starting others if churn is called multiple times). This | ||
310 | * function can only be used to create leave-join churn (peers "never" | ||
311 | * leave for good). First "voff" random peers that are currently | ||
312 | * online will be taken offline; then "von" random peers that are then | ||
313 | * offline will be put back online. No notifications will be | ||
314 | * generated for any of these operations except for the callback upon | ||
315 | * completion. Note that the implementation is at liberty to keep | ||
316 | * the ARM service itself (but none of the other services or daemons) | ||
317 | * running even though the "peer" is being varied offline. | ||
318 | * | ||
319 | * @param tb handle for the testbed | ||
320 | * @param voff number of peers that should go offline | ||
321 | * @param von number of peers that should come back online; | ||
322 | * must be zero on first call (since "testbed_start" | ||
323 | * always starts all of the peers) | ||
324 | * @param cb function to call at the end | ||
325 | * @param cb_cls closure for cb | ||
326 | */ | ||
327 | void | ||
328 | GNUNET_TESTING_testbed_churn (struct GNUNET_TESTING_Testbed *tb, | ||
329 | unsigned int voff, | ||
330 | unsigned int von, | ||
331 | GNUNET_TESTING_NotifyCompletion cb, | ||
332 | void *cb_cls); | ||
333 | |||
334 | |||
335 | |||
336 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
337 | { | ||
338 | #endif | ||
339 | #ifdef __cplusplus | ||
340 | } | ||
341 | #endif | ||
342 | |||
343 | #endif | ||