.. _system:
.. module:: exos.api

System
================================================

Process Name
------------------------------------------------
Every EXOS process has a name that uniquely identifies it.

.. autofunction:: get_process_name

.. autofunction:: set_process_name


Health Monitoring
------------------------------------------------

EXOS can monitor processings and restart them upon failure.  Additionally, it
can monitor threads within a process.  Threads must first be registered with
EXOS, then they must periodically send a heartbeat, indiciating they are still
functioning properly.


Thread Monitoring
++++++++++++++++++++++++++++++++++++++++++++++++

The following methods have been added to the :class:`threading.Thread` class to
support thread monitoring.

.. class:: threading.Thread

   .. automethod:: register
   .. automethod:: deregister
   .. automethod:: keepalive


Pool Monitoring
++++++++++++++++++++++++++++++++++++++++++++++++

The :class:`MonitoredThreadPool` class inherits from
:class:`futures.ThreadPoolExecutor` to implement a monitored pool.  It
automatically registers a pool monitoring thread with EXOS and periodically
sends heartbeats.  As long as the pool is still processing jobs, the monitoring
thread continues to send heartbeats. If the pool gets stuck, EXOS will note the
failure and can recover the process.

.. autoclass:: MonitoredThreadPool

  .. automethod:: __init__


Process State
------------------------------------------------

An EXOS processes have a state, indicating whether it is ``READY``, ``STOPPED``, etc.
When a process is started, it will transition from ``BOOTING`` to ``LOADCFG`` and finally
to ``READY``.  A process must call :func:`ready()` to enter the ``READY`` state.

.. autofunction:: ready

.. autofunction:: get_process_state

Process States:

.. data:: ProcessState.FAIL
.. data:: ProcessState.STOPPED
.. data:: ProcessState.STARTED
.. data:: ProcessState.BOOTING
.. data:: ProcessState.LOADCFG
.. data:: ProcessState.READY


Stacking
------------------------------------------------

EXOS switches can be "stacked" for redundancy and simplified management.  

Not all switches can be stacked.  Use the :func:`is_stackable` function to determine
if the current switch supports stacking.

  .. autofunction:: is_stackable


Slots
++++++++++++++++++++++++++++++++++++++++++++++++

The :data:`slot` collection provides information about the slot numbers used in
the stack.

.. autodata:: slot
   :annotation:

.. autoclass:: SlotProperties

   .. autoattribute:: self
   .. autoattribute:: first
   .. autoattribute:: last


Primary, Backup, and Standby
++++++++++++++++++++++++++++++++++++++++++++++++

Within each stack, one switch will be master, another may be a backup, and the
rest are standbys.  The following functions allow a process to determine its
switches current state.

.. autofunction:: is_primary
.. autofunction:: is_backup
.. autofunction:: is_standby

Processes can "checkpoint" state so that failover is seamless.  For example,
as a routing protocol learns about neighbors, it may checkpoint that list to the
backup so that the list does not need to re-learned after a failover.


Checkpointing
++++++++++++++++++++++++++++++++++++++++++++++++

Under Python, checkpointing is implemented as "call this, but over there."  For
example, if the primary learned about a new neighbor, it may call an
add_neighbor() locally and then use :func:`call_on_backup` to make the same call,
but on the backup switch::

  add_neighbor(new_ip)
  api.call_on_backup(add_neighbor, new_ip)

The following checkpointing functions are available.

.. autofunction:: is_checkpointing
.. autofunction:: call_on_primary
.. autofunction:: call_on_backup
.. autofunction:: call_on_standby
.. autofunction:: call_on_standbys


Miscellaneous
------------------------------------------------

.. autofunction:: get_system_mac
.. autofunction:: get_sysname
.. autofunction:: is_capability_supported

Exceptions
------------------------------------------------

.. autoexception:: ExosError

.. autoexception:: DeadlockDetectedError