gem-graph-client/include/fsm.h

/**
 * @file
 * FSM (Finite State Machine) header
 *
 * This file is part of Gem-graph.
 *
 * In this commit, the fsm treats only the log.
 *
 * --
 *
 * The production of the log requires: five structures, two enums, four
 * types and seven functions (see details below; the four macros are arbitrary)
 *
 * The role of the "severity" and "source" enumerations is to provide usable tools
 * for tagging messages so that they can be filtered.
 *
 * All logs must contain an item from each of these two enumerations.
 *
 * The filter is in fsm_add_log(). It uses the selected items as a labels to
 * highlight marked functions or structures during an inspection or repair.
 *
 * Only one message per function should be sent to the log, unless the function
 * generates several other functions of interest.
 *
 * If there are two messages or more in the same function, they should have the
 * same values from the enumerations 'severity' and 'source'.
 *
 *--
 *
 * @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 <gtk-4.0/gtk/gtk.h>

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

/**
 * The 'severity' enum 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
 *
 * All logs must contain at least one item from this enum and only one.
 * This item can not be set to NULL.
 *
 * @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,  /**< an irremediable situation that hinders the execution of a
                 specific operation within the application */
    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 */
};

/**
 * A list of structures that may be involved in a program event.
 *
 * All logs must contain at least one item from this enum and only one.
 * This item can be set to NULL.
 *
 * Only the main items of this list are commented on today. Further comments
 * will depend on its usage and structure which are just beginning to evolve.
 *
 * @see documentation
 * @see fsm_add_log()
 */
enum fsm_enum_log_source {
    AUTO_NOTIFICATION, /**< Not a source but a means of expression */
    DESTINATION, /**< SOURCE, TARGET */ SOURCE, TARGET,
    FSM_CONTENT, /**< LOG, FSM, PREFER */ LOG, FSM, PREFER,
    SRC_CONTENT, /**< MAIN, APP, WIDGETS, SIGNAL */ MAIN, APP, WIDGETS, SIGNAL,
    WINDOW, /**< MAIN, DIALOG, MODAL, TEXT  */ DIALOG_WINDOW, MODAL_WINDOW,
    TEXT_WINDOW,
    TOPBAR, /**< LEFT, CENTER, RIGHT */ TOPBAR_LEFT, TOPBAR_CENTER, TOPBAR_RIGHT,
    PAGE, /**< SYNTH, STATE, RULES, MEASURES, RESULTS
           * \n RULES_PAGE == USER TREE versus SELECTED (vertical separation)*/
    SYNTH_PAGE, STATE_PAGE, RULES_PAGE, MEASURES_PAGE, RESULTS_PAGE,
    SYNTHESIS, /**< In the SYNTH page can be:
                * GLAREA, RESULTS (all), TIME_DEP_RESULTS, TIME_INDEP_RESULTS */
    SYNTH_GLAREA, SYNTH_ALL_RESULTS,
    SYNTH_TIME_DEP_RESULTS, SYNTH_TIME_INDEP_RESULTS,
    STATE_VIEW, /**< TOP, BOTTOM, GLAREA, CAMERA */
    STATE_TOP, STATE_BOTTOM, STATE_GLAREA, STATE_CAMERA,
    SINGLE_RULE_VIEW, /** GEOMETRY, GLAREA, CAMERA, ALGEBRA, CONDITION, ASSIGN,
                       * ID, */
    RULE_GEOMETRY, RULE_GLAREA, RULE_CAMERA,
    RULE_ALGEBRA, RULE_CONDITION, RULE_ASSIGN, RULE_ID,
    TREE_RULES_VIEW, /** TREE, COMPARE, USE, */ RULES_TREE, RULES_COMPARE,
    RULES_USE,
    MEASURES_VIEW, /**< TOOLS, ACTIVITY, DISPLAY */
    MEASURES_TOOLS, MEASURES_ACTIVITY, MEASURES_DISPLAY,
    RESULTS_VIEW, /** TIME_DEP, TIME_INDEP */ TIME_DEP_RESULTS, TIME_INDEP_RESULTS,
    GTK_WIDGETS, /**< Only the main groups of widgets are mentioned here. */
    WIDGET, BUTTON, SCROLL, GLAREA, TEXT, LABEL, TREE, SLIDER, EXPANDER, ENTRY,
    OTHERS, /**< Experimental area */ ON_SWITCH_EXEC_EDIT, ON_SWITCH_STATE_RULES_DATA,
    SLIDER_X, SLIDER_Y, SLIDER_Z, SLIDER_A, SLIDER_B, SLIDER_C,
};

/**
 * 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);
void fsm_init_log      (fsm_log_struct *jj);
void fsm_add_log_event (fsm_log_struct *jj,
                           const char *file_source,
                           const char *function_source,
                           const char *string_value);
long fsm_pop_back_log (fsm_log_struct *jj,
                           const char *file_source,
                           const char *function_source,
                           const char *string_value);
int  fsm_get_log_length   (fsm_log_struct jj);
void fsm_seek_log         (fsm_log_struct jj,
                           long usec,
                           const char *file_source,
                           const char *function_source,
                           const char *string_value);

void fsm_trigger_log_init();
void fsm_trigger_log_publication();
void fsm_add_log    (int severity,
                           int source,
                           const char *file_source,
                           const char *function_source,
                           const char *string_value);

void fsm_init (char *message);     //  def: fsm/dispatch;               call: main;