.. _sardana-configuration-separate-servers:

Running Pool and MacroServer as separate servers
================================================

A Sardana system does not have to live in a single process. Apart from the
``Sardana`` device server, which hosts both a Pool and a MacroServer and is
the setup used in :ref:`sardana-tutorial-demo-beamline`, Sardana ships two
more device servers: ``Pool``, which takes care of the communication with
the hardware, and ``MacroServer``, which executes the macros and exposes the
doors. Running these two separately is a fully supported deployment - see
:ref:`sardana-devel-global-overview` for the possible configurations.

You typically split the system when you want to distribute the hardware over
several processes or hosts, or when you want to isolate slow hardware in its
own Pool so that it does not slow down the rest of the system. See
:ref:`sardana-explanation-performance` for a broader discussion.

This how-to uses ``demo2`` as the instance name, so that the system it builds
is distinct from the ``demo1`` system created by
:ref:`sardana-tutorial-demo-beamline`. Instance names must be unique per
server: reusing one that already exists yields the *next* free device and
alias (``Pool/demo2/2``, ``Pool_demo2_2``, ...) rather than reusing the
existing ones, which is rarely what you want. Note also that the server
lower-cases the instance name given on the command line, so ``Pool DEMO2``
and ``Pool demo2`` are the same instance.

Register the Pool first
-----------------------

Register the Pool before the MacroServer. When the ``MacroServer`` instance
is registered it offers you a list of Pools to connect to, and that list is
built by querying the Tango database for the devices of class ``Pool``. You
may answer with either the alias or the device name of a listed Pool -
anything else is rejected with ``Unknown pool element``.

This is a convenience, not a hard requirement: if no Pool is registered yet,
the MacroServer is simply created without any Pool connection (it reports
``MacroServer <instance> has not been connected to any Pool``) and you can
fill in its ``PoolNames`` property later. Registering the Pool first just
lets you pick it from the list. Only *registration* matters for this - the
Pool server does not need to be running, it merely shows up without the
``(running)`` marker if it is not.

Start the Pool in a terminal::

    Pool demo2

The first time the instance is run it is not yet in the Tango database, so
the server offers to register it. Answer ``y``::

    $ Pool demo2
    demo2 does not exist. Do you wish to create a new one (Y/n) ? y

This registers the ``Pool/demo2`` server with one Pool device,
``Pool/demo2/1``, aliased ``Pool_demo2_1``. Leave the server running in this
terminal.

Then register the MacroServer
-----------------------------

In a second terminal::

    MacroServer demo2

Again the instance has to be registered, but this time the server also asks
which Pool(s) it should connect to. It lists *every* Pool device registered
in the Tango database, whatever server it belongs to (the ``(running)``
suffix marks the ones currently exported), then prompts repeatedly until you
answer with an empty line. If you previously ran the tutorial, its Pool shows
up here too::

    $ MacroServer demo2
    demo2 does not exist. Do you wish to create a new one (Y/n) ? y

    Available Pools:
    Pool_demo1_1 (a.k.a. Pool/demo1/1) (running)
    Pool_demo2_1 (a.k.a. Pool/demo2/1) (running)

    Please select the Pool to connect to (return to finish): Pool_demo2_1
    Please select the Pool to connect to (return to finish):

    MacroServer demo2 has been connected to Pool/s ['Pool_demo2_1']

This registers the ``MacroServer/demo2`` server with two devices: a
MacroServer device ``MacroServer/demo2/1`` aliased ``MS_demo2_1``, whose
``PoolNames`` property holds the Pools you selected, and a Door device
``Door/demo2/1`` aliased ``Door_demo2_1``.

``Door_demo2_1`` is the device your clients connect to, for example
:ref:`Spock <sardana-spock>`.

Connecting to more than one Pool
--------------------------------

The selection prompt loops, so you may enter several Pools, one per line,
before pressing :kbd:`Return` on an empty line - ``PoolNames`` is a list
property. This is how a single MacroServer drives several Pools, for
instance one per hardware group or per host.

The Pools a MacroServer talks to are not frozen at creation time: the
``PoolNames`` property can be changed later on, see
:ref:`sardana-configuration-macroserver`.

.. seealso::

    For making a server listen for CORBA requests on a fixed port or IP
    address see :ref:`sardana-configuration-server`.