/** * @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 * 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 */ #pragma once #include /******************************************************************************/ /* 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;