[pytango] 326/483: updating documentation
Sandor Bodo-Merle
sbodomerle-guest at moszumanska.debian.org
Thu Sep 28 19:14:56 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 986e3d48ef08c8d8de869c18b731c7e2f6581957
Author: tiagocoutinho <tiagocoutinho at 4e9c00fd-8f2e-0410-aa12-93ce3db5e235>
Date: Mon Nov 25 15:15:08 2013 +0000
updating documentation
git-svn-id: http://svn.code.sf.net/p/tango-cs/code/bindings/PyTango/trunk@24366 4e9c00fd-8f2e-0410-aa12-93ce3db5e235
---
doc/client/miscellaneous.rst | 143 ++++++++++++++++++++++---------------------
1 file changed, 73 insertions(+), 70 deletions(-)
diff --git a/doc/client/miscellaneous.rst b/doc/client/miscellaneous.rst
index 66c183e..07b1db5 100644
--- a/doc/client/miscellaneous.rst
+++ b/doc/client/miscellaneous.rst
@@ -4,24 +4,22 @@ Green 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`.
+modes have been added: :obj:`~PyTango.GreenMode.Futures` and
+:obj:`~PyTango.GreenMode.Gevent`.
-The :obj:`~PyTango.GreenMode.Gevent` mode uses the well known :mod:`gevent`
-module. The :obj:`~PyTango.GreenMode.Futures` uses the standard python module
+The :obj:`~PyTango.GreenMode.Futures` uses the standard python module
:mod:`concurrent.futures`.
+The :obj:`~PyTango.GreenMode.Gevent` mode uses the well known gevent_ library.
-You can set the PyTango green mode at a global level. Set the environment
-variable :envvar:`PYTANGO_GREEN_MODE` to either gevent_ or futures
-(case incensitive). If this environment variable is not defined the PyTango
-global green mode defaults to *Synchronous*.
-
-Currently, at version 8.1, only :class:`DeviceProxy` has been modified to work
+Currently, in 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 set the PyTango green mode at a global level. Set the environment
+variable :envvar:`PYTANGO_GREEN_MODE` to either *futures* or *gevent*
+(case incensitive). If this environment variable is not defined the PyTango
+global green mode defaults to *Synchronous*.
You can also change the active global green mode at any time in your program::
@@ -35,54 +33,50 @@ You can also change the active global green mode at any time in your program::
>>> dev.get_green_mode()
PyTango.GreenMode.Synchronous
- >>> set_green_mode(GreenMode.Gevent)
+ >>> set_green_mode(GreenMode.Futures)
>>> get_green_mode()
- PyTango.GreenMode.Gevent
+ PyTango.GreenMode.Futures
>>> dev.get_green_mode()
- PyTango.GreenMode.Gevent
+ PyTango.GreenMode.Futures
As you can see by the example, the global green mode will affect any previously
-created :class:`DeviceProxy` using the default constructor parameters.
+created :class:`DeviceProxy` using the default *DeviceProxy* constructor
+parameters.
You can specificy green mode on a :class:`DeviceProxy` at creation time.
You can also change the green mode at any time::
- >>> from PyTango.gevent import DeviceProxy
+ >>> from PyTango.futures 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
+ PyTango.GreenMode.Futures
>>> dev.set_green_mode(GreenMode.Synchronous)
>>> dev.get_green_mode()
PyTango.GreenMode.Synchronous
-gevent mode
-~~~~~~~~~~~
+futures mode
+~~~~~~~~~~~~
-Using :mod:`gevent` cooperative mode in PyTango is relatively easy::
+Using :mod:`concurrent.futures` cooperative mode in PyTango is relatively easy::
- >>> from PyTango.gevent import DeviceProxy
+ >>> from PyTango.futures import DeviceProxy
>>> dev = DeviceProxy("sys/tg_test/1")
>>> dev.get_green_mode()
- PyTango.GreenMode.Gevent
+ PyTango.GreenMode.Futures
>>> print(dev.state())
RUNNING
-The :func:`PyTango.gevent.DeviceProxy` API is exactly the same as the standard
+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 *gevent* semantics are,
-on the :func:`PyTango.gevent.DeviceProxy`:
+The list of methods that have been modified to accept *futures* semantics are,
+on the :func:`PyTango.futures.DeviceProxy`:
* Constructor
* :meth:`~DeviceProxy.state`
@@ -96,46 +90,46 @@ on the :func:`PyTango.gevent.DeviceProxy`:
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
+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 with other greenlets.
+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 timeout is `None` which means wait forever.
-If *wait* is set to `False`, the *timeout* is ignored.
+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
+:class:`concurrent.futures.Future`. In this case, to get the actual value
you will need to do something like::
- >>> from PyTango.gevent import DeviceProxy
+ >>> from PyTango.futures import DeviceProxy
>>> dev = DeviceProxy("sys/tg_test/1")
>>> result = dev.state(wait=False)
>>> result
- <gevent.event.AsyncResult at 0x1a74050>
+ <Future at 0x16cb310 state=pending>
>>> # this will be the blocking code
- >>> state = result.get()
+ >>> state = result.result()
>>> print(state)
RUNNING
Here is another example using :meth:`~DeviceProxy.read_attribute`::
- >>> from PyTango.gevent import DeviceProxy
+ >>> from PyTango.futures import DeviceProxy
>>> dev = DeviceProxy("sys/tg_test/1")
>>> result = dev.read_attribute('wave', wait=False)
>>> result
- <gevent.event.AsyncResult at 0x1aff54e>
+ <Future at 0x16cbe50 state=pending>
- >>> dev_attr = result.get()
+ >>> dev_attr = result.result()
>>> print(dev_attr)
DeviceAttribute[
data_format = PyTango.AttrDataFormat.SPECTRUM
@@ -148,7 +142,7 @@ Here is another example using :meth:`~DeviceProxy.read_attribute`::
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)
+ 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,
@@ -160,32 +154,34 @@ Here is another example using :meth:`~DeviceProxy.read_attribute`::
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`
+gevent mode
+~~~~~~~~~~~
-futures mode
-~~~~~~~~~~~~
+.. warning::
+ Before using gevent mode please note that at the time of writing this
+ documentation, *PyTango.gevent* requires an unreleased version 1.0 of
+ gevent (the last official version of gevent is 0.13.6 which was released
+ more than 2.5 years ago). Also take into account that gevent_ is *not*
+ available on python 3.
+ So please consider using the *Futures* mode instead.
-Using :mod:`concurrent.futures` cooperative mode in PyTango is relatively easy::
+Using gevent_ cooperative mode in PyTango is relatively easy::
- >>> from PyTango.futures import DeviceProxy
+ >>> from PyTango.gevent import DeviceProxy
>>> dev = DeviceProxy("sys/tg_test/1")
>>> dev.get_green_mode()
- PyTango.GreenMode.Futures
+ PyTango.GreenMode.Gevent
>>> print(dev.state())
RUNNING
-The :func:`PyTango.futures.DeviceProxy` API is exactly the same as the standard
+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 *futures* semantics are,
-on the :func:`PyTango.futures.DeviceProxy`:
+The list of methods that have been modified to accept *gevent* semantics are,
+on the :func:`PyTango.gevent.DeviceProxy`:
* Constructor
* :meth:`~DeviceProxy.state`
@@ -199,46 +195,46 @@ on the :func:`PyTango.futures.DeviceProxy`:
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
+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.
+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.
+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 :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
+:class:`gevent.event.AsyncResult`. In this case, to get the actual value
you will need to do something like::
- >>> from PyTango.futures import DeviceProxy
+ >>> from PyTango.gevent import DeviceProxy
>>> dev = DeviceProxy("sys/tg_test/1")
>>> result = dev.state(wait=False)
>>> result
- <Future at 0x16cb310 state=pending>
+ <gevent.event.AsyncResult at 0x1a74050>
>>> # this will be the blocking code
- >>> state = result.result()
+ >>> state = result.get()
>>> print(state)
RUNNING
Here is another example using :meth:`~DeviceProxy.read_attribute`::
- >>> from PyTango.futures import DeviceProxy
+ >>> from PyTango.gevent import DeviceProxy
>>> dev = DeviceProxy("sys/tg_test/1")
>>> result = dev.read_attribute('wave', wait=False)
>>> result
- <Future at 0x16cbe50 state=pending>
+ <gevent.event.AsyncResult at 0x1aff54e>
- >>> dev_attr = result.result()
+ >>> dev_attr = result.get()
>>> print(dev_attr)
DeviceAttribute[
data_format = PyTango.AttrDataFormat.SPECTRUM
@@ -251,7 +247,7 @@ Here is another example using :meth:`~DeviceProxy.read_attribute`::
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)
+ 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,
@@ -263,23 +259,30 @@ Here is another example using :meth:`~DeviceProxy.read_attribute`::
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`
+
+
Green API
~~~~~~~~~
Summary:
* :func:`PyTango.get_green_mode`
* :func:`PyTango.set_green_mode`
- * :func:`PyTango.gevent.DeviceProxy`
* :func:`PyTango.futures.DeviceProxy`
+ * :func:`PyTango.gevent.DeviceProxy`
.. autofunction:: PyTango.get_green_mode
.. autofunction:: PyTango.set_green_mode
-.. autofunction:: PyTango.gevent.DeviceProxy
-
.. autofunction:: PyTango.futures.DeviceProxy
+.. autofunction:: PyTango.gevent.DeviceProxy
+
Low level API
#############
--
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