..
   hsmCommunicator.rst

   This file automatically generated by FSMLang

================
hsmCommunicator
================

This machine manages communications using a "stop and wait" protocol. Only one 
message is allowed to be outstanding.

Before any message can be exchanged, however, 
a session must be established with the peer. Establishing a connection
requires 
several exchanges to authenticate. The session will remain active as long as 
messages continue to be
exchanged with a minimum frequency.

The user of this 
machine calls run_hsmCommunicator, passing the SEND_MESSAGE event. For the first 
message,
the machine will be IDLE, and thus needs to queue the message, start 
the establishSession machine, and transition
to the ESTABLISHING_SESSION state. 
Requests to send messages received in this state will simply be queued. While 
the top level machine is in the ESTABLISHING_SESSION state, the establishSession 
machine does the establishment work.

When the establishSession machine receives 
the STEP1_RESPONSE event, it reports to the top level machine that
the session 
is established by returning the parent's SESSION_ESTABLISHED event. This will 
move the top level
machine to its IN_SESSION state and cause it to send the message(s) 
which are enqueued.






.. toctree::
   :hidden:
   :maxdepth: 2

   establishSession
   sendMessage

.. list-table:: Machine Statistics
   :align: left

   * - Number of events:
     - 4
   * - Events not handled:
     - 0
   * - Events handled in one state:
     - 2
   * - At least one event handled the same in all states?
     - no
   * - Number of states:
     - 3
   * - Number of states with entry functions:
     - 0
   * - Number of states with exit functions:
     - 0
   * - States handling no events:
     - 0
   * - States handling exactly one event:
     - 1
   * - States with no way in:
     - 0
   * - States with no way out:
     - 0



.. list-table:: State Chart
   :align: left
   :header-rows: 1
   :stub-columns: 1
   :class: scrollable

   * -
     - :ref:`SEND_MESSAGE <hsmCommunicator.SEND_MESSAGE>`
     - :ref:`SESSION_ESTABLISHED <hsmCommunicator.SESSION_ESTABLISHED>`
     - :ref:`SESSION_TIMEOUT <hsmCommunicator.SESSION_TIMEOUT>`
     - :ref:`MESSAGE_RECEIVED <hsmCommunicator.MESSAGE_RECEIVED>`
   * - :ref:`IDLE <hsmCommunicator.IDLE>`
     - | :ref:`startSessionEstablishment <hsmCommunicator.startSessionEstablishment>`
       | transition: :ref:`ESTABLISHING_SESSION <hsmCommunicator.ESTABLISHING_SESSION>`
     - 
     - 
     - 
   * - :ref:`ESTABLISHING_SESSION <hsmCommunicator.ESTABLISHING_SESSION>`
     - :ref:`queueMessage <hsmCommunicator.queueMessage>`
     - | :ref:`completeSessionStart <hsmCommunicator.completeSessionStart>`
       | transition: :ref:`IN_SESSION <hsmCommunicator.IN_SESSION>`
     - 
     - :ref:`passMessageReceived <hsmCommunicator.passMessageReceived>`
   * - :ref:`IN_SESSION <hsmCommunicator.IN_SESSION>`
     - :ref:`requestMessageTransmission <hsmCommunicator.requestMessageTransmission>`
     - 
     - transition: :ref:`IDLE <hsmCommunicator.IDLE>`
     - :ref:`passMessageReceived <hsmCommunicator.passMessageReceived>`


Events
-------


.. _hsmCommunicator.SEND_MESSAGE:

SEND_MESSAGE
~~~~~~~~~~~~~

This event comes from our client code, asking us to send a message.




These sub-machines share this event:

* sendMessage


These states handle this event:

* :ref:`IDLE <hsmCommunicator.IDLE>`
* :ref:`ESTABLISHING_SESSION <hsmCommunicator.ESTABLISHING_SESSION>`
* :ref:`IN_SESSION <hsmCommunicator.IN_SESSION>`


This yields a state density of 100%.



These actions are taken in response to this event:

* :ref:`startSessionEstablishment <hsmCommunicator.startSessionEstablishment>`
* :ref:`queueMessage <hsmCommunicator.queueMessage>`
* :ref:`requestMessageTransmission <hsmCommunicator.requestMessageTransmission>`


.. _hsmCommunicator.SESSION_ESTABLISHED:

SESSION_ESTABLISHED
~~~~~~~~~~~~~~~~~~~~

This event comes from our <i>establishSession</i> submachine, indicating that 
it has successfully
completed its work. We then forward it to our <i>sendMessage</i> 
submachine to indicate that
it may now begin to send messages.




This event is handled identically in 1 states.



These states handle this event:

* :ref:`ESTABLISHING_SESSION <hsmCommunicator.ESTABLISHING_SESSION>`


This yields a state density of 33%.



These actions are taken in response to this event:

* :ref:`completeSessionStart <hsmCommunicator.completeSessionStart>`


.. _hsmCommunicator.SESSION_TIMEOUT:

SESSION_TIMEOUT
~~~~~~~~~~~~~~~~

This event comes from our external timer, indicating that we've not tickled 
it in a while, and
thus should close down our session.




This event is handled identically in 1 states.



These states handle this event:

* :ref:`IN_SESSION <hsmCommunicator.IN_SESSION>`


This yields a state density of 33%.



No actions are taken in response to this event.



.. _hsmCommunicator.MESSAGE_RECEIVED:

MESSAGE_RECEIVED
~~~~~~~~~~~~~~~~~

This event comes from our lower comm layers, indicating that a peer message 
has arrived.
While we're in the ESTABLISHING_SESSION state, we forward this 
event to the <i>establishSession</i>
submachine; while in the IN_SESSION state, 
we forward it to the <i>sendMessage</i> submachine.




This event is handled identically in 2 states.



These sub-machines share this event:

* establishSession
* sendMessage


These states handle this event:

* :ref:`ESTABLISHING_SESSION <hsmCommunicator.ESTABLISHING_SESSION>`
* :ref:`IN_SESSION <hsmCommunicator.IN_SESSION>`


This yields a state density of 66%.



These actions are taken in response to this event:

* :ref:`passMessageReceived <hsmCommunicator.passMessageReceived>`


States
-------


.. _hsmCommunicator.IDLE:

IDLE
~~~~~

The wakeup state. Also, this is the state to which the machine
returns when 
a session times out.




These events are handled in this state:

* :ref:`SEND_MESSAGE <hsmCommunicator.SEND_MESSAGE>`


This yields an event density of 25%.



These actions are taken in this state:

* :ref:`startSessionEstablishment <hsmCommunicator.startSessionEstablishment>`


These states transition into this state:

* :ref:`IN_SESSION <hsmCommunicator.IN_SESSION>`


This state transitions into these states:

* :ref:`ESTABLISHING_SESSION <hsmCommunicator.ESTABLISHING_SESSION>`


.. _hsmCommunicator.ESTABLISHING_SESSION:

ESTABLISHING_SESSION
~~~~~~~~~~~~~~~~~~~~~

The machine is establishing a session. The actual work is being done by the 
<i>establishSession</i>
submachine. While in this state, the <i>MESSAGE_RECEIVED</i> 
event is forwarded to that submachine.




These events are handled in this state:

* :ref:`SESSION_ESTABLISHED <hsmCommunicator.SESSION_ESTABLISHED>`
* :ref:`MESSAGE_RECEIVED <hsmCommunicator.MESSAGE_RECEIVED>`
* :ref:`SEND_MESSAGE <hsmCommunicator.SEND_MESSAGE>`


This yields an event density of 75%.



These actions are taken in this state:

* :ref:`completeSessionStart <hsmCommunicator.completeSessionStart>`
* :ref:`passMessageReceived <hsmCommunicator.passMessageReceived>`
* :ref:`queueMessage <hsmCommunicator.queueMessage>`


These states transition into this state:

* :ref:`IDLE <hsmCommunicator.IDLE>`


This state transitions into these states:

* :ref:`IN_SESSION <hsmCommunicator.IN_SESSION>`


.. _hsmCommunicator.IN_SESSION:

IN_SESSION
~~~~~~~~~~~

A session has been established, and messages are being exchanged with the peer. 
While in this
state, the <i>MESSAGE_RECEIVED</i> event is forwarded to the <i>sendMessage</i> 
submachine.




These events are handled in this state:

* :ref:`MESSAGE_RECEIVED <hsmCommunicator.MESSAGE_RECEIVED>`
* :ref:`SEND_MESSAGE <hsmCommunicator.SEND_MESSAGE>`
* :ref:`SESSION_TIMEOUT <hsmCommunicator.SESSION_TIMEOUT>`


This yields an event density of 75%.



These actions are taken in this state:

* :ref:`passMessageReceived <hsmCommunicator.passMessageReceived>`
* :ref:`requestMessageTransmission <hsmCommunicator.requestMessageTransmission>`


These states transition into this state:

* :ref:`ESTABLISHING_SESSION <hsmCommunicator.ESTABLISHING_SESSION>`


This state transitions into these states:

* :ref:`IDLE <hsmCommunicator.IDLE>`


Actions
--------


.. _hsmCommunicator.startSessionEstablishment:

startSessionEstablishment
~~~~~~~~~~~~~~~~~~~~~~~~~~

This action returns:

* :ref:`ESTABLISH_SESSION_REQUEST <hsmCommunicator.establishSession.ESTABLISH_SESSION_REQUEST>`



.. _hsmCommunicator.completeSessionStart:

completeSessionStart
~~~~~~~~~~~~~~~~~~~~~

This action returns:

* noEvent



.. _hsmCommunicator.passMessageReceived:

passMessageReceived
~~~~~~~~~~~~~~~~~~~~

.. _hsmCommunicator.queueMessage:

queueMessage
~~~~~~~~~~~~~

This action returns:

* noEvent



.. _hsmCommunicator.requestMessageTransmission:

requestMessageTransmission
~~~~~~~~~~~~~~~~~~~~~~~~~~~

This action returns:

* noEvent