src/fsm/log/* three files created in this dir: manager.c, oper.c and appendix.c

These three files contain all the functions needed for the log to be init, build
and published.

The most important function is in the 'manager' file:

fsm_add_log (int severity,
             int source,
             const char *file_source,
             const char *function_source,
             const char *string_value)

Any event to be reported must call this function.

include/fsm.h

@@ -11,7 +11,7 @@
  *
  * 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
+ * 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
@@ -24,35 +24,29 @@
  * @endcond
  *
  *
- * The fsm header lists all the structures that the log will need.
+ * In this commit, the FSM (Finite State Machine) header only lists all the
+ * structures that the log needs. Other fsm functions will be introduced in
+ * subsequent commits. @see readme.docs and this text below.
+ *
+ * ---
  *
  * 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.
+ * All functions but the last one are now in dedicated files.
+ *
+ * The most important function: fsm_add_log() is in the file:
+ * /src/fsm/log/manager.c
+ *
+ * This file contains the declaration of the log with the static attribute,
+ * which forces 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.
+ * help to 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
@@ -70,28 +64,30 @@
  *
  * 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()
- * .
+ * The four most important executive functions needed by the log are in the
+ * dedicated file: /src/fsm/log/oper.c:
  *
- * - fsm_enum_log_severity()
- * - fsm_enum_log_source()
- * .
+ * NB: fsm_clear_log() is designed to close what was initiated by fsm_init_log().
+ * As, in this commit, fsm_publish_log() is the last instruction and no memory
+ * leaks are detected, the use of fsm_clear_log() is not required.
  *
  * - fsm_init_log()
  * - fsm_publish_log()
  * - fsm_clear_log()
  * - fsm_add_log_event()
+ * .
+ *
+ * A typical list would also feature the following three functions
+ * but in the case of a log, their usefulness remains to be demonstrated.
+ * These functions are therefore apart in the file /src/fsm/log/appendix.c
+ *
  * - fsm_get_log_length()
  * - fsm_seek_log()
  * - fsm_remove_log()
  * .
  *
- * - fsm_add_log()
- * .
  */
 
 

src/fsm/log/appendix.c

@@ -0,0 +1,112 @@
+/**
+ * @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 groups some functions that a typical list should implement but whose
+ * utility remains to evaluate in the case of a log list.
+ *
+ * @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
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include "../../../include/fsm.h"
+
+/**
+ * remove an event;
+ * the removal is a pop back
+ *
+ * @since 2024-09
+ *
+ * @param *jj
+ * @param *file_source
+ * @param *function_source
+ * @param *string_value
+ *
+ * @returns the removed event date microseconds
+ */
+long fsm_remove_log (fsm_log_struct *jj,
+                     const char *file_source,
+                     const char *function_source,
+                     const char *string_value)
+{
+    long usec;
+    fsm_log_struct_unit *tmp = jj->last;
+    if (! tmp) return -1;
+    usec = tmp->usec;
+    jj->last = tmp->prev;
+    if (jj->last) jj->last->next = NULL;
+    else jj->first = NULL;
+    free (tmp);
+    return usec;
+}
+
+
+
+/**
+ * get log length
+ *
+ * @since 2024-09
+ *
+ * @param *jj
+ * @returns log length
+ */
+int fsm_get_log_length (fsm_log_struct jj)
+{
+    fsm_log_struct_unit *a_unit = jj.first;
+    int nb = 0;
+    while (a_unit)
+    {
+        nb ++;
+        a_unit = a_unit->next;
+    }
+    return nb;
+}
+
+
+/**
+ * seek for an event
+ *
+ * @since 2024-09
+ *
+ * @param *jj
+ * @param usec
+ * @param *file_source
+ * @param *function_source
+ * @param *string_value
+ */
+void fsm_seek_log (fsm_log_struct jj,
+                   long usec,
+                   const char *file_source,
+                   const char *function_source,
+                   const char *string_value)
+{
+    fsm_log_struct_unit *a_unit = jj.first;
+    int nb = 0;
+    while (a_unit)
+    {
+        if (usec == a_unit->usec) nb++;
+        a_unit = a_unit->next;
+    }
+    if (nb > 0)  printf ("> date (usec) %ld found %d times in journal\n", usec, nb);
+    else         printf ("> date (usec) %ld not found in journal\n", usec);
+}

src/fsm/log/manager.c

@@ -0,0 +1,104 @@
+/**
+ * @file
+ * @brief fsm (Finite State Machine) log manager
+ *
+ * This file is part of Gem-graph.
+ *
+ * @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.
+ *
+ * @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
+ */
+
+#include "../../../include/fsm.h"
+
+
+/*******************************************************************************
+ *                      L O G   /   J O U R N A L                              *
+*******************************************************************************/
+
+/**
+ * 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.
+ */
+static fsm_log_struct gg_logs;
+
+
+/**
+ * @brief It is mandatory for any event to call this function to be published in
+ * the journal.
+ *
+ * @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.
+ *
+ * A message is send to the log for each documented event.
+ *
+ * If there are too many events, one or several filters can be applied
+ * here (and only here) before publication, to select only some events
+ * of interest (during debugging, for example).
+ *
+ * These filters can operate on any the following five parameters:
+ * severity, source, file_source (text), function_source (text),
+ * string_value (text).
+ *
+ * They can be combined using any logical operators and parentheses.
+ *
+ * @since 2024-08
+ *
+ * @callgraph
+ * @see fsm_add_log_event()
+ *
+ * @callergraph
+ * see fsm_init()
+ *
+ * @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)
+{
+    if
+    (
+        severity  <  TRACE
+    // &&  source == RULE_CONDITION
+    )
+    fsm_add_log_event (&gg_logs, file_source, function_source, string_value);
+}

src/fsm/log/oper.c

@@ -0,0 +1,153 @@
+/**
+ * @file
+ *
+ * This file is part of Gem-graph.
+ *
+ * The log (journal) stores chronologically the events during a session.
+ *
+ * This file contains the executive functions needed to init the log, add an
+ * event and publish the log.
+ *
+ * The log presentation is:
+ * [date - rank - source file - source function - value]
+ *
+ * Today, the log is simply printed in the console using glib/g_message();
+ * It will be printed in chronological order in a file.
+ *
+ * @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
+ */
+
+
+#include <time.h>
+#include <sys/time.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <glib.h>
+#include "../../../include/fsm.h"
+
+
+/**
+ * init the log: a double chained list
+ *
+ * first and last records are set to NULL
+ *
+ * @since 2024-09
+ *
+ * @param *jj
+ */
+void fsm_init_log (fsm_log_struct *jj)
+{
+    jj->first = NULL;
+    jj->last = NULL;
+}
+
+
+/**
+ * removes all the log content and free each unit
+ *
+ * @since 2024-09
+ *
+ * @param *jj
+ */
+void fsm_clear_log (fsm_log_struct *jj)
+{
+   fsm_log_struct_unit *tmp;
+   fsm_log_struct_unit *a_unit = jj->first;
+   while(a_unit)
+   {
+     tmp = a_unit;
+     a_unit = a_unit->next;
+     free (tmp);
+   }
+   jj->first = NULL;
+   jj->last = NULL;
+}
+
+
+/**
+ * add an event
+ *
+ * *new_unit = malloc (sizeof(fsm_log_struct_unit));
+ *
+ * warn: is never free (as new log units are never removed)
+ *
+ * @since 2024-09
+ *
+ * @param *jj
+ * @param *file_source
+ * @param *function_source
+ * @param *string_value
+ */
+void fsm_add_log_event (fsm_log_struct *jj,
+                  const char *file_source,
+                  const char *function_source,
+                  const char *string_value)
+{
+    struct timeval tv;
+    gettimeofday (&tv, NULL);
+    fsm_log_struct_unit *new_unit = malloc (sizeof(fsm_log_struct_unit));
+    if (! new_unit) exit (EXIT_FAILURE);
+
+    new_unit->yy_dd_mm = tv.tv_sec;
+    new_unit->usec = tv.tv_usec;
+    new_unit->file_source = file_source;
+    new_unit->function_source = function_source;
+    new_unit->string_value = string_value;
+
+    new_unit->next = jj->first;
+    new_unit->prev = NULL;
+    if (jj->first) jj->first->prev = new_unit;
+    else jj->last = new_unit;
+    jj->first = new_unit;
+}
+
+
+#define LOG_MAX_LENGTH 255 /**< arbitrary */
+
+/**
+ * publish all the logs chronologically (using the g_lib function: g_message)
+ *
+ * today, simply printed in the console;  TODO: print in a file
+ *
+ * @since 2024-09
+ *
+ * @param *jj
+ */
+void fsm_publish_log (fsm_log_struct jj)
+{
+    fsm_log_struct_unit *a_unit = jj.last;
+    char buf [LOG_MAX_LENGTH];
+    int nb = 0;
+    while (a_unit)
+    {
+        strftime(buf, sizeof(buf), "%D %T", localtime(&a_unit->yy_dd_mm));
+        g_message ("%s + %-6ld  %6d    %-32s %-38s %-50s",
+                   buf,
+                   a_unit->usec,
+                   nb,
+                   a_unit->file_source,
+                   a_unit->function_source,
+                   a_unit->string_value);
+        a_unit = a_unit->prev;
+        nb ++;
+    }
+}
+
+