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