|
cumbia-tango 1.x
C++ multi threaded library based on cumbia and the Tango control system
|
In this tutorial, we will learn how to write an activity to read Tango attribute, device and class properties from the Tango database. The example discussed here makes already part of the library, but it can be used to create custom activities to automate operations or to simply understand how to write activities.
We need to recall cumbia CuActivity concepts and will be inspired by CuTReader implementation.
CuTReader implements the CuTangoActionI interface, which in turn derives from CuThreadListener so as to force subclasses to provide the
methods. CuTReader inherits from the CuTangoActionI interface in order to integrate with CumbiaTango and the action factory service, that allows to provide a per device thread organisation. Since in our case we deal with database properties, we choose a different approach, since not every action has to do with a device (for example, a class property is not related to a device).
With qtcreator, we add a new C++ class, name it CuTDbPropertyReader and let it inherit from the CuThreadListener interface. Once the file is created and opened in the editor, right click on the CuTDbPropertyReader class definition, choose refactor and then Insert virtual functions of base classes.
The cutdbpropertyreader.h file will look like this:
Right clicking on every method definition, let qtcreator create empty bodies for each function.
CuTDbPropertyReader will be a proxy to the activity fetching the data from the database, so that clients do not have to directly deal with the activity.
CuTangoActionI Type enum defines a few fundamental types of actions that can be implemented. We will use the DbReadProp.
Let's adopt the bridge pattern, also known as d private pointer by the Qt developers, so that CuTDbPropertyReader can be extended in the future without causing troubles to binary compatibility. To accomplish this, add the line
at the top of the header file and the d private class attribute:
Let's move to the CPP file, define the private class and don't forget to allocate it in the constructor. We need to include some header files to provide needed definitions. cumbia library provides an object that bundles keys to values: CuData. We can use it to provide a list of database device, attribute or class properties that we want to fetch, in_props. A set of CuDataListener objects is stored within the listeners variable.
cumbia is a reference to the CumbiaTango engine. Cumbia base would be enough for this simple case, where there's no thread sharing across different instances of CuTDbPropertyReader. Nonetheless, since every cumbia application connecting to Tango instantiates CumbiaTango, we use it because methods to provide the thread factory and the event bridge in use (see Cumbia::registerActivity comments below).
CuTDbPropertyReader must grab a reference to Cumbia and a list of desired database properties must be provided at some time. We decide to pass the Cumbia reference in the constructor, together with an id that will identify every CuTDbPropertyReader used in the application (see "Registering *CuGetTDbPropActivity* with Cumbia" paragraph). We provide the list of desired properties in the get method instead.
An additional method called addListener is added in order to let objects implementing CuDataListener receive new data from the worker thread.
In the .cpp:
Don't forget to delete the d pointer in the destructor:
The get method accept a list of desired properties and fetches them from the Tango database. We need a cumbia activity, an implementation of CuActivity, to carry out the task in a separate thread and post the result through the onResult method of CuTDbPropertyReader. Let's call it CuGetTDbPropActivity, that stands for *(cumbia) get Tango database property activity. It implements CuActivity. With the help of qtcreator, add a new class with that name. Then, as we did before, add necessary includes and virtual method definitions (.h) and implementation (.cpp). We like to have a D pointer store the private fields of the class, as we did before.
Right clicking on every method definition in the .h file, you can add an empty implementation in the corresponding cpp.
At this point, we have the structure of an object that clients will use to fetch Tango database properties (proxy) and the activity that will carry out the actual task in a separate thread. Let the CuGetTDbPropActivity constructor accept the list of properties to fetch.
cumbia-tango library keeps the Tango aware code in a header/cpp couple of files named tango-world.h/.cpp. There goes the code accessing Tango functions, in order to keep them off other places within cumbia code. In your case, you can integrate Tango calls in your activity implementation.
A list of CuData will contains the names and the types of properties we want to fetch.
Every CuData must contain:
The list of CuData will be passed to the CuTDbPropertyReader::get method.
Every activity must be registered with cumbia, so that it can be searched by token, paused and resumed (if it's a continuous activity), and finally unregistered. Cumbia searches amongst all the registered threads to see if one with the same token is already there. If not, a new one is created and started. For example, in CuTReader a thread token is created with the "device" key associated to the Tango device name. In this way, Cumbia reuses threads working on the same device. To do so, a Cumbia method is available:
CumbiaTango provides methods to get the thread factory and the event bridge in use.
Let's then mix these ingredients to register our activity in the CuTDbPropertyReader::get method:
Cumbia registerActivity creates a new thread and starts it. At this point, we must write the code to fetch the properties from the database inside the activity three entry points: init, execute and onExit.
Database properties are fetched in a separate thread. Let's have a look at the CuGetTDbPropActivity three worker methods. The list of properties to get is stored in the in_data field of the CuGetTDbPropActivityPrivate object. We make use of the method CuTangoWorld::get_properties, written in the library file cutango-world.cpp. It accepts as input a list of CuData and a reference to a CuData where results are placed. A tango database host can be optionally specified as last parameter.
get_properties method definition, from cutango-world.cpp
All the work is carried out by this method, so let's call it from within the execute method of CuGetTDbPropActivity, in the cugettdbpropactivity.cpp file:
Using the CuTangoWorld class helper we fetch the properties, that are saved within res, of type CuData. Finally, to make the result available on the main thread, we must remember to call publishResult.
We have now to test the written code. To accomplish this, with qt creator we create a plain C++ application. The project name can be "dbproperties". We will write a command line utility to print the device/class/attribute properties on the command line. Open the dbproperties.pro file: we need to add the include path and libraries for cumbia and cumbia tango
Create the project and then add a new class named "PropertyReader".
Let PropertyReader inherit from CuDataListener and add the pure virtual method onUpdate implementation with qt creator. Its constructor can have empty arguments, while a get method will accept an id as string and the list of required properties and use a CuTDbPropertyReader to fetch them. onUpdate will receive the results.
Let's start having a look at the skeleton of the PropertyReader class created with qt creator.
Add the necessary includes to the .cpp file
As required by cumbia applications, a CumbiaTango object must be instantiated for Tango clients. Since cumbia is multi threaded, we must pass a C++ thread implementation to the CumbiaTango constructor, as well as a so called bridge that is used to forward events from the secondary thread (worker) to the main one. Cumbia offers base implementations of both objects. For Qt applications, we would use QThreadsEventBridge, that employs Qt QApplication and QApplication's postEvent as a means to deliver events between separate threads. For non Qt applications, we will use base event loop and event bridge provided by cumbia, namely CuThreadsEventBridge. For both Qt and non Qt applications, CuThread (cumbia C++11 thread implementation) are normally used. These two objects that parametrize CumbiaTango are not directly instantiated by the client, but rather through a couple of factories. In the Qt/QApplication scenario, QApplication transparently runs an event loop. In our simple console application, we must start the cumbia base event loop. This is accomplished in the PropertyReader constructor as follows:
The event loop is a cumbia service. Cumbia avoids singleton patterns and it rather uses the service provider pattern to supply application wide access to "services" from anywhere. CuServiceProvider is where services are registered and then fetched (see the registerService and get methods in the snipped above. The event loop is executed at last.
m_ct is a CumbiaTango class attribute, that is declared within PropertyReader class definition.
Let's now examine the main.cpp of this application before going back to the propertyreader.cpp. Properties are saved into a vector of strings by parsing the command line arguments. Then a PropertyReader is asked to fetch them from the Tango database.
The get method of the PropertyReader class will be now discussed. The first argument is an id that helps cumbia execute several property readers in different threads. The second is a list of strings with the desired properties. Basically, in the for loop, the program tries to distinguish between device, attribute and class property according to the expression provided in the command line. The application recognizes these three forms:
get parses the queries and adds a descriptive CuData to a list called in_list.
When the list is ready, a CuTDbPropertyReader is created, addListener is called to get updates and finally CuTDbPropertyReader::get is called with the string id and the list as parameters.
Since CuTDbPropertyReader works in a separate thread, we must keep the current one waiting for the results. For this, right after the CuTDbPropertyReader::get call, we ask the event loop to wait for the exit signal. The exit signal is invoked by the PropertyReader::onUpdate method, once data has been received and displayed.
As you can see, after *wait*ing, we proceed to delete the CumbiaTango and the CuTDbPropertyReader.
The onUpdate method below simply extracts data from the CuData received and prints it nicely on the console. Finally, exit is called on the event loop.
The data handed to the onUpdate method contains a "list" key which value is a list of strings containing all the names of the properties stored in the CuData. Iterating on such list we are able to print the value of each property as a string.
When the dbproperties application is launched with this command:
the output is like this:
As you can see, there is no test/device/2/double_scalar:values property in the tango database at the moment.
If you want to know all the properties of an attribute and the tango class "Description", you will execute:
and get this result:
In this tutorial we've learnt how to deal with writing a simple cumbia activity. The client of the activity, the property reader example, is a little bit complicated by the need of dealing with activities that work in a separate thread. For this, we had to use cumbia event loop implementation, calling execute, wait and exit at the right moment. Generally, activities are thought to be used within a multi threaded environment where a event loop is given for free, as it is in Qt's QApplication. In that case, the programmer's work is much easier.
1.9.5