[gnunet] branch master updated: TESTING: Various notes on API

[gnunet]

This is an automated email from the git hooks/post-receive script.

martin-schanzenbach pushed a commit to branch master
in repository gnunet.

The following commit(s) were added to refs/heads/master by this push:
     new 5357758fd TESTING: Various notes on API
5357758fd is described below

commit 5357758fd97902f748bd3eb500d71c4ca0956065
Author: Martin Schanzenbach <schanzen@gnunet.org>
AuthorDate: Fri Dec 9 14:06:20 2022 +0900

    TESTING: Various notes on API
---
 src/include/gnunet_testing_barrier.h     | 13 +++++++++++++
 src/include/gnunet_testing_netjail_lib.h | 19 +++++++++++++++++--
 src/include/gnunet_testing_ng_lib.h      | 30 ++++++++++++++++--------------
 src/testing/testing_api_loop.c           |  2 +-
 4 files changed, 47 insertions(+), 17 deletions(-)

diff --git a/src/include/gnunet_testing_barrier.h 
b/src/include/gnunet_testing_barrier.h
index ed4624e1b..b02499d14 100644
--- a/src/include/gnunet_testing_barrier.h
+++ b/src/include/gnunet_testing_barrier.h
@@ -67,6 +67,7 @@ struct GNUNET_TESTING_BarrierList
 
 /**
  * Message send to a child loop to inform the child loop about a barrier being 
advanced.
+ * FIXME: This is not packed and contains a char*... no payload documentation.
  */
 struct GNUNET_TESTING_CommandBarrierAdvanced
 {
@@ -84,6 +85,7 @@ struct GNUNET_TESTING_CommandBarrierAdvanced
 /**
  * Message send by a child loop to inform the master loop how much
  * GNUNET_CMDS_BARRIER_REACHED messages the child will send.
+ * FIXME: Not packed and contains char*; int in NBO? bitlength undefined.
  */
 struct GNUNET_TESTING_CommandBarrierAttached
 {
@@ -109,6 +111,7 @@ struct GNUNET_TESTING_CommandBarrierAttached
 };
 
 
+// FIXME: See above
 struct GNUNET_TESTING_CommandBarrierReached
 {
   /**
@@ -138,6 +141,12 @@ struct GNUNET_TESTING_CommandBarrierReached
 struct GNUNET_TESTING_Barrier*
 GNUNET_TESTING_barrier_new (const char *testcase_name);
 
+/**
+ * FIXME: documentation
+ * FIXME: high-level it is baffling how we need both the GNUNET_TESTING_Barrier
+ * and the Command that creates barriers. Conceptually this seems to be
+ * very much separate. Can we move _Barrier completely into testing as private?
+ */
 struct GNUNET_TESTING_Command
 GNUNET_TESTING_cmd_barrier_create (
  const char *label,
@@ -149,6 +158,7 @@ GNUNET_TESTING_cmd_barrier_create (
 // async version implies reached but does not
 // wait on other peers to reach it.
 /**
+ * FIXME: Documentation
  * Create command.
  *
  * @param label name for command.
@@ -171,6 +181,8 @@ GNUNET_TESTING_cmd_barrier_reached (
 
 
 /**
+ * FIXME: Return type
+ * FIXME: Documentation
  * Can we advance the barrier?
  *
  * @param barrier The barrier in question.
@@ -181,6 +193,7 @@ GNUNET_TESTING_can_barrier_advance (struct 
GNUNET_TESTING_Barrier *barrier);
 
 
 /**
+ * FIXME: Naming
  * Send Message to netjail nodes that a barrier can be advanced.
  *
  * @param is The interpreter loop.
diff --git a/src/include/gnunet_testing_netjail_lib.h 
b/src/include/gnunet_testing_netjail_lib.h
index 53cae38c6..eb16f6b86 100644
--- a/src/include/gnunet_testing_netjail_lib.h
+++ b/src/include/gnunet_testing_netjail_lib.h
@@ -50,6 +50,7 @@ struct GNUNET_TESTING_NetjailRouter
 
 
 /**
+ * FIXME: Naming
  * Enum for the different types of nodes.
  */
 enum GNUNET_TESTING_NODE_TYPE
@@ -265,6 +266,7 @@ GNUNET_TESTING_get_topo_from_file (const char *filename);
 
 
 /**
+ * FIXME: this could use a "to_string".
  * Parse the topology data.
  *
  * @param data The topology data.
@@ -386,6 +388,7 @@ struct GNUNET_TESTING_TestState
 };
 
 /**
+ * FIXME: This was also not namespaces.
  * Struct with information for callbacks.
  *
  */
@@ -408,6 +411,7 @@ struct GNUNET_TESTING_BlockState
 };
 
 /**
+ * FIXME: This was also not namespaced
  * Struct to hold information for callbacks.
  *
  */
@@ -426,7 +430,7 @@ struct GNUNET_TESTING_LocalPreparedState
 };
 
 /**
- * Create command.
+ * Create command. FIXME: What?
  *
  * @param label name for command.
  * @param create_label Label of the cmd which started the test system.
@@ -437,13 +441,14 @@ struct GNUNET_TESTING_Command
 GNUNET_TESTING_cmd_system_destroy (const char *label,
                                    const char *create_label);
 
-
+//FIXME
 struct GNUNET_TESTING_Command
 GNUNET_TESTING_cmd_system_create (const char *label,
                                   const char *testdir);
 
 
 /**
+ * FIXME
  * Create command.
  *
  * @param label name for command.
@@ -458,6 +463,7 @@ GNUNET_TESTING_cmd_netjail_start (const char *label,
 
 
 /**
+ * FIXME
  * Create command.
  *
  * @param label name for command.
@@ -472,6 +478,8 @@ GNUNET_TESTING_cmd_netjail_stop (const char *label,
 
 
 /**
+ * FIXME
+ * FIXME Naming?
  * Create command.
  *
  * @param label Name for the command.
@@ -506,6 +514,8 @@ GNUNET_TESTING_cmd_stop_testing_system (
 
 /**
  * Create a GNUNET_CMDS_LOCAL_FINISHED message.
+ * FIXME: This is strange as messages are not really used
+ * like this. Consider removing.
  *
  * @return The GNUNET_CMDS_LOCAL_FINISHED message.
  */
@@ -513,6 +523,7 @@ struct GNUNET_MessageHeader *
 GNUNET_TESTING_send_local_test_finished_msg ();
 
 
+//FIXME
 struct GNUNET_TESTING_Command
 GNUNET_TESTING_cmd_block_until_all_peers_started (
   const char *label,
@@ -520,6 +531,7 @@ GNUNET_TESTING_cmd_block_until_all_peers_started (
 
 
 /**
+ * FIXME
  * Create command.
  *
  * @param label name for command.
@@ -532,6 +544,7 @@ GNUNET_TESTING_cmd_block_until_external_trigger (
   const char *label);
 
 /**
+ * FIXME
  * Create command.
  *
  * @param label name for command.
@@ -544,6 +557,7 @@ GNUNET_TESTING_cmd_send_peer_ready (const char *label,
 
 
 /**
+ * FIXME
  * Create command.
  *
  * @param label name for command.
@@ -556,6 +570,7 @@ GNUNET_TESTING_cmd_local_test_finished (
   GNUNET_TESTING_cmd_helper_write_cb write_message);
 
 /**
+ * FIXME
  * Create command.
  *
  * @param label name for command.
diff --git a/src/include/gnunet_testing_ng_lib.h 
b/src/include/gnunet_testing_ng_lib.h
index d218a65db..270fdab26 100644
--- a/src/include/gnunet_testing_ng_lib.h
+++ b/src/include/gnunet_testing_ng_lib.h
@@ -328,6 +328,9 @@ GNUNET_TESTING_cmd_end (void);
 
 /**
  * Turn asynchronous command into non blocking command by setting 
asynchronous_finish to true.
+ * FIXME: what is this API doing? Is it returning a new cmd which is 
unblocking?
+ * Is it modifying cmd?
+ * Looking at the code, it both modifying cmd AND returning a copy oO
  *
  * @param cmd command to make synchronous.
  * @return a finish-command.
@@ -370,6 +373,8 @@ GNUNET_TESTING_cmd_rewind_ip (const char *label,
 
 /**
  * Function called with the final result of the test.
+ * FIXME: This may want to use a GNUNET_ErrorCode (namespaced, e.g.
+ * GNUNET_EC_TESTING_*)
  *
  * @param cls closure
  * @param rv #GNUNET_OK if the test passed
@@ -385,7 +390,7 @@ typedef void
  * defined into the "run" method that returns after
  * having scheduled the test interpreter.
  *
- * @param commands the list of command to execute
+ * @param commands the array of command to execute
  * @param timeout how long to wait for each command to execute
  * @param rc function to call with the final result
  * @param rc_cls closure for @a rc
@@ -402,6 +407,7 @@ GNUNET_TESTING_run (const struct GNUNET_TESTING_Command 
*commands,
  * Start a GNUnet scheduler event loop and
  * run the testsuite.  Return 0 upon success.
  * Expected to be called directly from main().
+ * FIXME: Why is this commands array here not const?
  *
  * @param commands the list of command to execute
  * @param timeout how long to wait for each command to execute
@@ -412,19 +418,6 @@ GNUNET_TESTING_main (struct GNUNET_TESTING_Command 
*commands,
                      struct GNUNET_TIME_Relative timeout);
 
 
-/**
- * Look for substring in a programs' name.
- *
- * @param prog program's name to look into
- * @param marker chunk to find in @a prog
- * // FIXME: this does not belong here! => libgnunetutil, maybe?
- * // FIXME: return bool? document return value!
- * // FIXME: man strstr??
- */
-int
-GNUNET_TESTING_has_in_name (const char *prog,
-                            const char *marker);
-
 /**
   * Deleting all barriers create in the context of this interpreter.
   *
@@ -473,6 +466,8 @@ GNUNET_TESTING_add_netjail_helper (struct 
GNUNET_TESTING_Interpreter *is,
 
 /**
  * Send Message to netjail nodes that a barrier can be advanced.
+ * FIXME: Naming. No "netjail" in argument. Or is there a
+ * GNUNET_TESTING_send_message without "to_netjail"??
  *
  * @param is The interpreter.
  * @param global_node_number The node to inform.
@@ -486,6 +481,8 @@ GNUNET_TESTING_send_message_to_netjail (struct 
GNUNET_TESTING_Interpreter *is,
 
 /**
  * Returns the actual running command.
+ * FIXME: Is Command allocated? Is it constant? Should this be a private
+ * function? => not used outside of testing
  *
  * @param is Global state of the interpreter, used by a command
  *        to access information about other commands.
@@ -498,6 +495,7 @@ GNUNET_TESTING_interpreter_get_current_command (
 
 /**
  * Check if the command is running.
+ * FIXME: Unused function.
  *
  * @param command The command to check.
  * @return GNUNET_NO if the command is not running, GNUNET_YES if it is 
running.
@@ -508,6 +506,7 @@ GNUNET_TESTING_running (const struct GNUNET_TESTING_Command 
*command);
 
 /**
  * Check if a command is finished.
+ * FIXME: Unused function
  *
  * @param command The command to check.
  * @return GNUNET_NO if the command is not finished, GNUNET_YES if it is 
finished.
@@ -595,6 +594,7 @@ struct GNUNET_TESTING_Timer
 
 /**
  * Retrieve the public key from the test system with the unique node id.
+ * FIXME: Naming. => get_peer? This returns a PeerIdentity not a PublicKey
  *
  * @param num The unique node id.
  * @param tl_system The test system.
@@ -618,6 +618,7 @@ GNUNET_TESTING_cmd_stat (struct GNUNET_TESTING_Timer 
*timers);
 /* *** Generic trait logic for implementing traits ********* */
 
 /**
+ * FIXME: Documentation
  * A trait.
  */
 struct GNUNET_TESTING_Trait
@@ -652,6 +653,7 @@ GNUNET_TESTING_trait_end (void);
 
 /**
  * Extract a trait.
+ * FIXME: Naming. This is something like "contains trait".
  *
  * @param traits the array of all the traits.
  * @param[out] ret where to store the result.
diff --git a/src/testing/testing_api_loop.c b/src/testing/testing_api_loop.c
index f133956cf..567d343cf 100644
--- a/src/testing/testing_api_loop.c
+++ b/src/testing/testing_api_loop.c
@@ -378,7 +378,7 @@ GNUNET_TESTING_interpreter_fail (struct 
GNUNET_TESTING_Interpreter *is)
  *        to access information about other commands.
  * @return The actual running command.
  */
-struct GNUNET_TESTING_Command *
+const struct GNUNET_TESTING_Command *
 GNUNET_TESTING_interpreter_get_current_command (
   struct GNUNET_TESTING_Interpreter *is)
 {

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.