gnunet_testing_loop_lib.h

Go to the documentation of this file.

/*
      This file is part of GNUnet
      Copyright (C) 2021, 2023 GNUnet e.V.
 
      GNUnet is free software: you can redistribute it and/or modify it
      under the terms of the GNU Affero General Public License as published
      by the Free Software Foundation, either version 3 of the License,
      or (at your option) any later version.
 
      GNUnet is distributed in the hope that it will be useful, but
      WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      Affero General Public License for more details.
 
      You should have received a copy of the GNU Affero General Public License
      along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
     SPDX-License-Identifier: AGPL3.0-or-later
 */
 
#ifndef GNUNET_TESTING_LOOP_LIB_H
#define GNUNET_TESTING_LOOP_LIB_H
 
#define GNUNET_TESTING_CMD_MAX_LABEL_LENGTH 127
 
/* ********************* Helper functions ********************* */
 
#define GNUNET_TESTING_FAIL(is) \
  do \
  { \
    GNUNET_break (0); \
    GNUNET_TESTING_interpreter_fail (is); \
    return; \
  } while (0)
 
 
/* ******************* Generic interpreter logic ************ */
 
struct GNUNET_TESTING_Interpreter;
 
struct GNUNET_TESTING_AsyncContext
{
 
  struct GNUNET_TESTING_Interpreter *is; // FIXME: Why needed? When available?
 
  GNUNET_SCHEDULER_TaskCallback cont;
 
  void *cont_cls;
 
  enum GNUNET_GenericReturnValue finished;
};
 
 
void
GNUNET_TESTING_async_fail (struct GNUNET_TESTING_AsyncContext *ac);
 
 
void
GNUNET_TESTING_async_finish (struct GNUNET_TESTING_AsyncContext *ac);
 
 
typedef void
(*GNUNET_TESTING_CommandRunRoutine)(void *cls,
                                    struct GNUNET_TESTING_Interpreter *is);
 
 
typedef void
(*GNUNET_TESTING_CommandCleanupRoutine)(void *cls);
 
 
typedef enum GNUNET_GenericReturnValue
(*GNUNET_TESTING_CommandGetTraits) (void *cls,
                                    const void **ret,
                                    const char *trait,
                                    unsigned int index);
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_command_new (void *cls,
                            const char *label,
                            GNUNET_TESTING_CommandRunRoutine run,
                            GNUNET_TESTING_CommandCleanupRoutine cleanup,
                            GNUNET_TESTING_CommandGetTraits traits,
                            struct GNUNET_TESTING_AsyncContext *ac);
 
 
struct GNUNET_TESTING_CommandLabel
{
  char value[GNUNET_TESTING_CMD_MAX_LABEL_LENGTH + 1];
};
 
 
void
GNUNET_TESTING_set_label (struct GNUNET_TESTING_CommandLabel *label,
                          const char *value);
 
 
struct GNUNET_TESTING_Command
{
  void *cls;
 
  struct GNUNET_TESTING_CommandLabel label;
 
  GNUNET_TESTING_CommandRunRoutine run;
 
  struct GNUNET_TESTING_AsyncContext *ac;
 
  GNUNET_TESTING_CommandCleanupRoutine cleanup;
 
  GNUNET_TESTING_CommandGetTraits traits;
 
  struct GNUNET_TIME_Absolute start_time;
 
  struct GNUNET_TIME_Absolute finish_time;
 
  struct GNUNET_TIME_Absolute last_req_time;
 
  struct GNUNET_TIME_Relative default_timeout;
 
  unsigned int num_tries;
 
  bool asynchronous_finish;
 
};
 
 
// FIXME: think harder about whether this is actually needed, likely not.
const struct GNUNET_TESTING_Command *
GNUNET_TESTING_interpreter_lookup_future_command (
  struct GNUNET_TESTING_Interpreter *is,
  const char *label);
 
 
const struct GNUNET_TESTING_Command *
GNUNET_TESTING_interpreter_lookup_command (
  struct GNUNET_TESTING_Interpreter *is,
  const char *label);
 
 
const struct GNUNET_TESTING_Command *
GNUNET_TESTING_interpreter_lookup_command_all (
  struct GNUNET_TESTING_Interpreter *is,
  const char *label);
 
 
void
GNUNET_TESTING_interpreter_fail (struct GNUNET_TESTING_Interpreter *is);
 
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_make_unblocking (struct GNUNET_TESTING_Command cmd);
 
 
const struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_finish (const char *finish_label,
                           const char *cmd_ref,
                           struct GNUNET_TIME_Relative timeout);
 
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_rewind_ip (const char *label,
                              const char *target_label,
                              unsigned int counter);
 
 
typedef void
(*GNUNET_TESTING_ResultCallback)(void *cls,
                                 enum GNUNET_GenericReturnValue rv);
 
 
struct GNUNET_TESTING_Interpreter *
GNUNET_TESTING_run (const struct GNUNET_TESTING_Command *commands,
                    struct GNUNET_TIME_Relative timeout,
                    GNUNET_TESTING_ResultCallback rc,
                    void *rc_cls);
 
 
int
GNUNET_TESTING_main (struct GNUNET_TESTING_Command *commands,
                     struct GNUNET_TIME_Relative timeout);
 
 
 
/* ************** Fundamental interpreter commands ************ */
 
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_end (void);
 
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_batch (const char *label,
                          struct GNUNET_TESTING_Command *batch);
 
 
struct GNUNET_TESTING_Timer
{
  const char *prefix;
 
  struct GNUNET_TIME_Relative total_duration;
 
  struct GNUNET_TIME_Relative success_latency;
 
  unsigned int num_commands;
 
  unsigned int num_retries;
};
 
struct GNUNET_TESTING_Command
GNUNET_TESTING_cmd_stat (struct GNUNET_TESTING_Timer *timers);
 
 
/* *** Generic trait logic for implementing traits ********* */
 
struct GNUNET_TESTING_Trait
{
  unsigned int index;
 
  const char *trait_name;
 
  const void *ptr;
};
 
 
struct GNUNET_TESTING_Trait
GNUNET_TESTING_trait_end (void);
 
 
enum GNUNET_GenericReturnValue
GNUNET_TESTING_get_trait (const struct GNUNET_TESTING_Trait *traits,
                          const void **ret,
                          const char *trait,
                          unsigned int index);
 
 
 
#define GNUNET_TESTING_MAKE_DECL_SIMPLE_TRAIT(prefix,name,type) \
  enum GNUNET_GenericReturnValue                           \
  prefix ## _get_trait_ ## name (                          \
    const struct GNUNET_TESTING_Command *cmd,              \
    type **ret);                                           \
  struct GNUNET_TESTING_Trait                              \
  prefix ## _make_trait_ ## name (                         \
    type * value);
 
 
#define GNUNET_TESTING_MAKE_IMPL_SIMPLE_TRAIT(prefix,name,type) \
  enum GNUNET_GenericReturnValue                          \
  prefix ## _get_trait_ ## name (                         \
    const struct GNUNET_TESTING_Command *cmd,             \
    type * *ret)                                          \
  {                                                       \
    if (NULL == cmd->traits) return GNUNET_SYSERR;        \
    return cmd->traits (cmd->cls,                         \
                        (const void **) ret,              \
                        GNUNET_S (name),                  \
                        0);                               \
  }                                                       \
  struct GNUNET_TESTING_Trait                             \
  prefix ## _make_trait_ ## name (                        \
    type * value)                                         \
  {                                                       \
    struct GNUNET_TESTING_Trait ret = {                   \
      .trait_name = GNUNET_S (name),                      \
      .ptr = (const void *) value                         \
    };                                                    \
    return ret;                                           \
  }
 
 
#define GNUNET_TESTING_MAKE_DECL_INDEXED_TRAIT(prefix,name,type)    \
  enum GNUNET_GenericReturnValue                           \
  prefix ## _get_trait_ ## name (                          \
    const struct GNUNET_TESTING_Command *cmd,              \
    unsigned int index,                                    \
    type **ret);                                           \
  struct GNUNET_TESTING_Trait                              \
  prefix ## _make_trait_ ## name (                         \
    unsigned int index,                                    \
    type *value);
 
 
#define GNUNET_TESTING_MAKE_IMPL_INDEXED_TRAIT(prefix,name,type)    \
  enum GNUNET_GenericReturnValue                          \
  prefix ## _get_trait_ ## name (                         \
    const struct GNUNET_TESTING_Command *cmd,             \
    unsigned int index,                                   \
    type * *ret)                                          \
  {                                                       \
    if (NULL == cmd->traits) return GNUNET_SYSERR;        \
    return cmd->traits (cmd->cls,                         \
                        (const void **) ret,              \
                        GNUNET_S (name),                  \
                        index);                           \
  }                                                       \
  struct GNUNET_TESTING_Trait                             \
  prefix ## _make_trait_ ## name (                        \
    unsigned int index,                                   \
    type * value)                                         \
  {                                                       \
    struct GNUNET_TESTING_Trait ret = {                   \
      .index = index,                                     \
      .trait_name = GNUNET_S (name),                      \
      .ptr = (const void *) value                         \
    };                                                    \
    return ret;                                           \
  }
 
 
#define GNUNET_TESTING_LOOP_SIMPLE_TRAITS(op,prefix)      \
  op (prefix, batch_cmds, struct GNUNET_TESTING_Command *)
 
 
GNUNET_TESTING_LOOP_SIMPLE_TRAITS(GNUNET_TESTING_MAKE_DECL_SIMPLE_TRAIT, GNUNET_TESTING)
 
 
 
#define GNUNET_TESTING_LOOP_INDEXED_TRAITS(op,prefix) \
  op (prefix, cmd, const struct GNUNET_TESTING_Command)
 
GNUNET_TESTING_LOOP_INDEXED_TRAITS (GNUNET_TESTING_MAKE_DECL_INDEXED_TRAIT, GNUNET_TESTING)
 
 
#endif