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>fsm (Finite State Machine) tasks dispatcher </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>fsm init is the first function called by <link linkend="_main_8c">main.c</link> It initiates the journal and the four lists: &apos;measures&apos;, &apos;results&apos;, &apos;displayables results&apos; and &apos;preferences&apos;. </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>some client pages (in particular &quot;state&quot; and &quot;rules&quot;) will be displayed and behave differently depending on whether the fsm is in edit or run state. </para>
</listitem>
            <listitem><para>int <link linkend="_fsm_2dispatch_8c_1a90ab14081a88752d3721947a4922ee25">fsm_get_state_rules_data</link> ()</para>

<para>The value of the static int choice_STATE_RULES_DATA can be one of the enum include/fsm enum fsm_enum_state_rules_data. </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>fsm (Finite State Machine) tasks dispatcher </para>

<para>This file is part of Gem-graph.</para>

<para>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:<itemizedlist>
<listitem>
<para>Run the model or edit it.</para>
</listitem><listitem>
<para>Select a single view of the model from all those possible. The different views show either the space, or the rule tree, or a single rule of interest, or measurements or results. NB an overview is possible, but it does not provide details.</para>
</listitem><listitem>
<para>Apply a selected measurement to the currently running model</para>
</listitem><listitem>
<para>Select some results for study or/and presentation.</para>
</listitem><listitem>
<para>Choose the user&apos;s preferred values for a set of parameters used to modify the appearance or behaviour of gem-graph.</para>
</listitem></itemizedlist>
</para>

<para>Each state of the fsm is a combination of each of these states.</para>

<para>The current state of the fsm must be<itemizedlist>
<listitem>
<para>saved at the end of a work session and</para>
</listitem><listitem>
<para>reread (available to the user) at the start of a new session.</para>
</listitem></itemizedlist>
</para>

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

<para>No fsm transition should 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>some client pages (in particular &quot;state&quot; and &quot;rules&quot;) will be displayed and behave differently depending on whether the fsm is in edit or run state. </para>
</para>

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

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

<para><formalpara><title>Since</title>

<para>2024-06</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>choice_EXEC_EDIT and </para>

<para>include/fsm/enum fsm_enum_exec_edit {}</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>Since</title>

<para>2024-08</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>
</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>The value of the static int choice_STATE_RULES_DATA can be one of the enum include/fsm enum fsm_enum_state_rules_data. </para>
</para>

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

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

<para><formalpara><title>Since</title>

<para>2024-06</para>
</formalpara>
<formalpara><title>See also</title>

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

<para>src/signal</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>fsm init is the first function called by <link linkend="_main_8c">main.c</link> It initiates the journal and the four lists: &apos;measures&apos;, &apos;results&apos;, &apos;displayables results&apos; and &apos;preferences&apos;. </para>
</para>

<para>The items selected in these lists define the current state of the fsm.</para>

<para><formalpara><title>Since</title>

<para>2024-08</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>Since</title>

<para>2024-08</para>
</formalpara>
<formalpara><title>See also</title>

<para><link linkend="_journal_8c">src/journal.c</link>/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><link linkend="_widget_2topbar_2dispatch_8c">src/widget/topbar/dispatch.c</link> * 3 </para>

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

<para><link linkend="_conditions_8c">src/widget/one_rule/algebra/conditions.c</link> * 2 </para>

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

<para><link linkend="_widget_2dispatch_8c">src/widget/dispatch.c</link> * 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><link linkend="_measures_2manager_8c">src/fsm/measures/manager.c</link> * 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><link linkend="_results_2manager_8c">src/fsm/results/manager.c</link> </para>

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

<para><link linkend="_signal_8c">src/signal.c</link> * 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 <link linkend="_fsm_8h_1ab761a6fdf1ac1e26a44f8f9524aa6da7">fsm_enum_journal_severity</link> in <link linkend="_fsm_8h">include/fsm.h</link> &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 <link linkend="_fsm_8h">include/fsm.h</link> &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><link linkend="_journal_8c">src/journal.c</link>/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>Since</title>

<para>2024-08</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>Since</title>

<para>2024-08</para>
</formalpara>
<formalpara><title>See also</title>

<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>Since</title>

<para>2024-08</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>Since</title>

<para>2024-08</para>
</formalpara>
<formalpara><title>See also</title>

<para>src/signal * 4</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>