gem-graph-client/include/fsm.h

/**
 * @file
 * FSM (Finite State Machine) header
 *
 * This file is part of Gem-graph.
 *
 * @cond LICENSE
 * Copyright © 2021 Libre en Communs <contact@a-lec.org>
 * Copyright © 2021-2024 Adrien Bourmault <neox@a-lec.org>
 * Copyright © 2021-2024 Jean Sirmai <jean@a-lec.org>
 *
 * This program 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.
 *
 * This program 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/>.
 * @endcond
 */


#pragma once
#include <stdbool.h>
#include <stddef.h>
#include <string.h>
#include <gtk-4.0/gtk/gtk.h>

/******************************************************************************/
/*                               J O U R N A L                                */
/******************************************************************************/

/**
 * --
 * J O U R N A L    -  M E T A  -  R U L E S
 * --
 *
 *  ref: sudo cat /var/log/messages
 *
 *  log structure:
 * - date
 * - rank
 * - file
 * - function
 * - value, parameter, description, context,...
 *   (any value that can qualify the event
 *  and provides useful information when reading the log)
 *
 * --
 *
 *  Un seul fsm_add_log() par fonction
 *      ? sauf si cette fonction génère plusieurs autres fonctions d'intérêt ?
 *
 *  S'il y a deux fsm_add_log() (begin / end) dans une fonction,
 *  ils doivent avoir la même étiquette (les mêmes valeurs) : SEVERITY & SOURCE
 */


/**
 * Conforms to canonical log levels:  FATAL, ERROR, WARN, INFO, DEBUG, TRACE
 *
 * https://betterstack.com/community/guides/logging/logging-best-practices/
 * https://en.wikipedia.org/wiki/Syslog
 *
 * @see fsm_add_log())
 */
enum fsm_enum_log_severity {
    FATAL,  /**< (or CRITICAL) an unrecoverable failure that prevents the whole
             * application from doing any further useful work */
    ERROR,  /**< a condition that hinders the execution of a specific
             * operation within an application and is unrecoverable */
    WARN,   /**< something unexpected has occurred, but the application can
             * continue to function normally for the time being */
    INFO,   /**< (or MESSAGE) a significant event occurs while the system is
             * operating normally */
    DEBUG,  /**< a description of system states in sufficient detail to give
             * developers clues as to the cause of an error */
    TRACE   /**< provides a systematic overview of code execution but comes at
             * a cost in terms of performance */
};

/**
 * arbitrary values that can help the logging filter work more efficiently
 *
 * @see fsm_add_log())
 */
enum fsm_enum_log_source {
    SOURCE, /**< must each element of this enumeration be commented (enhanced) ? */
    TARGET, /**< let's observe first how the enumeration structures and evolves on usage */
    LOG, FSM, PREFER,
    MAIN, APP, WIDGETS, SIGNAL,
    WINDOW, /**< MAIN_WINDOW || DIALOG_WINDOW || MODAL_WINDOW || TEXT_WINDOW  */
    DIALOG_WINDOW, MODAL_WINDOW, TEXT_WINDOW,
    AUTO_NOTIFICATION,
    TOPBAR, /**< LEFT || CENTER || RIGHT */
    TOPBAR_LEFT, TOPBAR_CENTER, TOPBAR_RIGHT,
    PAGE, /**< SYNTH_PAGE || STATE_PAGE || RULES_PAGE || MEASURES_PAGE || RESULTS_PAGE
           * \n RULES_PAGE == USER TREE versus SELECTED (vertical separation)*/
    SYNTH_PAGE, STATE_PAGE, RULES_PAGE, MEASURES_PAGE, RESULTS_PAGE,
    SYNTH_GLAREA, SYNTH_ALL_RESULTS,
    SYNTH_TIME_DEP_RESULTS, SYNTH_TIME_INDEP_RESULTS,
    STATE_TOP, STATE_BOTTOM, STATE_GLAREA, STATE_CAMERA,
    RULE_GEOMETRY, RULE_GLAREA, RULE_CAMERA,
    RULE_ALGEBRA, RULE_CONDITION, RULE_ASSIGN, RULE_ID,
    RULES_TREE, RULES_COMPARE, RULES_USE,
    MEASURES_TOOLS, MEASURES__ACTIVITY, MEASURES__DISPLAY,
    RESULTS, TIME_DEP_RESULTS, TIME_INDEP_RESULTS,
    WIDGET, BUTTON, SCROLL, GLAREA, TEXT, LABEL, TREE, SLIDER, EXPANDER, ENTRY,
    ON_SWITCH_STATE_RULES_DATA,
    SLIDER_X, SLIDER_Y, SLIDER_Z,
    SLIDER_A, SLIDER_B, SLIDER_C,
};

#define LOG_MAX_LENGTH 255  /**< arbitrary */

/**
 * structure of a log element
 *
 * @callergraph
 * @see fsm_add_log()
 * @see fsm_add_log_event()
 */
typedef struct  fsm_log_struct_unit
                {
                    long yy_dd_mm; /**< * date of the event reported in the log */
                    long usec;     /**< * with microseconds precision */
                    const char *file_source;     /**< * emitter file */
                    const char *function_source; /**< * emitter function */
                    const char *string_value;    /**< * any event descriptors */
                    struct fsm_log_struct_unit *prev; /**< * chained list */
                    struct fsm_log_struct_unit *next; /**< * chained list */
                }
                fsm_log_struct_unit;


/**
 * required to initialise a double-chained list
 * @see use in src/fsm/dispatch/fsm_add_log()
 * @see use in src/log/fsm_init_log()
 */
typedef struct {
                    fsm_log_struct_unit *first; /**< * required */
                    fsm_log_struct_unit *last;  /**< * required */
               }
               fsm_log_struct;

void fsm_publish_log  (fsm_log_struct jj);       //  def: src/journal  call: fsm/dispatch
void fsm_init_log     (fsm_log_struct *jj);      //  def: src/journal  call: fsm/dispatch
void fsm_add_log_event          (fsm_log_struct *jj,       //  def: src/journal  call: fsm/dispatch
                           const char *file_source,
                           const char *function_source,
                           const char *string_value);
void fsm_clear_log    (fsm_log_struct *jj,       //  def: src/journal  call: none
                           const char *file_source,
                           const char *function_source,
                           const char *string_value);
long fsm_pop_back_log (fsm_log_struct *jj,       //  def: src/journal  call: none
                           const char *file_source,
                           const char *function_source,
                           const char *string_value);
int  fsm_length_log   (fsm_log_struct jj);       //  def: src/journal  call: none
void fsm_seek_log     (fsm_log_struct jj,        //  def: src/journal  call: none
                           long usec,
                           const char *file_source,
                           const char *function_source,
                           const char *string_value);

// -----------------------------------------------------------------------------
//

void fsm_log_publication_request();   //  def: fsm/dispatch   call: main;
void fsm_add_log    (int severity,
                           int source,
                           const char *file_source,
                           const char *function_source,
                           const char *string_value);
//  def: fsm/dispatch   call: widget/dispatch;
// -----------------------------------------------------------------------------


/******************************************************************************/
/*                         S T A T E   M A C H I N E                          */
/******************************************************************************/
//                called by widgets through signal functions

/** phantom documentation */
enum fsm_enum_exec_edit           { EXEC, EDIT };

/** phantom documentation */
enum fsm_enum_state_rules_data    { SYNTH, STATE, RULES, DATA };

/** phantom documentation */
enum fsm_enum_store_restore_reset { STORE, RESTORE, RESET };

/** phantom documentation */
enum fsm_enum_measure_type {DATE_RULE_EXEC, RULE_EXEC_NB, OBJECT_NB, ELAPSED_TIME };

#define n_rules 128   /**<  arbitrary */
#define n_objects 32   /**<   arbitrary too, */
#define n_situations 128  /**<   and so on... */


/** phantom documentation */
typedef struct fsm_struct_list_tool {
    int value;                              /**< *value   phantom documentation */
    struct fsm_struct_list_tool *suiv;      /**< *suiv    phantom documentation */
} fsm_struct_list_tool ;


/** phantom documentation */
typedef struct fsm_struct_list_data {
    int value;                              /**< *value   phantom documentation */
    struct fsm_struct_list_data *suiv;      /**< *suiv    phantom documentation */

} fsm_struct_list_data ;


/** phantom documentation */
typedef struct fsm_struct_list_disp {
    int value;                              /**< *value   phantom documentation */
    struct fsm_struct_list_disp *suiv;      /**< *suiv    phantom documentation */
} fsm_struct_list_disp ;



void fsm_init (char *message);     //  def: fsm/dispatch;               call: main;
void fsm_list_init_preferences();  //  def: fsm/preferences/manager;    call: fsm/dispatch;
void fsm_list_init_measures();     //  def: fsm/measure/manager;        call: fsm/dispatch;
void fsm_list_init_results();      //  def: fsm/results/manager;        call: fsm/dispatch;
void fsm_list_init_displayables(); //  def: fsm/preferences/manager;    call: fsm/dispatch;

int  fsm_get_exec_edit();          //  def: fsm/disfpatch;  call: signal;
                                   //                            widget/state/dispatch;
                                   //                            widget/rules/selected/dispatch;
int  fsm_get_state_rules_data();   //  def: fsm/dispatch;  call: signal;

void fsm_set_exec_edit (int value);//  def: fsm/dispatch;  call: signal;
void fsm_set_state_rules_data (int value); // def: fsm/dispatch; call: signal;

void fsm_set_store_restore_reset (int choice, int value);// def: prefer;  call: signal;

bool fsm_get_preferences_state();  //  def: fsm/dispatch;  call: - - -
void fsm_set_preferences_modified (bool value); // def: fsm/dispatch;
                                                // call:  signal;  fsm/prefer;

void fsm_add_measure (char *measure_name); // def: fsm/measure/manager;
                                           // call: widget/measure/dispatch;
void fsm_add_result (char *result_name);   // def: fsm/results/manager;   call: - - -
void fsm_add_displayable (char *displayable_name);//  def: fsm/preferences/manager;  call: fsm/preferences/manager;

void fsm_reset_all_situations_values (int value); // def: fsm/preferences/manager;    call: signal;

// ---------------------------------------------------------------   WIP  ------
//  def: measure/tool_list  call: measure/tool_list  (about the following functions...)
void fsm_tools_list_insert (fsm_struct_list_tool **tl, int value);
int  fsm_tools_list_pop    (fsm_struct_list_tool **tl);
int  fsm_tools_list_length (fsm_struct_list_tool  *tl);
void fsm_tools_list_clear  (fsm_struct_list_tool **tl);
void fsm_tools_list_view   (fsm_struct_list_tool  *tl);
void fsm_tools_list_test(); //  def: measures/manager;  call: measures/manager;

//  def: fsm/measure/manage/;   call: rule exec
void fsm_rule_trig_measure (int rule_id, int object_id, int measure_id);


// ---------------------------------------------------------------   WIP  ------
// @see fsm/measures/data_list/
void fsm_add_data    (fsm_struct_list_data d, int *p_data, int *p_target);
int  fsm_get_data    (fsm_struct_list_data d, int from, int to);
void fsm_remove_data (fsm_struct_list_data d, int *p_data);


// ---------------------------------------------------------------   WIP  ------
/*void fsm_disp_add_chart    (fsm_struct_list_disp d, int *p_chart);
int  fsm_disp_get_chart    (fsm_struct_list_disp d, int from, int to);
void fsm_disp_remove_chart (fsm_struct_list_disp d, int *p_chart);*/