.. _bliss_object:

Configure Bliss Objects for Online Data Processing
==================================================

A *Bliss object* is an instance of a python class that is instantiated when starting the *Bliss terminal*
for a specific *Bliss session*.

All classes in *blissoda* that manage data processing with *Ewoks* derive from
:class:`blissoda.automation.BlissAutomationObject` which allows these classes to be used for Bliss objects.

*Bliss objects* are configured in *Beacon*. The Beacon configuration is expected to use the
`generic plugin <https://bliss.gitlab-pages.esrf.fr/bliss/master/config_plugins.html#plugin-generic>`_.
For example:

.. code-block:: yaml

    - name: my_processor
      plugin: generic
      class: MyProcessor
      package: blissoda.mycategory.my_processor
      default_parameters:
        param1: value1
        param2: value2
      shared: false
      singleton: true

- `default_parameters`: Initial values for parameters stored in Redis.
- `shared`: If True, parameters are shared between Bliss sessions. Default: ``false``.
- `singleton`: If True, parameters are a singleton for the Bliss session (``shared=False``)
               or globally (``shared=True``). Default: ``true``.

.. hint::

  Singleton means that all Bliss objects instantiated from the same class, regardless of their names,
  refer to the same underlying Redis hash. They therefore share the same persistent parameter set.

Then add it to the objects of any *Bliss session*
`configuration <https://bliss.gitlab-pages.esrf.fr/bliss/master/config_sessions.html#yaml-session-configuration-file>`_ 
in *Beacon*:

.. code-block:: yaml

    - class: Session
      name: eh1
      setup-file: ./eh1_setup.py
      config-objects:
        - my_processor

Depending on the implementation of ``MyProcessor``, the parameters in ``default_parameters`` are typically only used
when they do not exist in *Redis* yet for the Bliss session in which the object is used. So after the first time the
value from *Redis* is used and can be changed from the Bliss terminal as follows

.. code-block:: python

    DEMO_SESSION [3]: my_processor
            Out [3]:
                    Parameters: 
                    param1   'value1'
                    param2   'value2'
    DEMO_SESSION [4]: my_processor.param1 = "CHANGED"
    DEMO_SESSION [5]: my_processor
            Out [5]:
                    Parameters:
                    param1   'CHANGED'
                    param2   'value2'

To copy and remove the values of another instance, most often after changing the
Beacon configuration parameters `shared`, `singleton` or `name`

.. code-block:: python

  DEMO_SESSION [3]: my_processor.copy_and_remove_parameters(shared=True, name="old_my_processor")