Tango event subscription modes
==============================

Taurus supports the event subscription modes introduced in Tango 10.1.0.
Two aspects are relevant to Taurus clients:

1. Selecting the **event subscription mode** (``EventSubMode``).
2. A lightweight **first read** to initialize attribute values when needed.

For background on Tango events and PyTango API see the official docs:
`Tango Events`_ and `PyTango DeviceProxy API`_. PyTango exposes the
``EventSubMode`` enum and adds ``EventReason`` in the ``EventData``
structure (see documentation in `PyTango client API`_).

.. _Taurus Performance Optimization: https://gitlab.com/taurus-org/taurus/-/blob/develop/doc/source/tep/TEP21.md
.. _Tango Events: https://tango-controls.readthedocs.io/en/latest/Explanation/event.html
.. _PyTango DeviceProxy API: https://tango-controls.readthedocs.io/projects/pytango/en/latest/api/client_api/device_proxy.html
.. _PyTango client API: https://tango-controls.readthedocs.io/projects/pytango/en/latest/api/client_api/miscellaneous.html

EventSubMode in Taurus
----------------------

Taurus supports all event subscription modes that Tango >= 10.1.0 provides.
The Taurus functionality is independent of the selected mode, but application
startup performance may vary depending on the attributes and devices involved.

When available, Taurus uses ``AsyncRead`` as the default ``EventSubMode``. In
most cases it should not be changed, since ``AsyncRead`` provides a good compromise
between compatibility, simplicity, and performance. The mode can be changed when
needed; see :doc:`../howto/event_subscription_mode`.

If you experience problems when starting applications, especially with value
initialization, the mode can be changed to ``SyncRead`` to recover the previous
Taurus (< 5.4) default behaviour.

The following table (adapted from `PyTango EventSubMode`_) summarizes the available event
subscription modes:

+-------------+-------------------------------------+--------------------------------+----------------------------+---------------------------+-----------------------------------------+
| EventSubMode| Tries subscription before returning | Raises on subscription failure | Retries automatically      | Reads entity              | First callback                          |
+=============+=====================================+================================+============================+===========================+=========================================+
| SyncRead    | Yes                                 | Yes                            | No                         | Yes, during subscription  | Immediately, with data                  |
+-------------+-------------------------------------+--------------------------------+----------------------------+---------------------------+-----------------------------------------+
| AsyncRead   | No                                  | No                             | Yes                        | Yes, after subscription   | After read, with data                   |
+-------------+-------------------------------------+--------------------------------+----------------------------+---------------------------+-----------------------------------------+
| Sync        | Yes                                 | Yes                            | No                         | No                        | Not on subscription. Only on next event |
+-------------+-------------------------------------+--------------------------------+----------------------------+---------------------------+-----------------------------------------+
| Async       | No                                  | No                             | Yes                        | No                        | After subscription, no data             |
+-------------+-------------------------------------+--------------------------------+----------------------------+---------------------------+-----------------------------------------+
| Stateless   | Yes                                 | No                             | Yes                        | Yes, during subscription  | Immediately, with data                  |
+-------------+-------------------------------------+--------------------------------+----------------------------+---------------------------+-----------------------------------------+

.. _PyTango EventSubMode: https://tango-controls.readthedocs.io/projects/pytango/en/latest/api/client_api/miscellaneous.html#tango.EventSubMode

First Read (client-side initialization)
---------------------------------------

Taurus now provides a one-shot read used when the chosen mode does not
perform an initial read by itself (``Sync`` and ``Async``). This first read
is performed asynchronously in a dedicated thread that finishes when
all attributes have been initialized.

This feature ensures that the attribute has a value cached right after
subscription setup, delegating to Taurus the responsibility for providing
the initial attribute value.

API involved in Taurus:

- Factory helper to register a first-time read for a given attribute.
- Attribute-side helper that delegates to the factory during initialization.