gem-graph-client/doc/docbook/d4/d07/fsm_2dispatch_8c.xml

<?xml version='1.0' encoding='UTF-8' standalone='no'?>
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="_fsm_2dispatch_8c" xml:lang="en-US">
<title>src/fsm/dispatch.c File Reference</title>
<indexterm><primary>src/fsm/dispatch.c</primary></indexterm>
<para>

<para><itemizedlist>
<listitem>
<para>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 *<itemizedlist>
<listitem></listitem></itemizedlist>
</para>
</listitem></itemizedlist>
</para>
 
</para>
<programlisting linenumbering="unnumbered">#include &lt;stdbool.h&gt;<?linebreak?>#include &quot;../../include/fsm.h&quot;<?linebreak?>#include &quot;../../include/util.h&quot;<?linebreak?>#include &quot;../../include/widget.h&quot;<?linebreak?></programlisting><simplesect>
    <title>Functions    </title>
        <itemizedlist>
            <listitem><para>void <link linkend="_fsm_2dispatch_8c_1a435d1a5171a7d69662d701234722fee2">fsm_journal_publication_request</link> ()</para>

<para>The <link linkend="_fsm_2dispatch_8c_1a435d1a5171a7d69662d701234722fee2">fsm_journal_publication_request()</link> is called only once, by <link linkend="_main_8c_1a3c04138a5bfe5d72780bb7e82a18e627">main()</link>, just after closing the app and before ending the program. </para>
</listitem>
            <listitem><para>void <link linkend="_fsm_2dispatch_8c_1a8c67f42f95d48ee2469c9a27d65db3e6">fsm_journal_event</link> (int severity, int source, const char *file_source, const char *function_source, const char *string_value)</para>

<para>It is mandatory for any event to call this function to be published in the journal. </para>
</listitem>
            <listitem><para>void <link linkend="_fsm_2dispatch_8c_1a8d91f5868f20ad3b72cfa63787d87444">fsm_init</link> (char *initial_message_from_main)</para>

<para>F S M I N I T *. </para>
</listitem>
            <listitem><para>void <link linkend="_fsm_2dispatch_8c_1a770bcaeb0bd6f81cddcc3cd506468fff">fsm_set_preferences_modified</link> (bool value)</para>

<para>setter for the static boolean: &apos;preferences_have_been_modified&apos; </para>
</listitem>
            <listitem><para>bool <link linkend="_fsm_2dispatch_8c_1a0b0231a311d0e85723ef9fcf38be88e3">fsm_get_preferences_state</link> ()</para>

<para>getter for the static boolean: &apos;preferences_have_been_modified&apos; </para>
</listitem>
            <listitem><para>int <link linkend="_fsm_2dispatch_8c_1a9123915ffd10fe1ae18254898b1c0ebf">fsm_get_exec_edit</link> ()</para>

<para>Any function that modifies the client window must obtain this boolean. </para>
</listitem>
            <listitem><para>int <link linkend="_fsm_2dispatch_8c_1a90ab14081a88752d3721947a4922ee25">fsm_get_state_rules_data</link> ()</para>

<para>Any function that modifies the client window must obtain this value. </para>
</listitem>
            <listitem><para>void <link linkend="_fsm_2dispatch_8c_1ae921ecd39af67bb8dc0deb2cdc86125d">fsm_set_exec_edit</link> (int choice)</para>

<para>setter for the static value: &apos;choice_STATE_RULES_DATA&apos; (in this file) </para>
</listitem>
            <listitem><para>void <link linkend="_fsm_2dispatch_8c_1af5a464b19589ba1972c9b3aa3397945a">fsm_set_state_rules_data</link> (int choice)</para>

<para>setter for the static value: &apos;choice_STATE_RULES_DATA&apos; (in this file) </para>
</listitem>
        </itemizedlist>
</simplesect>
<section>
<title>Detailed Description</title>

<para><itemizedlist>
<listitem>
<para>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 *<itemizedlist>
<listitem></listitem></itemizedlist>
</para>
</listitem></itemizedlist>
</para>

<para>This Finite State Machine (fsm) describes all the possible states of the Gem-graph client and all the transitions between these states.</para>

<para>gem-graph-client fsm (Finite State Machine) manages four topics:<itemizedlist>
<listitem>
<para>engine (window appearance)</para>
</listitem><listitem>
<para>measures (current measurements)</para>
</listitem><listitem>
<para>results (current data acquisition and displays)</para>
</listitem><listitem>
<para>preferences (current user preferences)</para>
</listitem></itemizedlist>
</para>

<para>Each state of the finite state machine (fsm) is a combination of their states.</para>

<para>It must be<itemizedlist>
<listitem>
<para>saved at the end of a work session and</para>
</listitem><listitem>
<para>reread (available) at the start of a new session.</para>
</listitem></itemizedlist>
</para>

<para>No state of the fsm should be defined in another module. No fsm transition needs to be executed in another module.</para>

<para>The journal is created, edited and published from here. </para>
</section>
<section>
<title>Function Documentation</title>
<anchor xml:id="_fsm_2dispatch_8c_1a9123915ffd10fe1ae18254898b1c0ebf"/><section>
    <title>fsm_get_exec_edit()</title>
<indexterm><primary>fsm_get_exec_edit</primary><secondary>dispatch.c</secondary></indexterm>
<indexterm><primary>dispatch.c</primary><secondary>fsm_get_exec_edit</secondary></indexterm>
<para><computeroutput>int fsm_get_exec_edit ( )</computeroutput></para><para>

<para>Any function that modifies the client window must obtain this boolean. </para>
</para>

<para>The &apos;state&apos; and &apos;rules&apos; pages appearance depends heavily on this.</para>

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

<para><formalpara><title>Date</title>

<para>2024-08 </para>
</formalpara>
<formalpara><title>Author</title>

<para>Jean</para>
</formalpara>
<formalpara><title>See also</title>

<para>src/widget/one_rule/dispatch </para>

<para>src/widget/state/dispatch * 2 </para>

<para>src/signal</para>

<para>include/fsm enum fsm_enum_exec_edit { EXEC, EDIT } &lt;&lt; TODO check this</para>
</formalpara>
<formalpara><title>Returns</title>

<para>choice_EXEC_EDIT </para>
</formalpara>
</para>
</section>
<anchor xml:id="_fsm_2dispatch_8c_1a0b0231a311d0e85723ef9fcf38be88e3"/><section>
    <title>fsm_get_preferences_state()</title>
<indexterm><primary>fsm_get_preferences_state</primary><secondary>dispatch.c</secondary></indexterm>
<indexterm><primary>dispatch.c</primary><secondary>fsm_get_preferences_state</secondary></indexterm>
<para><computeroutput>bool fsm_get_preferences_state ( )</computeroutput></para><para>

<para>getter for the static boolean: &apos;preferences_have_been_modified&apos; </para>
</para>

<para><formalpara><title>Date</title>

<para>2024-08 </para>
</formalpara>
<formalpara><title>Author</title>

<para>Jean</para>
</formalpara>
<formalpara><title>See also</title>

<para>TODO A function must obtain this boolean when it stores the current state of the fsm (including <link linkend="_structpreferences">preferences</link>) before closing the current session.</para>

<para>(none)</para>
</formalpara>
<formalpara><title>Returns</title>

<para>preferences_have_been_modified </para>
</formalpara>
</para>
</section>
<anchor xml:id="_fsm_2dispatch_8c_1a90ab14081a88752d3721947a4922ee25"/><section>
    <title>fsm_get_state_rules_data()</title>
<indexterm><primary>fsm_get_state_rules_data</primary><secondary>dispatch.c</secondary></indexterm>
<indexterm><primary>dispatch.c</primary><secondary>fsm_get_state_rules_data</secondary></indexterm>
<para><computeroutput>int fsm_get_state_rules_data ( )</computeroutput></para><para>

<para>Any function that modifies the client window must obtain this value. </para>
</para>

<para>The pages selection and the window appearance depends heavily on this.</para>

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

<para><formalpara><title>Date</title>

<para>2024-08 </para>
</formalpara>
<formalpara><title>Author</title>

<para>Jean</para>
</formalpara>
<formalpara><title>See also</title>

<para>src/widget/topbar/left </para>

<para>src/signal</para>

<para>(none)</para>
</formalpara>
<formalpara><title>Returns</title>

<para>choice_STATE_RULES_DATA </para>
</formalpara>
</para>
</section>
<anchor xml:id="_fsm_2dispatch_8c_1a8d91f5868f20ad3b72cfa63787d87444"/><section>
    <title>fsm_init()</title>
<indexterm><primary>fsm_init</primary><secondary>dispatch.c</secondary></indexterm>
<indexterm><primary>dispatch.c</primary><secondary>fsm_init</secondary></indexterm>
<para><computeroutput>void fsm_init (char * initial_message_from_main)</computeroutput></para><para>

<para>F S M I N I T *. </para>
</para>

<para>This is the first function called by &apos;<link linkend="_main_8c">main.c</link>&apos; It initiates the journal and four lists which are: &apos;measures&apos;, &apos;results&apos;, &apos;displayables results&apos; and &apos;preferences&apos;. These lists will be used to define the current state of the fsm.</para>

<para><formalpara><title>Date</title>

<para>2024-08 </para>
</formalpara>
<formalpara><title>Author</title>

<para>Jean</para>
</formalpara>
<formalpara><title>See also</title>

<para>src/main/main()</para>

<para>src/journal/fsm_journal_init() </para>

<para>src/fsm/dispatch/fsm_journal_event() </para>

<para>src/fsm/measures/manager/fsm_list_init_measures() </para>

<para>src/fsm/results/manager/fsm_list_init_results() </para>

<para>src/fsm/preferences/manager/fsm_list_init_displayables() </para>

<para>src/fsm/preferences/manager/fsm_list_init_preferences()</para>
</formalpara>

                <formalpara>
                    <title>
Parameters</title>
                    <para>
                    <table frame="all">
                        <tgroup cols="2" align="left" colsep="1" rowsep="1">
                        <colspec colwidth="1*"/>
                        <colspec colwidth="4*"/>
                        <tbody>
                            <row>
<entry>*initial_message_from_main</entry><entry>
<para></para>
</entry>
                            </row>
                        </tbody>
                        </tgroup>
                    </table>
                    </para>
                </formalpara>
                </para>
</section>
<anchor xml:id="_fsm_2dispatch_8c_1a8c67f42f95d48ee2469c9a27d65db3e6"/><section>
    <title>fsm_journal_event()</title>
<indexterm><primary>fsm_journal_event</primary><secondary>dispatch.c</secondary></indexterm>
<indexterm><primary>dispatch.c</primary><secondary>fsm_journal_event</secondary></indexterm>
<para><computeroutput>void fsm_journal_event (int severity, int source, const char * file_source, const char * function_source, const char * string_value)</computeroutput></para><para>

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

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

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

<para>This filter can operate on any the following five parameters: severity, source, *file_source, *function_source, *string_value. <formalpara><title>See also</title>

<para>below (params)</para>
</formalpara>
Simple filters (on a single parameter) can be combined using the logical operators &apos;and&apos; and &apos;or&apos; and parentheses.</para>

<para>Use: $ grep -r &quot;fsm_journal_event&quot; to confirm the callergraph calls.</para>

<para><formalpara><title>Date</title>

<para>2024-08 </para>
</formalpara>
<formalpara><title>Author</title>

<para>Jean</para>
</formalpara>
<formalpara><title>See also</title>

<para>src/journal.c/fsm_journal_push_front()</para>

<para>src/main/main() </para>

<para>src/widget/topbar/modal.c </para>

<para>src/widget/topbar/right.c </para>

<para>src/widget/topbar/dialog.c </para>

<para>src/widget/topbar/left.c </para>

<para>src/widget/topbar/dispatch.c * 3 </para>

<para>src/widget/one_rule/dispatch.c </para>

<para>src/widget/one_rule/algebra/conditions.c * 2 </para>

<para>src/widget/measure/dispatch.c </para>

<para>src/widget/dispatch.c * 3 </para>

<para>src/widget/all_rules/dispatch.c </para>

<para><link linkend="_preferences_2manager_8c">src/fsm/preferences/manager.c</link> * 8 </para>

<para>src/fsm/measures/manager.c * 2 </para>

<para>src/fsm/measures/tools_list.c * 4 </para>

<para><link linkend="_fsm_2dispatch_8c">src/fsm/dispatch.c</link> * 10 </para>

<para>src/fsm/results/manager.c </para>

<para>src/util/tree.c </para>

<para>src/signal.c * 38</para>
</formalpara>

                <formalpara>
                    <title>
Parameters</title>
                    <para>
                    <table frame="all">
                        <tgroup cols="2" align="left" colsep="1" rowsep="1">
                        <colspec colwidth="1*"/>
                        <colspec colwidth="4*"/>
                        <tbody>
                            <row>
<entry>severity</entry><entry>
<para>&lt;&gt; </para>
</entry>
                            </row>
                        </tbody>
                        </tgroup>
                    </table>
                    </para>
                </formalpara>
                <formalpara><title>See also</title>

<para>enum fsm_enum_journal_severity in include/fsm.h &apos;severity&apos; 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</para>
</formalpara>

                <formalpara>
                    <title>
Parameters</title>
                    <para>
                    <table frame="all">
                        <tgroup cols="2" align="left" colsep="1" rowsep="1">
                        <colspec colwidth="1*"/>
                        <colspec colwidth="4*"/>
                        <tbody>
                            <row>
<entry>source</entry><entry>
<para>&lt;&gt; </para>
</entry>
                            </row>
                        </tbody>
                        </tgroup>
                    </table>
                    </para>
                </formalpara>
                <formalpara><title>See also</title>

<para>enum fsm_enum_journal_source in include/fsm.h &apos;source&apos; is a pre-defined value that can be associated to each event. It is not mandatory. It can be set to &apos;NULL&apos;.</para>
</formalpara>

                <formalpara>
                    <title>
Parameters</title>
                    <para>
                    <table frame="all">
                        <tgroup cols="2" align="left" colsep="1" rowsep="1">
                        <colspec colwidth="1*"/>
                        <colspec colwidth="4*"/>
                        <tbody>
                            <row>
<entry>*file_source</entry><entry>
<para>&lt;&gt; the name of the file that emits the event. </para>
</entry>
                            </row>
                            <row>
<entry>*function_source</entry><entry>
<para>&lt;&gt; the function that emits the event. </para>
</entry>
                            </row>
                            <row>
<entry>*string_value</entry><entry>
<para>&lt;&gt; any value that can qualify the event and provides useful information when reading the log. </para>
</entry>
                            </row>
                        </tbody>
                        </tgroup>
                    </table>
                    </para>
                </formalpara>
                </para>
</section>
<anchor xml:id="_fsm_2dispatch_8c_1a435d1a5171a7d69662d701234722fee2"/><section>
    <title>fsm_journal_publication_request()</title>
<indexterm><primary>fsm_journal_publication_request</primary><secondary>dispatch.c</secondary></indexterm>
<indexterm><primary>dispatch.c</primary><secondary>fsm_journal_publication_request</secondary></indexterm>
<para><computeroutput>void fsm_journal_publication_request ( )</computeroutput></para><para>

<para>The <link linkend="_fsm_2dispatch_8c_1a435d1a5171a7d69662d701234722fee2">fsm_journal_publication_request()</link> is called only once, by <link linkend="_main_8c_1a3c04138a5bfe5d72780bb7e82a18e627">main()</link>, just after closing the app and before ending the program. </para>
</para>

<para>This is to guarantee the chronological order of the events in the journal.</para>

<para>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 &quot;main()&quot;, Its chronological order is therefore guaranteed.</para>

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

<para>The <link linkend="_structfsm__struct__journal">fsm_struct_journal</link> (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.</para>

<para><formalpara><title>Date</title>

<para>2024-08 </para>
</formalpara>
<formalpara><title>Author</title>

<para>Jean</para>
</formalpara>
<formalpara><title>See also</title>

<para>src/main/main()</para>

<para>src/journal/fsm_journal_publish() </para>
</formalpara>
</para>
</section>
<anchor xml:id="_fsm_2dispatch_8c_1ae921ecd39af67bb8dc0deb2cdc86125d"/><section>
    <title>fsm_set_exec_edit()</title>
<indexterm><primary>fsm_set_exec_edit</primary><secondary>dispatch.c</secondary></indexterm>
<indexterm><primary>dispatch.c</primary><secondary>fsm_set_exec_edit</secondary></indexterm>
<para><computeroutput>void fsm_set_exec_edit (int choice)</computeroutput></para><para>

<para>setter for the static value: &apos;choice_STATE_RULES_DATA&apos; (in this file) </para>
</para>

<para>see include/fsm enum fsm_enum_exec_edit { EXEC, EDIT }</para>

<para><formalpara><title>Date</title>

<para>2024-08 </para>
</formalpara>
<formalpara><title>Author</title>

<para>Jean</para>
</formalpara>
<formalpara><title>See also</title>

<para>(none)</para>

<para>src/signal * 2</para>
</formalpara>

                <formalpara>
                    <title>
Parameters</title>
                    <para>
                    <table frame="all">
                        <tgroup cols="2" align="left" colsep="1" rowsep="1">
                        <colspec colwidth="1*"/>
                        <colspec colwidth="4*"/>
                        <tbody>
                            <row>
<entry>choice</entry><entry>
<para>&lt; a boolean value which can be &quot;EXEC&quot; or &quot;EDIT&quot; </para>
</entry>
                            </row>
                        </tbody>
                        </tgroup>
                    </table>
                    </para>
                </formalpara>
                </para>
</section>
<anchor xml:id="_fsm_2dispatch_8c_1a770bcaeb0bd6f81cddcc3cd506468fff"/><section>
    <title>fsm_set_preferences_modified()</title>
<indexterm><primary>fsm_set_preferences_modified</primary><secondary>dispatch.c</secondary></indexterm>
<indexterm><primary>dispatch.c</primary><secondary>fsm_set_preferences_modified</secondary></indexterm>
<para><computeroutput>void fsm_set_preferences_modified (bool value)</computeroutput></para><para>

<para>setter for the static boolean: &apos;preferences_have_been_modified&apos; </para>
</para>

<para><formalpara><title>Date</title>

<para>2024-08 </para>
</formalpara>
<formalpara><title>Author</title>

<para>Jean</para>
</formalpara>
<formalpara><title>See also</title>

<para>TODO To be used by any function that modifies the current user <link linkend="_structpreferences">preferences</link></para>

<para><link linkend="_fsm_2dispatch_8c_1a8c67f42f95d48ee2469c9a27d65db3e6">fsm_journal_event()</link></para>
</formalpara>

                <formalpara>
                    <title>
Parameters</title>
                    <para>
                    <table frame="all">
                        <tgroup cols="2" align="left" colsep="1" rowsep="1">
                        <colspec colwidth="1*"/>
                        <colspec colwidth="4*"/>
                        <tbody>
                            <row>
<entry>value</entry><entry>
<para>= TRUE if preferences_have_been_modified. </para>
</entry>
                            </row>
                        </tbody>
                        </tgroup>
                    </table>
                    </para>
                </formalpara>
                </para>
</section>
<anchor xml:id="_fsm_2dispatch_8c_1af5a464b19589ba1972c9b3aa3397945a"/><section>
    <title>fsm_set_state_rules_data()</title>
<indexterm><primary>fsm_set_state_rules_data</primary><secondary>dispatch.c</secondary></indexterm>
<indexterm><primary>dispatch.c</primary><secondary>fsm_set_state_rules_data</secondary></indexterm>
<para><computeroutput>void fsm_set_state_rules_data (int choice)</computeroutput></para><para>

<para>setter for the static value: &apos;choice_STATE_RULES_DATA&apos; (in this file) </para>
</para>

<para>see include/fsm enum fsm_enum_state_rules_data { SYNTH, STATE, RULES, DATA } Today (2024-10) the initial page is set to &apos;SYNTH&apos;. <formalpara><title>See also</title>

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

<para>end of the function: <link linkend="_fsm_2dispatch_8c">fsm/dispatch.c</link> window_design_topbar_left()</para>
</formalpara>
<formalpara><title>Date</title>

<para>2024-08 </para>
</formalpara>
<formalpara><title>Author</title>

<para>Jean</para>
</formalpara>
<formalpara><title>See also</title>

<para>src/signal * 4</para>

<para>(none)</para>
</formalpara>

                <formalpara>
                    <title>
Parameters</title>
                    <para>
                    <table frame="all">
                        <tgroup cols="2" align="left" colsep="1" rowsep="1">
                        <colspec colwidth="1*"/>
                        <colspec colwidth="4*"/>
                        <tbody>
                            <row>
<entry>choice</entry><entry>
<para></para>
</entry>
                            </row>
                        </tbody>
                        </tgroup>
                    </table>
                    </para>
                </formalpara>
                </para>
</section>
</section>
</section>