.. EXOS API documentation master file, created by
   sphinx-quickstart on Thu May 15 08:22:31 2014.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

.. image:: ExtremeSwitchingLogo.png
.. image:: XosLogo.png

====================================
The EXOS Python API
====================================

.. automodule:: exos.api

The following sections discuss the API.

.. toctree::
   :maxdepth: 2

   system.rst
   logging.rst
   aaa.rst
   cli.rst
   expkt.rst
   cm.rst
   ismb.rst
   throw.rst
..   vlan.rst


References.

.. toctree::
   :maxdepth: 1

   cmfrontend.rst
   cmbackend.rst


Runtime Environment
====================================

Python applications can be run on EXOS by: 

1. Using the create process command, which is documented 
   in the EXOS User Guide.
2. Installing an XMOD.  For more information about creating an XMOD, contact
   Extreme.

Python applications are run in a "Python container" known as EXPY.  It
implements the EXOS Python API and provides the Python runtime environment.


Threading Models
====================================

The EXOS C API is generally asynchronous.  Requests are sent and responses are
returned via a callback.  Calls are non-blocking, allowing a thread to do other
work instead of waiting for the response.  This enables an efficient
single-threaded processing model.  However, asynchronous calls are arguably more
complicated to develop and use.

Many developers, particularly developers of high-level languages such as
Python, are more comfortable with a synchronous API where calls block until the
response is received.  Such an API will typically require an application to be
multi-threaded.

In most cases, the EXOS Python API will provide both an asynchronous and a
synchronous version of each call.  We strongly discourage mixing asynchronous and synchronous calls,
which will usually result in a deadlock.  EXPY will attempt to
detect a deadlock before it happens and raise ``DeadlockDetectedError`` instead.

The Python application is launched in a Runner thread, leaving the main thread to interact 
with EXOS.  The application can exit the runtime environment using ``sys.exit()`` 
or ``thread.exit()`` from the Runner thread.  These will raise a ``SystemExit`` exception, 
allowing clean-up handlers, such as finally blocks, to run.  The application can also exit 
from any thread using ``os._exit()``, but clean-up handlers will not be run. 

If the Runner thread exits, the main thread will continue running and the application will be able to process events and callbacks from EXOS.




Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`