fsm.h File Reference

fsm (Finite State Machine) management header More...

#include <stdbool.h>
#include <stddef.h>
#include <string.h>
#include <gtk-4.0/gtk/gtk.h>

Classes
struct	fsm_struct_journal_unit
	structure of a journal element More...
struct	fsm_struct_journal
	required to initialise a double-chained list More...
struct	fsm_struct_list_tool
	phantom documentation More...
struct	fsm_struct_list_data
	phantom documentation More...
struct	fsm_struct_list_disp
	phantom documentation More...

Macros
#define	JOURNAL_LOG_MAX_LENGTH   255
	arbitrary
#define	n_rules   128
	arbitrary
#define	n_objects   32
	arbitrary too,
#define	n_situations   128
	and so on...

Typedefs
typedef struct fsm_struct_journal_unit	fsm_struct_journal_unit
	structure of a journal element
typedef struct fsm_struct_list_tool	fsm_struct_list_tool
	phantom documentation
typedef struct fsm_struct_list_data	fsm_struct_list_data
	phantom documentation
typedef struct fsm_struct_list_disp	fsm_struct_list_disp
	phantom documentation

Enumerations
enum	fsm_enum_journal_severity {   FATAL , ERROR , WARN , INFO ,   DEBUG , TRACE }
	Conforms to canonical log levels: FATAL, ERROR, WARN, INFO, DEBUG, TRACE. More...
enum	fsm_enum_journal_source {   SOURCE , TARGET , JOURNAL , FSM ,   PREFER , MAIN , APP , WIDGETS ,   SIGNAL , MAIN_WINDOW , DIALOG_WINDOW , MODAL_WINDOW ,   TEXT_WINDOW , AUTO_NOTIFICATION , TOPBAR , TOPBAR_LEFT ,   TOPBAR_RIGHT , TOPBAR_CENTER , SYNTH_PAGE , STATE_PAGE ,   RULES_PAGE , MEASURES_PAGE , RESULTS_PAGE , SenumYNTH_GLAREA ,   SYNTH_ALL_RESULTS , SYNTH_TIME_DEP_RESULTS , SYNTH_TIME_INDEP_RESULTS , STATE_TOP ,   STATE_BOTTOM , STATE_GLAREA , STATE_CAMERA , RULE_GEOMETRY ,   RULE_GLAREA , RULE_CAMERA , RULE_ALGEBRA , RULE_CONDITION ,   RULE_ASSIGN , RULE_ID , RULES_TREE , RULES_COMPARE ,   RULES_USE , MEASURES_TOOLS , MEASURES__ACTIVITY , MEASURES__DISPLAY ,   RESULTS , TIME_DEP_RESULTS , TIME_INDEP_RESULTS , WIDGET ,   BUTTON , SCROLL , GLAREA , TEXT ,   LABEL , TREE , SLIDER , EXPANDER ,   ENTRY , SWITCH_STATE_RULES_DATA , SLIDER_X , SLIDER_Y ,   SLIDER_Z , SLIDER_A , SLIDER_B , SLIDER_C }
	arbitrary values that can help the logging filter work more efficiently More...
enum	fsm_enum_exec_edit { EXEC , EDIT }
	phantom documentation
enum	fsm_enum_state_rules_data { SYNTH , STATE , RULES , DATA }
	phantom documentation
enum	fsm_enum_store_restore_reset { STORE , RESTORE , RESET }
	phantom documentation
enum	fsm_enum_measure_type { DATE_RULE_EXEC , RULE_EXEC_NB , OBJECT_NB , ELAPSED_TIME }
	phantom documentation

Functions
void	fsm_journal_publish (fsm_struct_journal jj)
	publish all the logs today just print in the console TODO > in a file
void	fsm_journal_init (fsm_struct_journal *jj)
	init the journal
void	fsm_journal_push_front (fsm_struct_journal *jj, const char *file_source, const char *function_source, const char *string_value)
	add an event
void	fsm_journal_clear (fsm_struct_journal *jj, const char *file_source, const char *function_source, const char *string_value)
	usefulness ? (systematic ^c)
long	fsm_journal_pop_back (fsm_struct_journal *jj, const char *file_source, const char *function_source, const char *string_value)
	remove an event
int	fsm_journal_length (fsm_struct_journal jj)
	get journal_length
void	fsm_journal_seek (fsm_struct_journal jj, long usec, const char *file_source, const char *function_source, const char *string_value)
	seek for an event
void	fsm_journal_publication_request ()
	The fsm_journal_publication_request() is called only once, by main(), just after closing the app and before ending the program.
void	fsm_journal_event (int severity, int source, const char *file_source, const char *function_source, const char *string_value)
	It is mandatory for any event to call this function to be published in the journal.
void	fsm_init (char *message)
	fsm init is the first function called by main.c It initiates the journal and the four lists: 'measures', 'results', 'displayables results' and 'preferences'.
void	fsm_list_init_preferences ()
void	fsm_list_init_measures ()
void	fsm_list_init_results ()
	phantom documentation
void	fsm_list_init_displayables ()
int	fsm_get_exec_edit ()
	some client pages (in particular "state" and "rules") will be displayed and behave differently depending on whether the fsm is in edit or run state.
int	fsm_get_state_rules_data ()
	The value of the static int choice_STATE_RULES_DATA can be one of the enum include/fsm enum fsm_enum_state_rules_data.
void	fsm_set_exec_edit (int value)
	setter for the static value: 'choice_STATE_RULES_DATA' (in this file)
void	fsm_set_state_rules_data (int value)
	setter for the static value: 'choice_STATE_RULES_DATA' (in this file)
void	fsm_set_store_restore_reset (int choice, int value)
bool	fsm_get_preferences_state ()
	getter for the static boolean: 'preferences_have_been_modified'
void	fsm_set_preferences_modified (bool value)
	setter for the static boolean: 'preferences_have_been_modified'
void	fsm_add_measure (char *measure_name)
void	fsm_add_result (char *result_name)
	phantom documentation
void	fsm_add_displayable (char *displayable_name)
void	fsm_reset_all_situations_values (int value)
void	fsm_tools_list_insert (fsm_struct_list_tool **tl, int value)
	phantom documentation
int	fsm_tools_list_pop (fsm_struct_list_tool **tl)
	phantom documentation
int	fsm_tools_list_length (fsm_struct_list_tool *tl)
	phantom documentation
void	fsm_tools_list_clear (fsm_struct_list_tool **tl)
	phantom documentation
void	fsm_tools_list_view (fsm_struct_list_tool *tl)
	phantom documentation
void	fsm_tools_list_test ()
	phantom documentation
void	fsm_rule_trig_measure (int rule_id, int object_id, int measure_id)
void	fsm_add_data (fsm_struct_list_data d, int *p_data, int *p_target)
	phantom documentation
int	fsm_get_data (fsm_struct_list_data d, int from, int to)
	phantom documentation
void	fsm_remove_data (fsm_struct_list_data d, int *p_data)
	phantom documentation

Detailed Description

fsm (Finite State Machine) management header

This file is part of Gem-graph.

Typedef Documentation

fsm_struct_journal_unit

typedef struct fsm_struct_journal_unit fsm_struct_journal_unit

structure of a journal element

See also

use in src/fsm/dispatch/fsm_journal_event()

use in src/journal/fsm_journal_push_front()

Enumeration Type Documentation

fsm_enum_journal_severity

enum fsm_enum_journal_severity

Conforms to canonical log levels: FATAL, ERROR, WARN, INFO, DEBUG, TRACE.

• * * * - J O U R N A L M E T A R U L E S - * * * *

  ref: sudo cat /var/log/messages

  structure d'un log:

• date
• rang (n° d'ordre)
• fichier
• fonction
• valeur, paramètre, descriptif, contexte,... (tout ce qui peut contribuer à améliorer la compréhension du journal) any value that can qualify the event and provides useful information when reading the log.

---

Un seul fsm_journal_event() par fonction ? sauf si cette fonction génère plusieurs autres fonctions d'intérêt ?

S'il y a deux fsm_journal_event() (begin / end) dans une fonction, ils doivent avoir la même étiquette (les mêmes valeurs) : SEVERITY & SOURCE

• * * * - J O U R N A L M E T A R U L E S - * * *
  

https://betterstack.com/community/guides/logging/logging-best-practices/ https://en.wikipedia.org/wiki/Syslog

Enumerator
FATAL	(or CRITICAL) an unrecoverable failure that prevents the whole application from doing any further useful work
ERROR	a conditions that hinder the execution of a specific operation within an application and is unrecoverable
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

fsm_enum_journal_source

enum fsm_enum_journal_source

arbitrary values that can help the logging filter work more efficiently

See also

src/fsm/dispatch/fsm_journal_event())

Function Documentation

fsm_add_data()

void fsm_add_data	(	fsm_struct_list_data	d,
		int *	p_data,
		int *	p_target
	)

phantom documentation

Parameters

d
*p_data
*p_target

fsm_add_displayable()

void fsm_add_displayable

(

char *

displayable_name

)

Date

Author

See also

Parameters

displayable_name

fsm_add_measure()

void fsm_add_measure

(

char *

measure_name

)

Since

2024-09

See also

src/widget/measure/dispatch/widget_measure_event_occurences_nb()

src/widget/measure/dispatch/widget_measure_event_occurences_dates()

src/widget/measure/dispatch/widget_measure_event_occurences_situations()

src/widget/measure/dispatch/widget_measure_time_elapsed_between_two_events()

src/widget/measure/dispatch/widget_measure_third_event_occurences_in_between()

src/fsm/dispatch/fsm_journal_event()

Parameters

*measure_name

fsm_get_data()

int fsm_get_data	(	fsm_struct_list_data	d,
		int	from,
		int	to
	)

phantom documentation

Parameters

d
from
to

fsm_get_exec_edit()

int fsm_get_exec_edit

(

)

some client pages (in particular "state" and "rules") will be displayed and behave differently depending on whether the fsm is in edit or run state.

Any function which modifies the appearance or behavior of these pages must use this getter to access the choice_EXEC_EDIT value.

see include/fsm enum fsm_enum_exec_edit { EXEC, EDIT } The current int may be replaced by a boolean . TODO

Since

2024-06

See also

src/widget/one_rule/dispatch

src/widget/state/dispatch * 2

src/signal

choice_EXEC_EDIT and

include/fsm/enum fsm_enum_exec_edit {}

Returns

choice_EXEC_EDIT

fsm_get_preferences_state()

bool fsm_get_preferences_state

(

)

getter for the static boolean: 'preferences_have_been_modified'

Since

2024-08

See also

TODO A function must obtain this boolean when it stores the current state of the fsm (including preferences) before closing the current session.

Returns

preferences_have_been_modified

fsm_get_state_rules_data()

int fsm_get_state_rules_data

(

)

The value of the static int choice_STATE_RULES_DATA can be one of the enum include/fsm enum fsm_enum_state_rules_data.

To each value is associated a different page and different possible behaviors. Any function that modifies the client window must get this value.

see include/fsm enum fsm_enum_state_rules_data { SYNTH, STATE, RULES, DATA }

Since

2024-06

See also

src/widget/topbar/left

src/signal

Returns

choice_STATE_RULES_DATA

fsm_init()

void fsm_init

(

char *

initial_INFO_from_main

)

fsm init is the first function called by main.c It initiates the journal and the four lists: 'measures', 'results', 'displayables results' and 'preferences'.

The items selected in these lists define the current state of the fsm.

Since

2024-08

See also

src/main/main()

src/journal/fsm_journal_init()

src/fsm/dispatch/fsm_journal_event()

src/fsm/measures/manager/fsm_list_init_measures()

src/fsm/results/manager/fsm_list_init_results()

src/fsm/preferences/manager/fsm_list_init_displayables()

src/fsm/preferences/manager/fsm_list_init_preferences()

Parameters

*initial_INFO_from_main

fsm_journal_clear()

void fsm_journal_clear	(	fsm_struct_journal *	jj,
		const char *	file_source,
		const char *	function_source,
		const char *	string_value
	)

usefulness ? (systematic ^c)

Since

2024-09

Parameters

*jj
*file_source
*function_source
*string_value

fsm_journal_event()

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

It is mandatory for any event to call this function to be published in the journal.

Before publication, a filter can be applied here (and only here) to select only some events of interest (during debugging, for example)

If there are too many events, a filter can be applied here to select a few interesting events for publication in the log.

This filter can operate on any the following five parameters: severity, source, *file_source, *function_source, *string_value.

See also

below (params)

Simple filters (on a single parameter) can be combined using the logical operators 'and' and 'or' and parentheses.

Use: $ grep -r "fsm_journal_event" to confirm the callergraph calls.

Since

2024-08

See also

src/journal.c/fsm_journal_push_front()

src/main/main()

src/widget/topbar/modal.c

src/widget/topbar/right.c

src/widget/topbar/dialog.c

src/widget/topbar/left.c

src/widget/topbar/dispatch.c * 3

src/widget/one_rule/dispatch.c

src/widget/one_rule/algebra/conditions.c * 2

src/widget/measure/dispatch.c

src/widget/dispatch.c * 3

src/widget/all_rules/dispatch.c

src/fsm/preferences/manager.c * 8

src/fsm/measures/manager.c * 2

src/fsm/measures/tools_list.c * 4

src/fsm/dispatch.c * 10

src/fsm/results/manager.c

src/util/tree.c

src/signal.c * 38

Parameters

severity

<>

See also

enum fsm_enum_journal_severity in include/fsm.h 'severity' is a pre-defined value that must be associated to each event. It ranges from zero to six : CRITICAL ERROR WARNING INFO INFO DEBUG TRACE 0 1 2 3 4 5 6

Parameters

source

<>

See also

enum fsm_enum_journal_source in include/fsm.h 'source' is a pre-defined value that can be associated to each event. It is not mandatory. It can be set to 'NULL'.

Parameters

*file_source	<> the name of the file that emits the event.
*function_source	<> the function that emits the event.
*string_value	<> any value that can qualify the event and provides useful information when reading the log.

fsm_journal_init()

void fsm_journal_init

(

fsm_struct_journal *

jj

)

init the journal

Since

2024-09

Parameters

*jj

fsm_journal_length()

int fsm_journal_length

(

fsm_struct_journal

jj

)

get journal_length

Since

2024-09

Parameters

*jj

Returns

journal length

fsm_journal_pop_back()

long fsm_journal_pop_back	(	fsm_struct_journal *	jj,
		const char *	file_source,
		const char *	function_source,
		const char *	string_value
	)

remove an event

Since

2024-09

Parameters

*jj
*file_source
*function_source
*string_value

fsm_journal_publication_request()

void fsm_journal_publication_request

(

)

The fsm_journal_publication_request() is called only once, by main(), just after closing the app and before ending the program.

This is to guarantee the chronological order of the events in the journal.

The log is modified for each event but events can be send asynchronously. This is why the journal is only published once, before the end of "main()", Its chronological order is therefore guaranteed.

src/journal.c/fsm_journal_publish() (called here) is the last function of the program to be executed.

The fsm_struct_journal (gg_logs) is a static instance in this file. Therefore, all the functions that read or write it are in this file. This is to avoid uncontrolled operations on it.

Since

2024-08

See also

src/main/main()

src/journal/fsm_journal_publish()

fsm_journal_publish()

void fsm_journal_publish

(

fsm_struct_journal

jj

)

publish all the logs today just print in the console TODO > in a file

Since

2024-09

Parameters

*jj

fsm_journal_push_front()

void fsm_journal_push_front	(	fsm_struct_journal *	jj,
		const char *	file_source,
		const char *	function_source,
		const char *	string_value
	)

add an event

Since

2024-09

Parameters

*jj
*file_source
*function_source
*string_value

fsm_journal_seek()

void fsm_journal_seek	(	fsm_struct_journal	jj,
		long	usec,
		const char *	file_source,
		const char *	function_source,
		const char *	string_value
	)

seek for an event

Since

2024-09

Parameters

*jj
usec
*file_source
*function_source
*string_value

fsm_list_init_displayables()

void fsm_list_init_displayables

(

)

Date

Author

See also

fsm_list_init_measures()

void fsm_list_init_measures

(

)

Since

2024-09

See also

src/fsm/dispatch/fsm_init()

fsm_list_init_preferences()

void fsm_list_init_preferences

(

)

Date

Author

See also

fsm_remove_data()

void fsm_remove_data	(	fsm_struct_list_data	d,
		int *	p_data
	)

phantom documentation

Parameters

d
*p_data

fsm_reset_all_situations_values()

void fsm_reset_all_situations_values

(

int

value

)

Date

Author

See also

Parameters

value

fsm_rule_trig_measure()

void fsm_rule_trig_measure	(	int	rule_id,
		int	object_id,
		int	measure_id
	)

Since

2024-09

Parameters

rule_id
object_id
measure_id

fsm_set_exec_edit()

void fsm_set_exec_edit

(

int

choice

)

setter for the static value: 'choice_STATE_RULES_DATA' (in this file)

see include/fsm enum fsm_enum_exec_edit { EXEC, EDIT }

Since

2024-08

See also

src/signal * 2

Parameters

choice

< a boolean value which can be "EXEC" or "EDIT"

fsm_set_preferences_modified()

void fsm_set_preferences_modified

(

bool

value

)

setter for the static boolean: 'preferences_have_been_modified'

Since

2024-08

See also

TODO To be used by any function that modifies the current user preferences

fsm_journal_event()

Parameters

value

= TRUE if preferences_have_been_modified.

fsm_set_state_rules_data()

void fsm_set_state_rules_data

(

int

choice

)

setter for the static value: 'choice_STATE_RULES_DATA' (in this file)

see include/fsm enum fsm_enum_state_rules_data { SYNTH, STATE, RULES, DATA } Today (2024-10) the initial page is set to 'SYNTH'.

See also

line 292 choice_STATE_RULES_DATA = SYNTH; NB This choice can be temporarily modified for debugging purpose:

end of the function: fsm/dispatch.c window_design_topbar_left()

Since

2024-08

See also

src/signal * 4

Parameters

choice

fsm_set_store_restore_reset()

void fsm_set_store_restore_reset	(	int	choice,
		int	value
	)

Date

Author

See also

Parameters

choice
value