diff options
author | Christian Grothoff <christian@grothoff.org> | 2021-04-06 10:37:29 +0200 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2021-04-06 10:37:29 +0200 |
commit | efb63d91616d5587bf99efab80c85afd205fc1bd (patch) | |
tree | f685c38a50d8d5451acbde1328becbfa06a27fe2 /src/include/gnunet_testing_ng_lib.h | |
parent | 45720bde1c56c414fec8a1c3d5775208c3b32139 (diff) | |
download | gnunet-efb63d91616d5587bf99efab80c85afd205fc1bd.tar.gz gnunet-efb63d91616d5587bf99efab80c85afd205fc1bd.zip |
-DESIGN: add various suggestions to gnunet_testing_ng_lib.h
Diffstat (limited to 'src/include/gnunet_testing_ng_lib.h')
-rw-r--r-- | src/include/gnunet_testing_ng_lib.h | 82 |
1 files changed, 74 insertions, 8 deletions
diff --git a/src/include/gnunet_testing_ng_lib.h b/src/include/gnunet_testing_ng_lib.h index c510ca334..951158ca4 100644 --- a/src/include/gnunet_testing_ng_lib.h +++ b/src/include/gnunet_testing_ng_lib.h | |||
@@ -28,7 +28,6 @@ | |||
28 | #define GNUNET_TESTING_NG_LIB_H | 28 | #define GNUNET_TESTING_NG_LIB_H |
29 | 29 | ||
30 | #include "gnunet_util_lib.h" | 30 | #include "gnunet_util_lib.h" |
31 | #include "gnunet_scheduler_lib.h" | ||
32 | 31 | ||
33 | 32 | ||
34 | /* ********************* Helper functions ********************* */ | 33 | /* ********************* Helper functions ********************* */ |
@@ -52,6 +51,9 @@ | |||
52 | * Global state of the interpreter, used by a command | 51 | * Global state of the interpreter, used by a command |
53 | * to access information about other commands. | 52 | * to access information about other commands. |
54 | */ | 53 | */ |
54 | // SUGGESTION: consider making this struct opaque (only known inside of libgnunettesting, | ||
55 | // say main loop and a few select commands, like next/fail/batch); + helper | ||
56 | // function to access 'cfg'? | ||
55 | struct GNUNET_TESTING_Interpreter | 57 | struct GNUNET_TESTING_Interpreter |
56 | { | 58 | { |
57 | 59 | ||
@@ -97,8 +99,7 @@ struct GNUNET_TESTING_Command | |||
97 | { | 99 | { |
98 | 100 | ||
99 | /** | 101 | /** |
100 | * Closure for all commands with command-specific context | 102 | * Closure for all commands with command-specific context information. |
101 | * information. | ||
102 | */ | 103 | */ |
103 | void *cls; | 104 | void *cls; |
104 | 105 | ||
@@ -115,6 +116,10 @@ struct GNUNET_TESTING_Command | |||
115 | * #GNUNET_TESTING_interpreter_next() or | 116 | * #GNUNET_TESTING_interpreter_next() or |
116 | * #GNUNET_TESTING_interpreter_fail(). | 117 | * #GNUNET_TESTING_interpreter_fail(). |
117 | * | 118 | * |
119 | * If this function creates some asynchronous activity, it should | ||
120 | * initialize @e finish to a function that can be used to wait for | ||
121 | * the asynchronous activity to terminate. | ||
122 | * | ||
118 | * @param cls closure | 123 | * @param cls closure |
119 | * @param cmd command being run | 124 | * @param cmd command being run |
120 | * @param i interpreter state | 125 | * @param i interpreter state |
@@ -124,6 +129,21 @@ struct GNUNET_TESTING_Command | |||
124 | const struct GNUNET_TESTING_Command *cmd, | 129 | const struct GNUNET_TESTING_Command *cmd, |
125 | struct GNUNET_TESTING_Interpreter *i); | 130 | struct GNUNET_TESTING_Interpreter *i); |
126 | 131 | ||
132 | /** | ||
133 | * Wait for any asynchronous execution of @e run to conclude, | ||
134 | * then call @a cont. Finish may only be called once per command. | ||
135 | * | ||
136 | * This member may be NULL if this command is a synchronous command, | ||
137 | * and also should be set to NULL once the command has finished. | ||
138 | * | ||
139 | * @param cont function to call upon completion, can be NULL | ||
140 | * @param cont_cls closure for @a cont | ||
141 | */ | ||
142 | // SUGGESTION (NEW!) | ||
143 | void | ||
144 | (*finish)(void *cls, | ||
145 | struct GNUNET_SCHEDULER_Task cont, | ||
146 | void *cont_cls); | ||
127 | 147 | ||
128 | /** | 148 | /** |
129 | * Clean up after the command. Run during forced termination | 149 | * Clean up after the command. Run during forced termination |
@@ -163,18 +183,41 @@ struct GNUNET_TESTING_Command | |||
163 | struct GNUNET_TIME_Absolute finish_time; | 183 | struct GNUNET_TIME_Absolute finish_time; |
164 | 184 | ||
165 | /** | 185 | /** |
166 | * When did we start the last request of this command? | 186 | * When did we start the last run of this command? Delta to @e finish_time |
167 | * Delta to @e finish_time gives the latency for the last | 187 | * gives the latency for the last successful run. Useful in case @e |
168 | * successful request. | 188 | * num_tries was positive and the command was run multiple times. In that |
189 | * case, the @e start_time gives the time when we first tried to run the | ||
190 | * command, so the difference between @e start_time and @e finish_time would | ||
191 | * be the time all of the @e num_tries took, while the delta to @e | ||
192 | * last_req_time is the time the last (successful) execution took. | ||
169 | */ | 193 | */ |
170 | struct GNUNET_TIME_Absolute last_req_time; | 194 | struct GNUNET_TIME_Absolute last_req_time; |
171 | 195 | ||
172 | /** | 196 | /** |
173 | * How often did we try to execute this command? (In case | 197 | * How often did we try to execute this command? (In case it is a request |
174 | * it is a request that is repated.) | 198 | * that is repated.) Note that a command must have some build-in retry |
199 | * mechanism for this value to be useful. | ||
175 | */ | 200 | */ |
176 | unsigned int num_tries; | 201 | unsigned int num_tries; |
177 | 202 | ||
203 | /** | ||
204 | * In case @e asynchronous_finish is true, how long should we wait for this | ||
205 | * command to complete? If @e finish did not complete after this amount of | ||
206 | * time, the interpreter will fail. Should be set generously to ensure | ||
207 | * tests do not fail on slow systems. | ||
208 | */ | ||
209 | // SUGGESTION (NEW): | ||
210 | struct GNUNET_TIME_Relative default_timeout; | ||
211 | |||
212 | /** | ||
213 | * If "true", the interpreter should not immediately call | ||
214 | * @e finish, even if @e finish is non-NULL. Otherwise, | ||
215 | * #TALER_TESTING_cmd_finish() must be used | ||
216 | * to ensure that a command actually completed. | ||
217 | */ | ||
218 | // SUGGESTION (NEW): | ||
219 | bool asynchronous_finish; | ||
220 | |||
178 | }; | 221 | }; |
179 | 222 | ||
180 | 223 | ||
@@ -228,6 +271,24 @@ GNUNET_TESTING_cmd_end (void); | |||
228 | 271 | ||
229 | 272 | ||
230 | /** | 273 | /** |
274 | * Create (synchronous) command that waits for another command to finish. | ||
275 | * If @a cmd_ref did not finish after @a timeout, this command will fail | ||
276 | * the test case. | ||
277 | * | ||
278 | * @param finish_label label for this command | ||
279 | * @param cmd_ref reference to a previous command which we should | ||
280 | * wait for (call `finish()` on) | ||
281 | * @param timeout how long to wait at most for @a cmd_ref to finish | ||
282 | * @return a finish-command. | ||
283 | */ | ||
284 | // SUGGESTION (NEW!) | ||
285 | const struct GNUNET_TESTING_Command * | ||
286 | TALER_TESTING_cmd_finish (const char *finish_label, | ||
287 | const char *cmd_ref, | ||
288 | struct GNUNET_TIME_Relative timeout); | ||
289 | |||
290 | |||
291 | /** | ||
231 | * Make the instruction pointer point to @a target_label | 292 | * Make the instruction pointer point to @a target_label |
232 | * only if @a counter is greater than zero. | 293 | * only if @a counter is greater than zero. |
233 | * | 294 | * |
@@ -331,6 +392,7 @@ GNUNET_TESTING_cmd_batch (const char *label, | |||
331 | * | 392 | * |
332 | * @return false if not, true if it is a batch command | 393 | * @return false if not, true if it is a batch command |
333 | */ | 394 | */ |
395 | // TODO: figure out if this needs to be exposed in the public API. | ||
334 | int | 396 | int |
335 | GNUNET_TESTING_cmd_is_batch (const struct GNUNET_TESTING_Command *cmd); | 397 | GNUNET_TESTING_cmd_is_batch (const struct GNUNET_TESTING_Command *cmd); |
336 | 398 | ||
@@ -340,14 +402,17 @@ GNUNET_TESTING_cmd_is_batch (const struct GNUNET_TESTING_Command *cmd); | |||
340 | * | 402 | * |
341 | * @param is interpreter state. | 403 | * @param is interpreter state. |
342 | */ | 404 | */ |
405 | // TODO: figure out if this needs to be exposed in the public API. | ||
343 | void | 406 | void |
344 | GNUNET_TESTING_cmd_batch_next (struct GNUNET_TESTING_Interpreter *is); | 407 | GNUNET_TESTING_cmd_batch_next (struct GNUNET_TESTING_Interpreter *is); |
345 | 408 | ||
409 | |||
346 | /** | 410 | /** |
347 | * Obtain what command the batch is at. | 411 | * Obtain what command the batch is at. |
348 | * | 412 | * |
349 | * @return cmd current batch command | 413 | * @return cmd current batch command |
350 | */ | 414 | */ |
415 | // TODO: figure out if this needs to be exposed in the public API. | ||
351 | struct GNUNET_TESTING_Command * | 416 | struct GNUNET_TESTING_Command * |
352 | GNUNET_TESTING_cmd_batch_get_current (const struct GNUNET_TESTING_Command *cmd); | 417 | GNUNET_TESTING_cmd_batch_get_current (const struct GNUNET_TESTING_Command *cmd); |
353 | 418 | ||
@@ -358,6 +423,7 @@ GNUNET_TESTING_cmd_batch_get_current (const struct GNUNET_TESTING_Command *cmd); | |||
358 | * @param cmd current batch command | 423 | * @param cmd current batch command |
359 | * @param new_ip where to move the IP | 424 | * @param new_ip where to move the IP |
360 | */ | 425 | */ |
426 | // TODO: figure out if this needs to be exposed in the public API. | ||
361 | void | 427 | void |
362 | GNUNET_TESTING_cmd_batch_set_current (const struct GNUNET_TESTING_Command *cmd, | 428 | GNUNET_TESTING_cmd_batch_set_current (const struct GNUNET_TESTING_Command *cmd, |
363 | unsigned int new_ip); | 429 | unsigned int new_ip); |