include/fsm.h: prepares the building of a log and create src/readme.doc

This commit is the first in a series that will make the fsm apt to build the log. The log (or journal) records events chronologically from the start to the end of the programme. Its quantitatively most important part is to report on the execution of the session. The log will be created from the fsm (finite state machine) which describes all the possible states of the Gem-graph client and all the transitions between them. The fsm header is introduced in this commit. It lists the structures, functions and tools that the log will need and details the presentation of events in the log [date - rank - source file - source function - value]. The src/readme.docs file provides an initial overview of the missions and their distribution in the code files. valgrind --show-leak-kinds=all bin/gem-graph-client shows always the same message: ==xxxx== LEAK SUMMARY: ==xxxx== definitely lost: 96 bytes in 1 blocks ==xxxx== indirectly lost: 64 bytes in 1 blocks ==xxxx== possibly lost: 2,627 bytes in 7 blocks
2024-11-06 19:46:21 +01:00
3 changed files with 387 additions and 2 deletions
--- a/include/fsm.h
+++ b/include/fsm.h
@ -0,0 +1,303 @@
 /**
 * @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, eisrc/log/ther 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
 *
 *
 * The fsm header lists all the structures that the log will need.
 *
 * The two structures and the two enums listed below will stay in the fsm header.
 *
 * All functions but the last one will be in a dedicated file: src/log/oper.c
 * This file will contain the declaration of the log with the static attribute,
 * which will force 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
 * will prevent uncontrolled operations.
 *
 * The four most important functions are:
 * - fsm_init_log()
 * - fsm_publish_log()
 * - fsm_clear_log()
 * - fsm_add_log_event()
 * .
 *
 * A typical list would also feature the last three functions:
 * - fsm_get_log_length()
 * - fsm_seek_log()
 * - fsm_remove_log()
 * .
 * but in the case of a log, their usefulness remains to be demonstrated.
 *
 *
 * A last function: fsm_add_log() will be in another file: src/log/manager.c.
 * 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.
 *
 * Here is the list of all the structures that the log will need. The functions
 * will be documented in future commits.
 *
 * - fsm_log_struct()
 * - fsm_log_struct_unit()
 * .
 *
 * - fsm_enum_log_severity()
 * - fsm_enum_log_source()
 * .
 *
 * - fsm_init_log()
 * - fsm_publish_log()
 * - fsm_clear_log()
 * - fsm_add_log_event()
 * - fsm_get_log_length()
 * - fsm_seek_log()
 * - fsm_remove_log()
 * .
 *
 * - fsm_add_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);
--- a/src/main.c
+++ b/src/main.c
@ -3,7 +3,7 @@
 *
 * Gem-graph main file
 *
- * This file is part of Gem-graph.
+ * This file is part of Gem-graph. It contains only the main() function.
 *
 * @cond LICENSE
 * Copyright © 2021 Libre en Communs <contact@a-lec.org>
@ -23,6 +23,23 @@
 * 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
 *
 * ---
 *
 * The main() function will **initialise** the log, the finite state machine (fsm),
 * the application and the windows and **close** all the elements it opened
 * before the end of program execution.
 * In this commit, it does not implement g_application_activate() and has no
 * handlers connected to the 'activate' signal (which triggers an error message).
 *
 * The default values of the fsm initial state will be specified in:
 * src/fsm/dispatch(). They are user preference and, in accordance, the overview
 * page of the current model will be displayed as they specify it in:
 * src/widget/main_window/designer/widget_design_main_window().
 *
 * About code organization, see src/readme.dox
 *
 * ---
 */
 #include <gtk-4.0/gtk/gtk.h>
@ -32,9 +49,11 @@ int main (int argc, char **argv)
  GtkApplication *app;
  int status;
-  app = gtk_application_new ("org.jean.GTK4_GG_hack", G_APPLICATION_DEFAULT_FLAGS);
+  app = gtk_application_new ("org.gem-graph", G_APPLICATION_DEFAULT_FLAGS);
  //g_signal_connect (app, "activate", G_CALLBACK (on_main_window_activation), NULL);
  //g_signal_connect (app, "activate", G_CALLBACK (on_dialog_window_activation), NULL);
  status = g_application_run (G_APPLICATION (app), argc, argv);
  g_object_unref (app);
--- a/src/readme.docs.c
+++ b/src/readme.docs.c
@ -0,0 +1,63 @@
 /**
 * @file
 * Gem-graph-client src/readme.docs file
 *
 *  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
 *
 * @details
 * The code files are all located in the src (sources) directory.
 *
 * They are divided according to several *types of organisation*:
 *
 * - *hierarchical*: the widgets that give the windows their appearance are
 *    organised in the form of a tree.
 *    Windows are the first level of depth.
 *    Next come the windows contents: the title bars and the pages.
 *    The pages are designed to occupy the windows space below the title bars.
 *    Each of these pages has its own hierarchical structure: it can be divided
 *    into horizontal or vertical strips, which can themselves be divided in the
 *    same way, with varying levels of depth right down to the last containers
 *    which contain lists of widgets such as buttons, bars, entries or images.
 *
 * - *list*: the main *sections* of the fsm (finite state machine) constitute
 *   a list of at least four elements, each of which defines a set of possible
 *   states :
 *   -# execute or edit (managing the appropriate tools states in both cases)
 *   -# measure, operate on data, prepare displayable results
 *   -# user preferences
 *   -# desired state of windows and widgets
 *
 *   The state of the fsm is uniquely defined at all times by all the parameters
 *   listed in these sections. All program actions depend on this state.
 *
 * - *transversal*: the other functions that must be easily accessible by all
 *   the previous functions. They are therefore all located at the root.
 *   These are the functions that manage graphics, callbacks and utilities.
 *   Although 'transversal', the log is part of the fsm.
 *
 * ---
 *
 * @see
 * Model–view–controller || Model–view–viewmodel || Action–domain–responder ||
 * Multitier_architecture https://en.wikipedia.org/wiki/Multitier_architecture
 * (presentation, logic, data)
 */