====================
Execution Monitoring
====================
 
.. Modified: 2018-10-23/05:38-0400 btiffin
.. Copyright 2016 Brian Tiffin
.. This file is part of the Unicon Programming document
.. GPL 3.0+ :ref:`license`

.. image:: images/unicon.png
   :align: center

.. only:: html

    :ref:`genindex`
    :floatright:`<a href="http://unicon.sourceforge.net/">Unicon</a>`

.. index:: Execution Monitoring, monitoring

.. _Execution monitoring:

Unicon monitoring
=================

Execution monitoring is a profiling aid for ``Unicon`` programs.

Relying on multi threading, a monitoring control program loads other programs
and receives (possibily filtering) events.

.. index:: TP, EM

TP
   Target Program

EM
   Execution Monitor

In the Unicon source distribution, in ``unicon/tests/special`` there is a
basic monitoring test. Monitoring is usually setup with a TP (target program)
and an EM (execution monitor).  That sample has ``1to10.icn`` a simple
generator as the target program, and ``monitor.icn`` the sample EM.

For the capture, ``1to10.icn`` is changed to ``1to4.icn``, to decrease the
listing size.

.. literalinclude:: examples/1to4.icn
   :language: unicon
   :start-after: ##+

.. literalinclude:: examples/monitor.icn
   :language: unicon
   :start-after: ##+

.. sourcecode:: make

    # Make the monitor sample
    .RECIPEPREFIX = >
    
    monitor: monitor.icn 1to4
    > unicon monitor
    > ./monitor
    
    1to4: 1to4.icn
    > unicon 1to4

.. command-output:: make monitor
   :cwd: examples

Hmm, codes.  What all the monitoring event numbers mean are held in the
:ref:`IPL`, in the mprocs, mprogs, mincl directories. ``mprocs/evnames.icn``
is a good clue, but they are indexed by enumeration names, which is in
``mincl/evdefs.icn`` (which is mostly octal character code).  Execution
monitoring with Unicon is very much a tool chain that requires computer
assistance to use effectively at the capture and dump level.  Higher level
programs that provide visualization is a much more human friendly interface to
execution monitoring.

But just for instance, when the first column is ``80:`` (octal 120), that
matches an ``E_Fret`` event code.  Makes sense as the second column for those
events are the 1, 2, 3, 4 values returned from the ``1to4`` program.

Let's change the EM to be a little more friendly as a sample.

.. literalinclude:: examples/monitor-names.icn
   :language: unicon
   :start-after: ##+

.. command-output:: make monitor-names
   :cwd: examples

Ahh, that's a little easier on the eyes and brain.  And a sweet little view of
what's going on.  I wonder how that maps to some ucode?

.. program-output:: make monitor-names.u
   :cwd: examples

.. program-output:: cat -v monitor-names.u
   :cwd: examples

And, no, not really any quick grok matching .u to the monitor; that listing
means relatively little, at this point in studying Unicon, in relation to the
execution events. .u with the VM, and this particular monitor, are at
different layers, and there is no one to one mapping.  That's ok, lesson
learned.  Reading .u is pretty nice though, the ``line`` and ``colm``
mnemonics make it pretty easy to mentally map source to VM and let the brain
know where things are in the code for each operation.

Visualization
-------------

And Event Monitoring starts to shine.  Take your eyes off the code and look at
some pictures. Let the running programming paint its own picture.

.. todo:: add some plots


.. only:: html
   
   ..

   --------

   :ref:`genindex` | Previous: :doc:`debugging` | Next: :doc:`performance`

   |