[pytango] 291/483: update documentation with green chapter
Sandor Bodo-Merle
sbodomerle-guest at moszumanska.debian.org
Thu Sep 28 19:14:51 UTC 2017
This is an automated email from the git hooks/post-receive script.
sbodomerle-guest pushed a commit to annotated tag bliss_8.10
in repository pytango.
commit b761244a447fe00673281d1518b468db5ff4103a
Author: tiagocoutinho <tiagocoutinho at 4e9c00fd-8f2e-0410-aa12-93ce3db5e235>
Date: Fri Nov 8 15:39:05 2013 +0000
update documentation with green chapter
git-svn-id: http://svn.code.sf.net/p/tango-cs/code/bindings/PyTango/trunk@24151 4e9c00fd-8f2e-0410-aa12-93ce3db5e235
---
doc/_templates/index.html | 2 +
doc/client/miscellaneous.rst | 273 ++++++++++++++++++++++++++++++++++++
src/boost/python/attribute_proxy.py | 2 +-
3 files changed, 276 insertions(+), 1 deletion(-)
diff --git a/doc/_templates/index.html b/doc/_templates/index.html
index b2eec92..9e5d7db 100644
--- a/doc/_templates/index.html
+++ b/doc/_templates/index.html
@@ -42,6 +42,8 @@
<a href="http://www.tango-controls.org/static/PyTango/latest/doc/html">Latest stable</a>
+ <a href="http://www.tango-controls.org/static/PyTango/v803/doc/html">8.0.3</a>
+
<a href="http://www.tango-controls.org/static/PyTango/v723/doc/html">7.2.3</a>
</p>
diff --git a/doc/client/miscellaneous.rst b/doc/client/miscellaneous.rst
index e8f5b9c..1cc1910 100644
--- a/doc/client/miscellaneous.rst
+++ b/doc/client/miscellaneous.rst
@@ -3,6 +3,279 @@
Green creation of PyTango objects
---------------------------------
+PyTango supports cooperative green Tango objects. Since version 8.1 two *green*
+modes have been added: :obj:`~PyTango.GreenMode.Gevent` and
+:obj:`~PyTango.GreenMode.Futures`.
+
+The :obj:`~PyTango.GreenMode.Gevent` mode uses the well known :mod:`gevent`
+module. The :obj:`~PyTango.GreenMode.Futures` uses the standard python module
+:mod:`concurrent.futures`.
+
+You can set the PyTango green mode at a global level. You can set environment
+variable :envvar:`PYTANGO_GREEN_MODE` to either gevent or futures
+(case incensitive). If this environment variable is not defined the mode
+defaults to *Synchronous*.
+
+Currently, at version 8.1, only :class:`DeviceProxy` has been modified to work
+in a green cooperative way. If the work is found to be useful, the same can
+be implemented in the future for :class:`AttributeProxy` and even
+to :class:`Database`.
+
+You can also change the active global green mode at any time in your program::
+
+ >>> from PyTango import DeviceProxy, GreenMode
+ >>> from PyTango import set_green_mode, get_green_mode
+
+ >>> get_green_mode()
+ PyTango.GreenMode.Synchronous
+
+ >>> dev = DeviceProxy("sys/tg_test/1")
+ >>> dev.get_green_mode()
+ PyTango.GreenMode.Synchronous
+
+ >>> set_green_mode(GreenMode.Gevent)
+ >>> get_green_mode()
+ PyTango.GreenMode.Gevent
+
+ >>> dev.get_green_mode()
+ PyTango.GreenMode.Gevent
+
+As you can see by the example, the global green mode will affect any previously
+created :class:`DeviceProxy` using the default constructor parameters.
+
+You can specificy green mode on a :class:`DeviceProxy` at creation time.
+You can also change green mode of an object at any time::
+
+ >>> from PyTango.gevent import DeviceProxy
+
+ >>> dev = DeviceProxy("sys/tg_test/1")
+ >>> dev.get_green_mode()
+ PyTango.GreenMode.Gevent
+
+ >>> from PyTango import GreenMode
+ >>> from PyTango import set_green_mode, get_green_mode
+ >>> get_green_mode()
+ PyTango.GreenMode.Synchronous
+
+ >>> dev.set_green_mode(GreenMode.Synchronous)
+ >>> dev.get_green_mode()
+ PyTango.GreenMode.Synchronous
+
+gevent mode
+~~~~~~~~~~~
+
+Using :mod:`gevent` cooperative mode in PyTango is relatively easy::
+
+ >>> from PyTango.gevent import DeviceProxy
+
+ >>> dev = DeviceProxy("sys/tg_test/1")
+ >>> dev.get_green_mode()
+ PyTango.GreenMode.Gevent
+
+ >>> print(dev.state())
+ RUNNING
+
+The :func:`PyTango.gevent.DeviceProxy` API is exactly the same as the standard
+:class:`~PyTango.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 :func:`PyTango.gevent.DeviceProxy`:
+
+* Constructor
+* :meth:`~DeviceProxy.state`
+* :meth:`~DeviceProxy.status`
+* :meth:`~DeviceProxy.read_attribute`
+* :meth:`~DeviceProxy.write_attribute`
+* :meth:`~DeviceProxy.write_read_attribute`
+* :meth:`~DeviceProxy.read_attributes`
+* :meth:`~DeviceProxy.write_attributes`
+* :meth:`~DeviceProxy.ping`
+
+So how does this work in fact? I see no difference from using the *standard*
+:class:`~PyTango.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 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 :class:`~PyTango.DeviceProxy`.
+If, *wait* is set to `False`, the result will be a
+:class:`gevent.event.AsyncResult`. In this case, to get the actual value
+you will need to do something like::
+
+ >>> from PyTango.gevent import DeviceProxy
+
+ >>> dev = DeviceProxy("sys/tg_test/1")
+ >>> result = dev.state(wait=False)
+ >>> result
+ <gevent.event.AsyncResult at 0x1a74050>
+
+ >>> # this will be the time consuming code
+ >>> state = result.get()
+ >>> print(state)
+ RUNNING
+
+Here is another example using :meth:`~DeviceProxy.read_attribute`::
+
+ >>> from PyTango.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 = PyTango.AttrDataFormat.SPECTRUM
+ dim_x = 256
+ dim_y = 0
+ has_failed = False
+ is_empty = False
+ name = 'wave'
+ nb_read = 256
+ nb_written = 0
+ quality = PyTango.AttrQuality.ATTR_VALID
+ r_dimension = AttributeDimension(dim_x = 256, dim_y = 0)
+ time = TimeVal(tv_nsec = 0, tv_sec = 1383923292, tv_usec = 886720)
+ type = PyTango.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 :mod:`gevent` when
+ compared with :mod:`concurrent.futures`
+
+futures mode
+~~~~~~~~~~~~
+
+Using :mod:`concurrent.futures` cooperative mode in PyTango is relatively easy::
+
+ >>> from PyTango.futures import DeviceProxy
+
+ >>> dev = DeviceProxy("sys/tg_test/1")
+ >>> dev.get_green_mode()
+ PyTango.GreenMode.Futures
+
+ >>> print(dev.state())
+ RUNNING
+
+The :func:`PyTango.futures.DeviceProxy` API is exactly the same as the standard
+:class:`~PyTango.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 :func:`PyTango.futures.DeviceProxy`:
+
+* Constructor
+* :meth:`~DeviceProxy.state`
+* :meth:`~DeviceProxy.status`
+* :meth:`~DeviceProxy.read_attribute`
+* :meth:`~DeviceProxy.write_attribute`
+* :meth:`~DeviceProxy.write_read_attribute`
+* :meth:`~DeviceProxy.read_attributes`
+* :meth:`~DeviceProxy.write_attributes`
+* :meth:`~DeviceProxy.ping`
+
+So how does this work in fact? I see no difference from using the *standard*
+:class:`~PyTango.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 :class:`~PyTango.DeviceProxy`.
+If, *wait* is set to `False`, the result will be a
+:class:`concurrent.futures.Future`. In this case, to get the actual value
+you will need to do something like::
+
+ >>> from PyTango.futures import DeviceProxy
+
+ >>> dev = DeviceProxy("sys/tg_test/1")
+ >>> result = dev.state(wait=False)
+ >>> result
+ <Future at 0x16cb310 state=pending>
+
+ >>> # this will be the time consuming code
+ >>> state = result.result()
+ >>> print(state)
+ RUNNING
+
+Here is another example using :meth:`~DeviceProxy.read_attribute`::
+
+ >>> from PyTango.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 = PyTango.AttrDataFormat.SPECTRUM
+ dim_x = 256
+ dim_y = 0
+ has_failed = False
+ is_empty = False
+ name = 'wave'
+ nb_read = 256
+ nb_written = 0
+ quality = PyTango.AttrQuality.ATTR_VALID
+ r_dimension = AttributeDimension(dim_x = 256, dim_y = 0)
+ time = TimeVal(tv_nsec = 0, tv_sec = 1383923329, tv_usec = 451821)
+ type = PyTango.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]
+
+Green API
+~~~~~~~~~
+
+.. autofunction:: get_green_mode
+
+.. autofunction:: set_green_mode
+
+.. autofunction:: PyTango.gevent.DeviceProxy
+
+.. autofunction:: PyTango.futures.DeviceProxy
+
+
+Low level API
+~~~~~~~~~~~~~
+
.. autofunction:: get_device_proxy
.. autofunction:: get_attribute_proxy
diff --git a/src/boost/python/attribute_proxy.py b/src/boost/python/attribute_proxy.py
index 1e6d59d..67f0a6f 100644
--- a/src/boost/python/attribute_proxy.py
+++ b/src/boost/python/attribute_proxy.py
@@ -189,7 +189,7 @@ def __AttributeProxy__put_property(self, value):
Return : None
Throws : ConnectionFailed, CommunicationFailed
- DevFailed from device (DB_SQLError)
+ DevFailed from device (DB_SQLError)
"""
if isinstance(value, DbData):
pass
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/pytango.git
More information about the debian-science-commits
mailing list