304 lines
12 KiB
C
304 lines
12 KiB
C
|
/**
|
||
|
|
* @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);
|
||
|
|
|