188 lines
7.6 KiB
C
188 lines
7.6 KiB
C
/**
|
|
* @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;
|
|
|