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
 *
 *
 * In this commit, the FSM (Finite State Machine) header only lists all the
 * structures that the log needs. Other fsm functions will be introduced in
 * subsequent commits. @see readme.docs and this text below.
 *
 * ---
 *
 * The two structures and the two enums listed below will stay in the fsm header.
 *
 * All functions but the last one are now in dedicated files.
 *
 * The most important function: fsm_add_log() is in the file:
 * /src/fsm/log/manager.c
 *
 * This file contains the declaration of the log with the static attribute,
 * which forces all the functions that read or write it to be in it.
 * Forcing all functions that read or write to the log to be grouped together
 * help to prevent uncontrolled operations.
 *
 * All events sent to the log must pass through this function, which allows them
 * to be filtered before being published in the log.
 *
 * ---
 *
 * Here's how the procedure works.
 * A message is send to the fsm_add_log() function for each documented event.
 * If there are too many events, this is the only function that allows you to
 * apply one or more filters before publication. This allows you to select the
 * events of interest, which can vary depending on the type of session.
 * These filters can operate on any the following five parameters:
 * severity, source, file_source, function_source, string_value.
 * They can be combined using any logical operators and parentheses.
 *
 * 'severity' is one of the following pre-defined values:
 * FATAL  -  ERROR  -  WARN  -  INFO  -  DEBUG  -  TRACE
 *
 * 'source' is a pre-defined value (typically a name of a structure) that can be
 * associated to each event. It can be set to 'NULL'.
 *
 * file_source, function_source and string_value are three strings.
 *
 * ---
 *
 * The four most important executive functions needed by the log are in the
 * dedicated file: /src/fsm/log/oper.c:
 *
 * NB: fsm_clear_log() is designed to close what was initiated by fsm_init_log().
 * As, in this commit, fsm_publish_log() is the last instruction and no memory
 * leaks are detected, the use of fsm_clear_log() is not required.
 *
 * - fsm_init_log()
 * - fsm_publish_log()
 * - fsm_clear_log()
 * - fsm_add_log_event()
 * .
 *
 * A typical list would also feature the following three functions
 * but in the case of a log, their usefulness remains to be demonstrated.
 * These functions are therefore apart in the file /src/fsm/log/appendix.c
 *
 * - fsm_get_log_length()
 * - fsm_seek_log()
 * - fsm_remove_log()
 * .
 *
 */


#pragma once

/******************************************************************************/
/*                         L O G   /   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 or states that may be involved in program events.
 *
 * All logs must contain at least one item from this list or the value NULL.
 *
 * Only some main items of this list are commented on today. Further comments
 * will depend on its usage and structure which are just beginning to evolve.
 *
 * NB  about PAGE:  user_tree and selected_rule are two vertical panes which it
 * is a good idea to place next to each other on the rules page so that you can
 * switch between them more easily or have a parallel view of the two.
 *
 * @see fsm_add_log()
 */
enum fsm_enum_log_source {
    AUTO_NOTIFICATION, /**< (not a source) */
    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 */
        MAIN_WINDOW, DIALOG_WINDOW, MODAL_WINDOW, TEXT_WINDOW,
    TOPBAR, /**< LEFT, CENTER, RIGHT */ TOPBAR_LEFT, TOPBAR_CENTER, TOPBAR_RIGHT,
    PAGE, /**< SYNTH, STATE, RULES, [USER TREE], [SELECTED_RULE], MEASURES, RESULTS */
        SYNTH_PAGE, STATE_PAGE, RULES_PAGE, MEASURES_PAGE, RESULTS_PAGE,
    SYNTHESIS, /**< GLAREA, CAMERA, CONTROLS, RESULTS (duplicates from other pages) */
        SYNTH_GLAREA, SYNTH_CAMERA, SYNTH_CONTROLS, SYNTH_RESULTS,
    SYNTH_DATA, /**< SYNTH_TIME_DEP_RESULTS, SYNTH_TIME_INDEP_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, /**< RULE_GEOMETRY, RULE_ALGEBRA */
    RULE_GEOMETRY, /**< VIEW_BEFORE, VIEW_AFTER, RULE_GLAREA, RULE_CAMERA */
        VIEW_BEFORE, VIEW_AFTER, RULE_GLAREA, RULE_CAMERA,
    RULE_ALGEBRA, /**< LIST_CONDITIONS, LIST_ASSIGNMENTS, IDENTITY */
        RULE_LIST_CONDITION, RULE_LIST_ASSIGNMENTS, RULE_IDENTITY,
    TREE_RULES, /**< TREE, COMPARE, USE */
        RULES_TREE, RULES_COMPARE, RULES_USE,
    MEASURES, /**< TOOLS, ACTIVITY, DISPLAY */
        MEASURES_TOOLS, MEASURES_ACTIVITY, MEASURES_DISPLAY,
    RESULTS, /**< TIME_DEPPENDENT, TIME_INDEPENDENT */
        TIME_DEP_RESULTS, TIME_INDEP_RESULTS,
    GTK_WIDGETS, /**< LABEL, BUTTON, SCROLL, GLAREA, SLIDER, EXPANDER,...
        * (non limitative) */
        WIDGET, BUTTON, SCROLL, GLAREA, TEXT, LABEL, TREE, SLIDER, EXPANDER,
        ENTRY, SLIDER_X, SLIDER_Y, SLIDER_Z, SLIDER_A, SLIDER_B, SLIDER_C,
    OTHERS, /**< fsm possible states:  [EXEC / EDIT], [STATE / RULES / DATA],
        * (non limitative) */
        ON_SWITCH_EXEC_EDIT, ON_SWITCH_STATE_RULES_DATA,
};

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

/**
 * Structure of a log unit.
 *
 * @callergraph
 * @see fsm_log_struct
 */
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;


/**
 * Two links towards the previous and the next unit are required to initialize
 * and manage a double-chained list.
 *
 * @callgraph
 * @see fsm_log_struct_unit
 *
 * @callergraph
 * @see fsm_init_log()
 * @see fsm_publish_log()
 * @see fsm_clear_log()
 * @see fsm_add_log_event()
 * @see fsm_get_log_length()
 * @see fsm_seek_log()
 * @see fsm_remove_log()
 */
typedef struct {
                    fsm_log_struct_unit *first; /**< * required */
                    fsm_log_struct_unit *last;  /**< * required */
               }
               fsm_log_struct;

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

void fsm_init_log      (fsm_log_struct *jj);
void fsm_publish_log   (fsm_log_struct jj);
void fsm_clear_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);

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);
long fsm_remove_log    (fsm_log_struct *jj,
                        const char *file_source,
                        const char *function_source,
                        const char *string_value);


/**
 * @brief (1) This comment is not a duplicate: it will be displaced in the file:
 * src/log/manager.c in next commits.
 *
 * It will be mandatory for any event to call the function fsm_add_log()
 * to be published in the journal and it is here and only here that filters will
 * be found.
 *
 * --
 *
 * @details The fsm_struct_journal (gg_logs) will be a static instance in a
 * dedicated file: src/log/manager.c
 * Therefore, all the functions that read or write it will be in this file.
 * This is to avoid uncontrolled operations on it.
 *
 * While the program is running, messages will be sent to the fsm_add_log()
 * function for each documented event.
 * If there are too many events, this is the only function that allows you to
 * apply one or more filters before publication. This allows you to select the
 * events of interest, which can vary depending on the type of session.
 *
 * These filters can operate on any of the following five parameters:
 * severity, source, file_source, function_source, string_value .
 * They can be combined using any logical operators and parentheses.
 *
 * --
 *
 * @since 2024-08
  *
 * @callgraph
 * @see fsm_add_log_event() insertion into the log list
 *
 * @callergraph @see Almost all functions will have to report events and will
 *              therefore call fsm_add_log().
 * @see main()  will send the first and last messages.
 *
 *
 * @param severity:  one of the following pre-defined values
 *
 *        FATAL  -  ERROR  -  WARN  -  INFO  -  DEBUG  -  TRACE
 *
 * @param source: a pre-defined value (a name of a structure) that can be
 * associated to each event. It can be set to 'NULL'.
 *
 * @param *file_source        the name of the file that emits the event
 * @param *function_source    the function that emits the event
 * @param *string_value       any value that better specifies the event
 *
 * @see fsm_enum_log_severity
 * @see fsm_enum_log_source
 */
void fsm_add_log (int severity,
                  int source,
                  const char *file_source,
                  const char *function_source,
                  const char *string_value);