=========
Threading
=========

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

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

.. only:: html

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

.. index:: threads

.. _threads:

Unicon threading
================

Unicon supports concurrent processing, tasks, and threads.

Threading is documented in Unicon Technical Report 14, by :ref:`jafar` and
:ref:`clint`.

http://unicon.org/utr/utr14.pdf

Unicon threads build on :ref:`co-expression`. Normally co-expressions are
synchronous, thread co-expressions are asynchronous.

Thread creation
---------------
Unicon threads can be created with the reserved word :ref:`thread` or the
function :ref:`spawn`.  The ``spawn()`` function turns a previously created
synchronous co-expression into an asynchronous threaded co-expression.  The
``thread`` reserved word creates a thread and starts it running.

``thread expr`` is equivalent to:

.. sourcecode:: unicon

    T := spawn(create expr))
    @T

Both ``thread`` and ``spawn()`` return a reference to the new thread.

Hello, threads
--------------

This example creates running threads, but there is no synchronization with
main.  The main procedure may end, terminating the run, before the threads
have a chance to complete, (or it may not, due to the nature of asynchronous
threading).

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

.. only:: html

    .. rst-class:: rightalign

        :download:`examples/threading.icn`

Initial test:

.. program-output:: unicon -s threading.icn -x
   :cwd: examples

That sample run may or may not allow all ten threads to finish before the
main program completes and returns to the operating system.

This next example uses :ref:`wait` to ensure that all the threads complete
before main terminates.

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

.. only:: html

    .. rst-class:: rightalign

        :download:`examples/threading-wait.icn`

Waited run:

.. program-output:: unicon -s threading-wait.icn -x
   :cwd: examples

Using :ref:`wait` is the recommended way of dealing with thread execution to
ensure the threads are given a chance to complete. Keeping a list structure
of thread references is a handy and reliable way of managing this idiom.

.. attention::

    Threaded programming is hard. It adds an extra dimension to processing
    that requires special care and attention to detail.  Most operations in a
    computer program are multiple step, non atomic operations.  Even something
    as simple as incrementing a variable is split at the machine level as
    fetch, increment, store.  Threads may enter the operation at any point in
    time, and two competing threads may conflict between the fetching and
    incrementing steps, causing erroneous results.  Guards must be put in
    place to ensure that every section of code is allowed to complete each
    step before another thread starts in on the operation. Unicon has kept
    this in mind and :ref:`critical` section management is part and parcel of
    safe, reliable thread programming.

--------


.. index:: tasks, multi-tasking

.. _tasks:

Multi-tasking
=============
:ref:`clint` has enhanced the virtual machine to allow multi-tasking.
Multiple programs can be loaded into the VM and invoked as
:ref:`co-expression`\ s. See `load`.

The poor person's expensive ``uval`` *compile at runtime* function uses `load`
to load a different task to perform the equivalent of an ``eval`` function.
Not perfect, but satisfactory for many applications that need to evaluate
arbitrary Unicon programs or program fragments.  The `unitest` testing
framework uses ``uval`` to compile and test arbitrary code fragments from text
source.

The multi-tasking features started life as a method to allow execution
monitoring and control.  Comes in handy for many things, and will likely play
a large part of any future *evaluate at runtime* form of an ``eval`` function. 


.. only:: html
   
   ..

   --------

   :ref:`genindex` | Next: :doc:`features` | Previous: :doc:`networking`

   |