gem-graph/gem-graph-client
gem-graph
/
gem-graph-client
3
0
Fork 0
Code Issues 14 Pull Requests Projects Releases Activity

src/fsm/* modifies several names: 

* - in fsm_trigger_log_init(), fsm_trigger_log_close() the word **trigger** is
 * replaced by **relay**
 * - fsm_log_struct_unit is replaced by: fsm_log_unit_struct
 *
 * docs/rtfm/intro (previously 'Once upon a time'... 🙃️) is also renamed and
 * extended.
 *
This commit is contained in:
Jean Sirmai 2024-11-11 16:39:47 +01:00
parent 98f69581b8
commit c9edba046c
Signed by: jean
GPG Key ID: FB3115C340E057E3
5 changed files with 89 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
include/fsm.h
View File

@ -1,29 +1,15 @@
/**
* @file
* Client fsm (finite state machine) header
*
* This file is part of Gem-graph.
*
*
* This commit introduces:
*
* - the two functions that enable main() to init and close the log:
* fsm_trigger_log_init() and fsm_trigger_log_close()
*
* - the two functions that enable main() to init and close the fsm:
* fsm_init() and fsm_close()
*
* - the two functions that enable the fsm to init and close its structures:
* fsm_structures_init() and fsm_structures_close()
*
* This file is part of Gem-graph; Client fsm (finite state machine) header.
*
* @see readme.docs and this text below.
*
* ---
*
* The two log structures and the two enums listed below stay in the fsm header.
* The two log structures and the two enums listed below are defined in the fsm
* header.
*
* All log functions are now in dedicated files.
* All log functions are in dedicated files.
*
* The most important function: fsm_add_log() is in the file:
* /src/fsm/log/manager.c
@ -121,18 +107,18 @@
*/
enum fsm_enum_log_severity {
FATAL, /**< (or CRITICAL) an unrecoverable failure that prevents the whole
application from doing any further useful work */
application from doing any further useful work 🕳️☠️ */
ERROR, /**< an irremediable situation that hinders the execution of a
specific operation within the application */
specific operation within the application 👀️😮️ */
WARN, /**< something unexpected has occurred, but the application can
continue to function normally for the time being */
continue to function normally for the time being 😅️ */
INFO, /**< (or MESSAGE) a significant event occurs while the system is
operating normally */
operating normally 📜️👌️ */
DEBUG, /**< a description of system states in sufficient detail to give
developers clues as to the cause of an error */
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 cost in terms of performance 🥱️ */
};//.😮️🧐️👀️😅️😕️😱️😦️🕳️😵‍💫️
/**
* A list of structures or states that may be involved in program events.
@ -192,22 +178,22 @@ enum fsm_enum_log_source {
* @callergraph
* @see fsm_log_struct
*/
typedef struct fsm_log_struct_unit
typedef struct fsm_log_unit_struct
{
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 */
struct fsm_log_unit_struct *prev; /**< * chained list */
struct fsm_log_unit_struct *next; /**< * chained list */
}
fsm_log_struct_unit;
fsm_log_unit_struct;
/**
* Two links towards the previous and the next unit are required to initialize
* and manage a double-chained list.
* Log is a double-chained list. Two links towards the previous and the next unit
* are required to initialize and manage it.
*
* @callgraph
* @see fsm_log_struct_unit
@ -222,8 +208,8 @@ typedef struct fsm_log_struct_unit
* @see fsm_remove_log()
*/
typedef struct {
fsm_log_struct_unit *first; /**< * required */
fsm_log_struct_unit *last; /**< * required */
fsm_log_unit_struct *first; /**< * required */
fsm_log_unit_struct *last; /**< * required */
}
fsm_log_struct;
@ -255,8 +241,8 @@ void fsm_add_log (int severity,
const char *function_source,
const char *string_value);
void fsm_trigger_log_init();
void fsm_trigger_log_close();
void fsm_relay_init_log();
void fsm_relay_close_log();
void fsm_init (const char *initial_message_from_main);
void fsm_close (const char *final_message_from_main);

51
src/fsm/control.c
View File

@ -1,8 +1,9 @@
/**
* @file
* Client fsm (Finite State Machine) control file.
* @brief This file is part of Gem-graph; it controls the client fsm
* (Finite State Machine).
*
* ---
* @details
*
* The fsm control instance
* - **initialises** the log and the rest of the fsm when triggered by main()
@ -10,35 +11,8 @@
* - **closes** all the elements it opened before handing over to main()
* .
*
* About code organization, see src/readme.dox
*
* ---
*
* @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
*
* @file
* @brief
*
* This file is part of Gem-graph.
*
* @details
* The Finite State Machine (fsm) describes all the possible states of the
* Gem-graph client and all the transitions between them.
* It manages several kinds of exclusive states:
@ -64,6 +38,10 @@
*
* The journal is created, edited and published from here.
*
* ---
*
* About code organization, see src/readme.dox
*
* @cond LICENSE
* Copyright © 2021 Libre en Communs <contact@a-lec.org>
* Copyright © 2021-2024 Adrien Bourmault <neox@a-lec.org>
@ -141,7 +119,10 @@ static void fsm_structures_close()
/**
* @brief fsm_init() is the first function called by main.c
* It initiates the journal and calls fsm_structures_init() that
* It initiates the journal and calls fsm_structures_init().
*
* It uses the relay function fsm_relay_init_log() in src/fsm/log/manager.c to
* reach the fsm_init_log().
*
* @since 2024-08
*
@ -149,7 +130,7 @@ static void fsm_structures_close()
* @see main()
*
* @callgraph
* @see trigger_fsm_log_init()
* @see fsm_relay_init_log()
* @see fsm_add_log()
* @see fsm_list_init_measures()
* @see fsm_list_init_results()
@ -160,9 +141,7 @@ static void fsm_structures_close()
*/
void fsm_init (const char *initial_info_from_main)
{
fsm_trigger_log_init(); /**< fsm_init_log(() can't be called from here
* because static fsm_log_struct gg_logs
* is in src/fsm/log/manager.c */
fsm_relay_init_log();
fsm_add_log (INFO, MAIN, "main", initial_info_from_main,
"👋️ (☕️) Hi everybody ! Here is Gem-Graph.");
@ -194,7 +173,7 @@ void fsm_init (const char *initial_info_from_main)
*
* @callgraph
* @see fsm_structures_close()
* @see fsm_trigger_log_close()
* @see fsm_relay_close_log()
* @see fsm_add_log()
*
* @param *closing_info_from_main
@ -208,7 +187,7 @@ void fsm_close (const char *closing_info_from_main)
fsm_add_log (INFO, MAIN, "main", closing_info_from_main,
"👋️😄️ That'all folks !");
fsm_trigger_log_close(); /**< fsm_clear_log(() can't be called from here
fsm_relay_close_log(); /**< fsm_clear_log(() can't be called from here
* because static fsm_log_struct gg_logs
* is in src/fsm/log/manager.c */
}

11
src/fsm/log/appendix.c
View File

@ -1,8 +1,9 @@
/**
* @file
*
* This file is part of Gem-graph. The log (or journal) stores chronologically
* the events during a session run (rules exec, mainly)
* This file is part of Gem-graph; it contains only auxiliary functions.
*
* The log (or journal) stores chronologically the events during a session run.
*
* This file groups some functions that a typical list should implement but whose
* utility remains to evaluate in the case of a log list.
@ -50,7 +51,7 @@ long fsm_remove_log (fsm_log_struct *jj,
const char *string_value)
{
long usec;
fsm_log_struct_unit *tmp = jj->last;
fsm_log_unit_struct *tmp = jj->last;
if (! tmp) return -1;
usec = tmp->usec;
jj->last = tmp->prev;
@ -72,7 +73,7 @@ long fsm_remove_log (fsm_log_struct *jj,
*/
int fsm_get_log_length (fsm_log_struct jj)
{
fsm_log_struct_unit *a_unit = jj.first;
fsm_log_unit_struct *a_unit = jj.first;
int nb = 0;
while (a_unit)
{
@ -100,7 +101,7 @@ void fsm_seek_log (fsm_log_struct jj,
const char *function_source,
const char *string_value)
{
fsm_log_struct_unit *a_unit = jj.first;
fsm_log_unit_struct *a_unit = jj.first;
int nb = 0;
while (a_unit)
{

69
src/fsm/log/manager.c
View File

@ -1,14 +1,15 @@
/**
* @file
* @brief fsm (Finite State Machine) log manager
*
* This file is part of Gem-graph.
* @brief This file is part of Gem-graph; fsm (Finite State Machine) log manager.
*
* @details
* The log (journal) is created, edited and published from here.
* This file contains only (1) the static fsm_log_struct gg_logs
* and (2) the function fsm_add_log() that all calls must pass through to send a
* message to the log.
*
* This file contains only
* -# the static fsm_log_struct **gg_logs**
* -# the function fsm_add_log() that all calls must pass through to send a
* message to the log and
* -# the two relay functions that init and publish the log before closing it.
*
* @cond LICENSE
* Copyright © 2021 Libre en Communs <contact@a-lec.org>
@ -38,33 +39,34 @@
*******************************************************************************/
/**
* The fsm_struct_journal (gg_logs) is a static instance in the file
* The fsm_struct_journal (gg_logs) is a **static** instance in the file
* /src/fsm/log/manager.c
* Therefore, all the functions that read or write it are in this file.
* This helps to avoid uncontrolled operations.
* Therefore, all the functions that read or write it must be in the same file.
*
* Limiting the access to gg_logs helps to avoid uncontrolled operations on it.
*/
static fsm_log_struct gg_logs;
/**
* @brief It is mandatory for any event to call this function to be published in
* the journal.
* @brief To be published in the log, all events must pass through this function,
* which enables filtering.
*
* @details The fsm_struct_journal (gg_logs) is a static instance in the file
* /src/fsm/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.
* @details This function is both a relay and a filter.
*
* A message is send to the log for each documented event.
* - It is a relay because it must call fsm_add_log_event() and pass it **gg_logs**
* to write to the log. As gg_logs is a **static** instance, this call can only
* be made from the same file.
*
* One or several filters can be applied here (and only here) before publication,
* to select only some events of interest (during debugging, for example).
* - It's more than just a relay, because one or more filters can be applied here
* (and only here) before publication to select only certain events.
* The interest of events can vary according to the type of session.
*
* These filters can operate on any the following five parameters:
* severity, source, file_source (text), function_source (text),
* string_value (text).
* - severity, - source, - file_source (text), - function_source (text),
* - string_value (text).
*
* They can be combined using any logical operators and parentheses.
* The filters can be combined using any logical operators and parentheses.
*
* @since 2024-08
*
@ -102,11 +104,15 @@ void fsm_add_log (int severity,
fsm_add_log_event (&gg_logs, file_source, function_source, string_value);
}
/**
* this function is a relay: fsm_init_log() can't be called directly from
* fsm_init() in control because static fsm_log_struct gg_logs is in
* src/fsm/log/manager.c
* This function is only a relay: it calls fsm_init_log() and this call couldn't
* be written in another file because the fsm_log_struct **gg_logs** it transmits
* is **static** in src/fsm/log/manager.c
*
* Limiting the access to **gg_logs** helps to avoid uncontrolled operations on it.
*
* Functions which only relay should not send log.
*
* @since 2024-08
*
@ -114,15 +120,20 @@ void fsm_add_log (int severity,
* @see main()
*
*/
void fsm_trigger_log_init()
void fsm_relay_init_log()
{
fsm_init_log (&gg_logs);
}
/**
* this function is a relay: fsm_publish_log() and fsm_clear_log() can't be
* called directly from fsm_close() in control because static fsm_log_struct
* gg_logs is in src/fsm/log/manager.c
* This function is only a relay: it calls fsm_publish_log() and fsm_clear_log()
* and this calls couldn't be written in another file because the fsm_log_struct
* **gg_logs** they transmit is **static** in src/fsm/log/manager.c
*
* Limiting the access to **gg_logs** helps to avoid uncontrolled operations on it.
*
* Functions which only relay should not send log.
*
* @since 2024-08
*
@ -130,7 +141,7 @@ void fsm_trigger_log_init()
* @see main()
*
*/
void fsm_trigger_log_close()
void fsm_relay_close_log()
{
fsm_publish_log (gg_logs);
fsm_clear_log (&gg_logs);

10
src/fsm/log/oper.c
View File

@ -68,8 +68,8 @@ void fsm_init_log (fsm_log_struct *jj)
*/
void fsm_clear_log (fsm_log_struct *jj)
{
fsm_log_struct_unit *tmp;
fsm_log_struct_unit *a_unit = jj->first;
fsm_log_unit_struct *tmp;
fsm_log_unit_struct *a_unit = jj->first;
while(a_unit)
{
tmp = a_unit;
@ -84,7 +84,7 @@ void fsm_clear_log (fsm_log_struct *jj)
/**
* add an event
*
* *new_unit = malloc (sizeof(fsm_log_struct_unit));
* *new_unit = malloc (sizeof(fsm_log_unit_struct));
*
* warn: is never free (as new log units are never removed)
*
@ -102,7 +102,7 @@ void fsm_add_log_event (fsm_log_struct *jj,
{
struct timeval tv;
gettimeofday (&tv, NULL);
fsm_log_struct_unit *new_unit = malloc (sizeof(fsm_log_struct_unit));
fsm_log_unit_struct *new_unit = malloc (sizeof(fsm_log_unit_struct));
if (! new_unit) exit (EXIT_FAILURE);
new_unit->yy_dd_mm = tv.tv_sec;
@ -132,7 +132,7 @@ void fsm_add_log_event (fsm_log_struct *jj,
*/
void fsm_publish_log (fsm_log_struct jj)
{
fsm_log_struct_unit *a_unit = jj.last;
fsm_log_unit_struct *a_unit = jj.last;
char buf [LOG_MAX_LENGTH];
int nb = 0;
while (a_unit)