diff --git a/include/fsm.h b/include/fsm.h index 7e6654f..c8cafc6 100644 --- a/include/fsm.h +++ b/include/fsm.h @@ -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); diff --git a/src/fsm/control.c b/src/fsm/control.c index d687100..27b9a8a 100644 --- a/src/fsm/control.c +++ b/src/fsm/control.c @@ -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 - * 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 - * - * @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 * Copyright © 2021-2024 Adrien Bourmault @@ -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 */ } diff --git a/src/fsm/log/appendix.c b/src/fsm/log/appendix.c index ab92fac..4476276 100644 --- a/src/fsm/log/appendix.c +++ b/src/fsm/log/appendix.c @@ -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) { diff --git a/src/fsm/log/manager.c b/src/fsm/log/manager.c index 8b668bf..4d38b4e 100644 --- a/src/fsm/log/manager.c +++ b/src/fsm/log/manager.c @@ -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 @@ -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,35 +104,44 @@ 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 - * + * * @callergraph * @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 - * + * * @callergraph * @see main() * */ -void fsm_trigger_log_close() +void fsm_relay_close_log() { fsm_publish_log (gg_logs); fsm_clear_log (&gg_logs); diff --git a/src/fsm/log/oper.c b/src/fsm/log/oper.c index 4b4b295..2de59e9 100644 --- a/src/fsm/log/oper.c +++ b/src/fsm/log/oper.c @@ -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)