# Client green modes

You can also change the active global green mode at any time in your program:

    >>> from tango import DeviceProxy, GreenMode
    >>> from tango import set_green_mode, get_green_mode

    >>> get_green_mode()
    tango.GreenMode.Synchronous

    >>> dev = DeviceProxy("sys/tg_test/1")
    >>> dev.get_green_mode()
    tango.GreenMode.Synchronous

    >>> set_green_mode(GreenMode.Futures)
    >>> get_green_mode()
    tango.GreenMode.Futures

    >>> dev.get_green_mode()
    tango.GreenMode.Futures

As you can see by the example, the global green mode will affect any previously created `DeviceProxy` using the default DeviceProxy constructor parameters.

You can specificy green mode on a `DeviceProxy` at creation time. You can also change the green mode at any time:

    >>> from tango.futures import DeviceProxy

    >>> dev = DeviceProxy("sys/tg_test/1")
    >>> dev.get_green_mode()
    tango.GreenMode.Futures

    >>> dev.set_green_mode(GreenMode.Synchronous)
    >>> dev.get_green_mode()
    tango.GreenMode.Synchronous

## futures mode

Using `concurrent.futures` cooperative mode in PyTango is relatively easy:

    >>> from tango.futures import DeviceProxy

    >>> dev = DeviceProxy("sys/tg_test/1")
    >>> dev.get_green_mode()
    tango.GreenMode.Futures

    >>> print(dev.state())
    RUNNING

The `tango.futures.DeviceProxy()` API is exactly the same as the standard `DeviceProxy`. The difference is in the semantics of the methods that involve synchronous network calls (constructor included) which may block the execution for a relatively big amount of time. The list of methods that have been modified to accept futures semantics are, on the `tango.futures.DeviceProxy()`:

- Constructor

- `state()`

- `status()`

- `read_attribute()`

- `write_attribute()`

- `write_read_attribute()`

- `read_attributes()`

- `write_attributes()`

- `ping()`

So how does this work in fact? I see no difference from using the standard `DeviceProxy`. Well, this is, in fact, one of the goals: be able to use a futures cooperation without changing the API. Behind the scenes the methods mentioned before have been modified to be able to work cooperatively.

All of the above methods have been boosted with two extra keyword arguments wait and timeout which allow to fine tune the behaviour. The wait parameter is by default set to `True` meaning wait for the request to finish (the default semantics when not using green mode). If wait is set to `True`, the timeout determines the maximum time to wait for the method to execute. The default is `None` which means wait forever. If wait is set to `False`, the timeout is ignored.

If wait is set to `True`, the result is the same as executing the standard method on a `DeviceProxy`. If, wait is set to `False`, the result will be a `concurrent.futures.Future`. In this case, to get the actual value you will need to do something like:

    >>> from tango.futures import DeviceProxy

    >>> dev = DeviceProxy("sys/tg_test/1")
    >>> result = dev.state(wait=False)
    >>> result
    <Future at 0x16cb310 state=pending>

    >>> # this will be the blocking code
    >>> state = result.result()
    >>> print(state)
    RUNNING

Here is another example using `read_attribute()`:

    >>> from tango.futures import DeviceProxy

    >>> dev = DeviceProxy("sys/tg_test/1")
    >>> result = dev.read_attribute('wave', wait=False)
    >>> result
    <Future at 0x16cbe50 state=pending>

    >>> dev_attr = result.result()
    >>> print(dev_attr)
    DeviceAttribute[
    data_format = tango.AttrDataFormat.SPECTRUM
          dim_x = 256
          dim_y = 0
     has_failed = False
       is_empty = False
           name = 'wave'
        nb_read = 256
     nb_written = 0
        quality = tango.AttrQuality.ATTR_VALID
    r_dimension = AttributeDimension(dim_x = 256, dim_y = 0)
           time = TimeVal(tv_nsec = 0, tv_sec = 1383923329, tv_usec = 451821)
           type = tango.CmdArgType.DevDouble
          value = array([ -9.61260664e-01,  -9.65924853e-01,  -9.70294813e-01,
            -9.74369212e-01,  -9.78146810e-01,  -9.81626455e-01,
            -9.84807087e-01,  -9.87687739e-01,  -9.90267531e-01,
            ...
            5.15044507e-1])
        w_dim_x = 0
        w_dim_y = 0
    w_dimension = AttributeDimension(dim_x = 0, dim_y = 0)
        w_value = None]

## gevent mode

Warning

Before using gevent mode please note that at the time of writing this documentation, tango.gevent requires the latest version 1.0 of gevent (which has been released the day before :-P).

Using gevent cooperative mode in PyTango is relatively easy:

    >>> from tango.gevent import DeviceProxy

    >>> dev = DeviceProxy("sys/tg_test/1")
    >>> dev.get_green_mode()
    tango.GreenMode.Gevent

    >>> print(dev.state())
    RUNNING

The `tango.gevent.DeviceProxy()` API is exactly the same as the standard `DeviceProxy`. The difference is in the semantics of the methods that involve synchronous network calls (constructor included) which may block the execution for a relatively big amount of time. The list of methods that have been modified to accept gevent semantics are, on the `tango.gevent.DeviceProxy()`:

- Constructor

- `state()`

- `status()`

- `read_attribute()`

- `write_attribute()`

- `write_read_attribute()`

- `read_attributes()`

- `write_attributes()`

- `ping()`

So how does this work in fact? I see no difference from using the standard `DeviceProxy`. Well, this is, in fact, one of the goals: be able to use a gevent cooperation without changing the API. Behind the scenes the methods mentioned before have been modified to be able to work cooperatively with other greenlets.

All of the above methods have been boosted with two extra keyword arguments wait and timeout which allow to fine tune the behaviour. The wait parameter is by default set to `True` meaning wait for the request to finish (the default semantics when not using green mode). If wait is set to `True`, the timeout determines the maximum time to wait for the method to execute. The default timeout is `None` which means wait forever. If wait is set to `False`, the timeout is ignored.

If wait is set to `True`, the result is the same as executing the standard method on a `DeviceProxy`. If, wait is set to `False`, the result will be a `gevent.event.AsyncResult`. In this case, to get the actual value you will need to do something like:

    >>> from tango.gevent import DeviceProxy

    >>> dev = DeviceProxy("sys/tg_test/1")
    >>> result = dev.state(wait=False)
    >>> result
    <gevent.event.AsyncResult at 0x1a74050>

    >>> # this will be the blocking code
    >>> state = result.get()
    >>> print(state)
    RUNNING

Here is another example using `read_attribute()`:

    >>> from tango.gevent import DeviceProxy

    >>> dev = DeviceProxy("sys/tg_test/1")
    >>> result = dev.read_attribute('wave', wait=False)
    >>> result
    <gevent.event.AsyncResult at 0x1aff54e>

    >>> dev_attr = result.get()
    >>> print(dev_attr)
    DeviceAttribute[
    data_format = tango.AttrDataFormat.SPECTRUM
          dim_x = 256
          dim_y = 0
     has_failed = False
       is_empty = False
           name = 'wave'
        nb_read = 256
     nb_written = 0
        quality = tango.AttrQuality.ATTR_VALID
    r_dimension = AttributeDimension(dim_x = 256, dim_y = 0)
           time = TimeVal(tv_nsec = 0, tv_sec = 1383923292, tv_usec = 886720)
           type = tango.CmdArgType.DevDouble
          value = array([ -9.61260664e-01,  -9.65924853e-01,  -9.70294813e-01,
            -9.74369212e-01,  -9.78146810e-01,  -9.81626455e-01,
            -9.84807087e-01,  -9.87687739e-01,  -9.90267531e-01,
            ...
            5.15044507e-1])
        w_dim_x = 0
        w_dim_y = 0
    w_dimension = AttributeDimension(dim_x = 0, dim_y = 0)
        w_value = None]

Note

due to the internal workings of gevent, setting the wait flag to `True` (default) doesn’t prevent other greenlets from running in parallel. This is, in fact, one of the major bonus of working with `gevent` when compared with `concurrent.futures`

## asyncio mode

Asyncio mode is similar to gevent, but it uses explicit coroutines. You can compare gevent and asyncio examples.

     1# SPDX-FileCopyrightText: All Contributors to the PyTango project
     2# SPDX-License-Identifier: LGPL-3.0-or-later
     3import asyncio
     4from tango.asyncio import DeviceProxy
     5
     6
     7async def asyncio_example():
     8    dev = await DeviceProxy("sys/tg_test/1")
     9    print(dev.get_green_mode())
    10
    11    print(await dev.state())
    12
    13    # in case of high-level API read has to be awaited
    14    print(await dev.long_scalar)
    15    print(await dev["long_scalar"])
    16    print(await getattr(dev, "long_scalar"))
    17
    18    # while write executed sync
    19    dev.long_scalar = 1
    20
    21    # for low-level API both read_attribute and write_attribute have to be awaited
    22    print(await dev.read_attribute("long_scalar"))
    23    await dev.write_attribute("long_scalar", 1)
    24
    25
    26if __name__ == "__main__":
    27    asyncio.run(asyncio_example())

Below you can find a TCP server example, which runs in an asynchronous mode and waits for a device’s attribute name from a TCP client, then asks the device for a value and replies to the TCP client.

     1# SPDX-FileCopyrightText: All Contributors to the PyTango project
     2# SPDX-License-Identifier: LGPL-3.0-or-later
     3"""A simple TCP server for Tango attributes.
     4
     5It runs on all interfaces on port 8888:
     6
     7   $ python tango_tcp_server.py
     8   Serving on 0.0.0.0 port 8888
     9
    10It can be accessed using netcat:
    11
    12   $ ncat localhost 8888
    13   >>> sys/tg_test/1/ampli
    14   0.0
    15   >>> sys/tg_test/1/state
    16   RUNNING
    17   >>> sys/tg_test/1/nope
    18   DevFailed[
    19   DevError[
    20        desc = Attribute nope is not supported by device sys/tg_test/1
    21      origin = AttributeProxy::real_constructor()
    22      reason = API_UnsupportedAttribute
    23    severity = ERR]
    24    ]
    25   >>> ...
    26"""
    27
    28import asyncio
    29from tango.asyncio import AttributeProxy
    30
    31
    32async def handle_echo(reader, writer):
    33    # Write the cursor
    34    writer.write(b">>> ")
    35    # Loop over client request
    36    async for line in reader:
    37        request = line.decode().strip()
    38        # Get attribute value using asyncio green mode
    39        try:
    40            proxy = await AttributeProxy(request)
    41            attr_value = await proxy.read()
    42            reply = str(attr_value.value)
    43        # Catch exception if something goes wrong
    44        except Exception as exc:
    45            reply = str(exc)
    46        # Reply to client
    47        writer.write(reply.encode() + b"\n" + b">>> ")
    48    # Close communication
    49    writer.close()
    50
    51
    52async def start_serving():
    53    server = await asyncio.start_server(handle_echo, "0.0.0.0", 8888)
    54    print("Serving on {} port {}".format(*server.sockets[0].getsockname()))
    55    return server
    56
    57
    58async def stop_serving(server):
    59    server.close()
    60    await server.wait_closed()
    61
    62
    63def main():
    64    # Start the server
    65    loop = asyncio.get_event_loop()
    66    server = loop.run_until_complete(start_serving())
    67    # Serve requests until Ctrl+C is pressed
    68    try:
    69        loop.run_forever()
    70    except KeyboardInterrupt:
    71        pass
    72    # Close the server
    73    loop.run_until_complete(stop_serving(server))
    74    loop.close()
    75
    76
    77if __name__ == "__main__":
    78    main()