460 lines
10 KiB
Groff
460 lines
10 KiB
Groff
|
.TH "src/fsm/dispatch.c" 3 "Version 0.1.0" "Gem-graph" \" -*- nroff -*-
|
||
|
|
.ad l
|
||
|
|
.nh
|
||
|
|
.SH NAME
|
||
|
|
src/fsm/dispatch.c \-
|
||
|
|
.IP "\(bu" 2
|
||
|
|
OOOOOOOOOOO OOOOO OOO OOO * OO OO OO OOOO OOOO * OO OO OO OO OO OO * OOOOOO OO OO OO OO OO * OO OO OO OOO OO * OO OO OO OO * OO OO OOO OO OO * OO OOOOOO OO OO *
|
||
|
|
.IP " \(bu" 4
|
||
|
|
|
||
|
|
.PP
|
||
|
|
|
||
|
|
.PP
|
||
|
|
|
||
|
|
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.br
|
||
|
|
.PP
|
||
|
|
\fC#include <stdbool\&.h>\fP
|
||
|
|
.br
|
||
|
|
\fC#include '\&.\&./\&.\&./include/fsm\&.h'\fP
|
||
|
|
.br
|
||
|
|
\fC#include '\&.\&./\&.\&./include/util\&.h'\fP
|
||
|
|
.br
|
||
|
|
\fC#include '\&.\&./\&.\&./include/widget\&.h'\fP
|
||
|
|
.br
|
||
|
|
|
||
|
|
.SS "Functions"
|
||
|
|
|
||
|
|
.in +1c
|
||
|
|
.ti -1c
|
||
|
|
.RI "void \fBfsm_journal_publication_request\fP ()"
|
||
|
|
.br
|
||
|
|
.RI "The \fBfsm_journal_publication_request()\fP is called only once, by \fBmain()\fP, just after closing the app and before ending the program\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "void \fBfsm_journal_event\fP (int severity, int source, const char *file_source, const char *function_source, const char *string_value)"
|
||
|
|
.br
|
||
|
|
.RI "It is mandatory for any event to call this function to be published in the journal\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "void \fBfsm_init\fP (char *initial_message_from_main)"
|
||
|
|
.br
|
||
|
|
.RI "F S M I N I T *\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "void \fBfsm_set_preferences_modified\fP (bool value)"
|
||
|
|
.br
|
||
|
|
.RI "setter for the static boolean: 'preferences_have_been_modified' "
|
||
|
|
.ti -1c
|
||
|
|
.RI "bool \fBfsm_get_preferences_state\fP ()"
|
||
|
|
.br
|
||
|
|
.RI "getter for the static boolean: 'preferences_have_been_modified' "
|
||
|
|
.ti -1c
|
||
|
|
.RI "int \fBfsm_get_exec_edit\fP ()"
|
||
|
|
.br
|
||
|
|
.RI "Any function that modifies the client window must obtain this boolean\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "int \fBfsm_get_state_rules_data\fP ()"
|
||
|
|
.br
|
||
|
|
.RI "Any function that modifies the client window must obtain this value\&. "
|
||
|
|
.ti -1c
|
||
|
|
.RI "void \fBfsm_set_exec_edit\fP (int choice)"
|
||
|
|
.br
|
||
|
|
.RI "setter for the static value: 'choice_STATE_RULES_DATA' (in this file) "
|
||
|
|
.ti -1c
|
||
|
|
.RI "void \fBfsm_set_state_rules_data\fP (int choice)"
|
||
|
|
.br
|
||
|
|
.RI "setter for the static value: 'choice_STATE_RULES_DATA' (in this file) "
|
||
|
|
.in -1c
|
||
|
|
.SH "Detailed Description"
|
||
|
|
.PP
|
||
|
|
|
||
|
|
.IP "\(bu" 2
|
||
|
|
OOOOOOOOOOO OOOOO OOO OOO * OO OO OO OOOO OOOO * OO OO OO OO OO OO * OOOOOO OO OO OO OO OO * OO OO OO OOO OO * OO OO OO OO * OO OO OOO OO OO * OO OOOOOO OO OO *
|
||
|
|
.IP " \(bu" 4
|
||
|
|
|
||
|
|
.PP
|
||
|
|
|
||
|
|
.PP
|
||
|
|
|
||
|
|
|
||
|
|
This Finite State Machine (fsm) describes all the possible states of the Gem-graph client and all the transitions between these states\&.
|
||
|
|
.PP
|
||
|
|
gem-graph-client fsm (Finite State Machine) manages four topics:
|
||
|
|
.IP "\(bu" 2
|
||
|
|
engine (window appearance)
|
||
|
|
.IP "\(bu" 2
|
||
|
|
measures (current measurements)
|
||
|
|
.IP "\(bu" 2
|
||
|
|
results (current data acquisition and displays)
|
||
|
|
.IP "\(bu" 2
|
||
|
|
preferences (current user preferences)
|
||
|
|
.PP
|
||
|
|
.PP
|
||
|
|
Each state of the finite state machine (fsm) is a combination of their states\&.
|
||
|
|
.PP
|
||
|
|
It must be
|
||
|
|
.IP "\(bu" 2
|
||
|
|
saved at the end of a work session and
|
||
|
|
.IP "\(bu" 2
|
||
|
|
reread (available) at the start of a new session\&.
|
||
|
|
.PP
|
||
|
|
.PP
|
||
|
|
No state of the fsm should be defined in another module\&. No fsm transition needs to be executed in another module\&.
|
||
|
|
.PP
|
||
|
|
The journal is created, edited and published from here\&.
|
||
|
|
.SH "Function Documentation"
|
||
|
|
.PP
|
||
|
|
.SS "int fsm_get_exec_edit ()"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
Any function that modifies the client window must obtain this boolean\&. The 'state' and 'rules' pages appearance depends heavily on this\&.
|
||
|
|
.PP
|
||
|
|
see include/fsm enum fsm_enum_exec_edit { EXEC, EDIT } The current int may be replaced by a boolean before publication\&. TODO
|
||
|
|
.PP
|
||
|
|
\fBDate\fP
|
||
|
|
.RS 4
|
||
|
|
2024-08
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBAuthor\fP
|
||
|
|
.RS 4
|
||
|
|
Jean
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBSee also\fP
|
||
|
|
.RS 4
|
||
|
|
src/widget/one_rule/dispatch
|
||
|
|
.PP
|
||
|
|
src/widget/state/dispatch * 2
|
||
|
|
.PP
|
||
|
|
src/signal
|
||
|
|
.PP
|
||
|
|
include/fsm enum fsm_enum_exec_edit { EXEC, EDIT } << TODO check this
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBReturns\fP
|
||
|
|
.RS 4
|
||
|
|
choice_EXEC_EDIT
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
|
||
|
|
.SS "bool fsm_get_preferences_state ()"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
getter for the static boolean: 'preferences_have_been_modified'
|
||
|
|
.PP
|
||
|
|
\fBDate\fP
|
||
|
|
.RS 4
|
||
|
|
2024-08
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBAuthor\fP
|
||
|
|
.RS 4
|
||
|
|
Jean
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBSee also\fP
|
||
|
|
.RS 4
|
||
|
|
TODO A function must obtain this boolean when it stores the current state of the fsm (including \fBpreferences\fP) before closing the current session\&.
|
||
|
|
.PP
|
||
|
|
(none)
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBReturns\fP
|
||
|
|
.RS 4
|
||
|
|
preferences_have_been_modified
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
|
||
|
|
.SS "int fsm_get_state_rules_data ()"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
Any function that modifies the client window must obtain this value\&. The pages selection and the window appearance depends heavily on this\&.
|
||
|
|
.PP
|
||
|
|
see include/fsm enum fsm_enum_state_rules_data { SYNTH, STATE, RULES, DATA }
|
||
|
|
.PP
|
||
|
|
\fBDate\fP
|
||
|
|
.RS 4
|
||
|
|
2024-08
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBAuthor\fP
|
||
|
|
.RS 4
|
||
|
|
Jean
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBSee also\fP
|
||
|
|
.RS 4
|
||
|
|
src/widget/topbar/left
|
||
|
|
.PP
|
||
|
|
src/signal
|
||
|
|
.PP
|
||
|
|
(none)
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBReturns\fP
|
||
|
|
.RS 4
|
||
|
|
choice_STATE_RULES_DATA
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
|
||
|
|
.SS "void fsm_init (char * initial_message_from_main)"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
F S M I N I T *\&. This is the first function called by '\fBmain\&.c\fP' It initiates the journal and four lists which are: 'measures', 'results', 'displayables results' and 'preferences'\&. These lists will be used to define the current state of the fsm\&.
|
||
|
|
.PP
|
||
|
|
\fBDate\fP
|
||
|
|
.RS 4
|
||
|
|
2024-08
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBAuthor\fP
|
||
|
|
.RS 4
|
||
|
|
Jean
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBSee also\fP
|
||
|
|
.RS 4
|
||
|
|
src/main/main()
|
||
|
|
.PP
|
||
|
|
src/journal/fsm_journal_init()
|
||
|
|
.PP
|
||
|
|
src/fsm/dispatch/fsm_journal_event()
|
||
|
|
.PP
|
||
|
|
src/fsm/measures/manager/fsm_list_init_measures()
|
||
|
|
.PP
|
||
|
|
src/fsm/results/manager/fsm_list_init_results()
|
||
|
|
.PP
|
||
|
|
src/fsm/preferences/manager/fsm_list_init_displayables()
|
||
|
|
.PP
|
||
|
|
src/fsm/preferences/manager/fsm_list_init_preferences()
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBParameters\fP
|
||
|
|
.RS 4
|
||
|
|
\fI*initial_message_from_main\fP
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
|
||
|
|
.SS "void fsm_journal_event (int severity, int source, const char * file_source, const char * function_source, const char * string_value)"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
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)\&.
|
||
|
|
.PP
|
||
|
|
If there are too many events, a filter can be applied here to select a few interesting events for publication in the log\&.
|
||
|
|
.PP
|
||
|
|
This filter can operate on any the following five parameters: severity, source, *file_source, *function_source, *string_value\&.
|
||
|
|
.PP
|
||
|
|
\fBSee also\fP
|
||
|
|
.RS 4
|
||
|
|
below (params)
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
Simple filters (on a single parameter) can be combined using the logical operators 'and' and 'or' and parentheses\&.
|
||
|
|
.PP
|
||
|
|
Use: $ grep -r 'fsm_journal_event' to confirm the callergraph calls\&.
|
||
|
|
.PP
|
||
|
|
\fBDate\fP
|
||
|
|
.RS 4
|
||
|
|
2024-08
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBAuthor\fP
|
||
|
|
.RS 4
|
||
|
|
Jean
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBSee also\fP
|
||
|
|
.RS 4
|
||
|
|
src/journal\&.c/fsm_journal_push_front()
|
||
|
|
.PP
|
||
|
|
src/main/main()
|
||
|
|
.PP
|
||
|
|
src/widget/topbar/modal\&.c
|
||
|
|
.PP
|
||
|
|
src/widget/topbar/right\&.c
|
||
|
|
.PP
|
||
|
|
src/widget/topbar/dialog\&.c
|
||
|
|
.PP
|
||
|
|
src/widget/topbar/left\&.c
|
||
|
|
.PP
|
||
|
|
src/widget/topbar/dispatch\&.c * 3
|
||
|
|
.PP
|
||
|
|
src/widget/one_rule/dispatch\&.c
|
||
|
|
.PP
|
||
|
|
src/widget/one_rule/algebra/conditions\&.c * 2
|
||
|
|
.PP
|
||
|
|
src/widget/measure/dispatch\&.c
|
||
|
|
.PP
|
||
|
|
src/widget/dispatch\&.c * 3
|
||
|
|
.PP
|
||
|
|
src/widget/all_rules/dispatch\&.c
|
||
|
|
.PP
|
||
|
|
\fBsrc/fsm/preferences/manager\&.c\fP * 8
|
||
|
|
.PP
|
||
|
|
src/fsm/measures/manager\&.c * 2
|
||
|
|
.PP
|
||
|
|
src/fsm/measures/tools_list\&.c * 4
|
||
|
|
.PP
|
||
|
|
\fBsrc/fsm/dispatch\&.c\fP * 10
|
||
|
|
.PP
|
||
|
|
src/fsm/results/manager\&.c
|
||
|
|
.PP
|
||
|
|
src/util/tree\&.c
|
||
|
|
.PP
|
||
|
|
src/signal\&.c * 38
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBParameters\fP
|
||
|
|
.RS 4
|
||
|
|
\fIseverity\fP <>
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBSee also\fP
|
||
|
|
.RS 4
|
||
|
|
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 MESSAGE DEBUG SPEW 0 1 2 3 4 5 6
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBParameters\fP
|
||
|
|
.RS 4
|
||
|
|
\fIsource\fP <>
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBSee also\fP
|
||
|
|
.RS 4
|
||
|
|
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'\&.
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBParameters\fP
|
||
|
|
.RS 4
|
||
|
|
\fI*file_source\fP <> the name of the file that emits the event\&.
|
||
|
|
.br
|
||
|
|
\fI*function_source\fP <> the function that emits the event\&.
|
||
|
|
.br
|
||
|
|
\fI*string_value\fP <> any value that can qualify the event and provides useful information when reading the log\&.
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
|
||
|
|
.SS "void fsm_journal_publication_request ()"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
The \fBfsm_journal_publication_request()\fP is called only once, by \fBmain()\fP, just after closing the app and before ending the program\&. This is to guarantee the chronological order of the events in the journal\&.
|
||
|
|
.PP
|
||
|
|
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\&.
|
||
|
|
.PP
|
||
|
|
src/journal\&.c/fsm_journal_publish() (called here) is the last function of the program to be executed\&.
|
||
|
|
.PP
|
||
|
|
The \fBfsm_struct_journal\fP (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\&.
|
||
|
|
.PP
|
||
|
|
\fBDate\fP
|
||
|
|
.RS 4
|
||
|
|
2024-08
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBAuthor\fP
|
||
|
|
.RS 4
|
||
|
|
Jean
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBSee also\fP
|
||
|
|
.RS 4
|
||
|
|
src/main/main()
|
||
|
|
.PP
|
||
|
|
src/journal/fsm_journal_publish()
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
|
||
|
|
.SS "void fsm_set_exec_edit (int choice)"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
setter for the static value: 'choice_STATE_RULES_DATA' (in this file) see include/fsm enum fsm_enum_exec_edit { EXEC, EDIT }
|
||
|
|
.PP
|
||
|
|
\fBDate\fP
|
||
|
|
.RS 4
|
||
|
|
2024-08
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBAuthor\fP
|
||
|
|
.RS 4
|
||
|
|
Jean
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBSee also\fP
|
||
|
|
.RS 4
|
||
|
|
(none)
|
||
|
|
.PP
|
||
|
|
src/signal * 2
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBParameters\fP
|
||
|
|
.RS 4
|
||
|
|
\fIchoice\fP < a boolean value which can be 'EXEC' or 'EDIT'
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
|
||
|
|
.SS "void fsm_set_preferences_modified (bool value)"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
setter for the static boolean: 'preferences_have_been_modified'
|
||
|
|
.PP
|
||
|
|
\fBDate\fP
|
||
|
|
.RS 4
|
||
|
|
2024-08
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBAuthor\fP
|
||
|
|
.RS 4
|
||
|
|
Jean
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBSee also\fP
|
||
|
|
.RS 4
|
||
|
|
TODO To be used by any function that modifies the current user \fBpreferences\fP
|
||
|
|
.PP
|
||
|
|
\fBfsm_journal_event()\fP
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBParameters\fP
|
||
|
|
.RS 4
|
||
|
|
\fIvalue\fP = TRUE if preferences_have_been_modified\&.
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
|
||
|
|
.SS "void fsm_set_state_rules_data (int choice)"
|
||
|
|
|
||
|
|
.PP
|
||
|
|
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'\&.
|
||
|
|
.PP
|
||
|
|
\fBSee also\fP
|
||
|
|
.RS 4
|
||
|
|
line 292 choice_STATE_RULES_DATA = SYNTH; NB This choice can be temporarily modified for debugging purpose:
|
||
|
|
.PP
|
||
|
|
end of the function: \fBfsm/dispatch\&.c\fP window_design_topbar_left()
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBDate\fP
|
||
|
|
.RS 4
|
||
|
|
2024-08
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBAuthor\fP
|
||
|
|
.RS 4
|
||
|
|
Jean
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBSee also\fP
|
||
|
|
.RS 4
|
||
|
|
src/signal * 4
|
||
|
|
.PP
|
||
|
|
(none)
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
\fBParameters\fP
|
||
|
|
.RS 4
|
||
|
|
\fIchoice\fP
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
|
||
|
|
.SH "Author"
|
||
|
|
.PP
|
||
|
|
Generated automatically by Doxygen for Gem-graph from the source code\&.
|