# Writing a TANGO client using TANGO C++ APIs

Intended audience: developers, Programming language: c++

## Introduction

TANGO devices and database are implemented using the TANGO device server model. To access them the user has the CORBA interface e.g. command_inout(), write_attributes() etc. defined by the idl file. These methods are very low-level and assume a good working knowledge of CORBA. In order to simplify this access, high-level api has been implemented which hides all CORBA aspects of TANGO. In addition the api hides details like how to connect to a device via the database, how to reconnect after a device has been restarted, how to correctly pack and unpack attributes and so on by implementing these in a manner transparent to the user. The api provides a unified error handling for all TANGO and CORBA errors. Unlike the CORBA C++ bindings the TANGO api supports native C++ data types e.g. strings and vectors.

This chapter describes how to use these API’s. It is not a reference guide. Reference documentation is available as Web pages in the TANGO home page

## Getting Started

Refer to the chapter Getting Started for an example on getting start with the C++ or Java api.

## Basic Philosophy

The basic philosophy is to have high level classes to deal with Tango devices. To communicate with Tango device, uses the DeviceProxy class. To send/receive data to/from Tango device, uses the DeviceData, DeviceAttribute or DevicePipe classes. To communicate with a group of devices, use the Group class. If you are interested only in some attributes provided by a Tango device, uses the AttributeProxy class. Even if the Tango database is implemented as any other devices (and therefore accessible with one instance of a DeviceProxy class), specific high level classes have been developped to query it. Uses the Database, DbDevice, DbClass, DbServer or DbData classes when interfacing the Tango database. Callback for asynchronous requests or events are implemented via a CallBack class. An utility class called ApiUtil is also available.

## Data types

The definition of the basic data type you can transfert using Tango is:

Tango type name | C++ equivalent type
--- | ---
DevBoolean | `boolean`
DevShort | `short`
DevEnum | enumeration (only for attribute / See chapter on advanced features)
DevLong | `int` (always 32 bits data)
DevLong64 | `long long` on 32 bits chip or `long` on 64 bits chip (always 64 bits data)
DevFloat | `float`
DevDouble | `double`
DevString | `char \*`
DevEncoded | `structure` with 2 fields: a string and an array of unsigned char
DevUChar | `unsigned char`
DevUShort | `unsigned short`
DevULong | `unsigned int` (always 32 bits data)
DevULong64 | `unsigned long long` on 32 bits chip or `unsigned long` on 64 bits chip (always 64 bits data)
DevState | Tango specific data type

Using commands, you are able to transfert all these data types, array of these basic types and two other Tango specific data types called DevVarLongStringArray and DevVarDoubleStringArray. See chapter [Data exchange] to get details about them. You are also able to create attributes using any of these basic data types to transfer data between clients and servers.

## Request model

For the most important API remote calls (command_inout, read_attribute(s) and write_attribute(s)), Tango supports two kind of requests which are the synchronous model and the asynchronous model. Synchronous model means that the client wait (and is blocked) for the server to send an answer. Asynchronous model means that the client does not wait for the server to send an answer. The client sends the request and immediately returns allowing the CPU to do anything else (like updating a graphical user interface). Device pipe supports only the synchronous model. Within Tango, there are two ways to retrieve the server answer when using asynchronous model. They are:

1. The polling mode

2. The callback mode

In polling mode, the client executes a specific call to check if the answer is arrived. If this is not the case, an exception is thrown. If the reply is there, it is returned to the caller and if the reply was an exception, it is re-thrown. There are two calls to check if the reply is arrived:

- Call which does not wait before the server answer is returned to the caller.

- Call which wait with timeout before returning the server answer to the caller (or throw the exception) if the answer is not arrived.

In callback model, the caller must supply a callback method which will be executed when the command returns. They are two sub-modes:

1. The pull callback mode

2. The push callback mode

In the pull callback mode, the callback is triggered if the server answer is arrived when the client decide it by calling a synchronization method (The client pull-out the answer). In push mode, the callback is executed as soon as the reply arrives in a separate thread (The server pushes the answer to the client).

### Synchronous model

Synchronous access to Tango device are provided using the DeviceProxy or AttributeProxy class. For the DeviceProxy class, the main synchronous call methods are :

- command_inout() to execute a Tango device command

- read_attribute() or read_attributes() to read a Tango device attribute(s)

- write_attribute() or write_attributes() to write a Tango device attribute(s)

- write_read_attribute() or write_read_attributes() to write then read Tango device attribute(s)

- read_pipe() to read a Tango device pipe

- write_pipe() to write a Tango device pipe

- write_read_pipe() to write then read Tango device pipe

For commands, data are send/received to/from device using the DeviceData class. For attributes, data are send/received to/from device attribute using the DeviceAttribute class. For pipes, data are send/receive to/from device pipe using the DevicePipe and DevicePipeBlob classes.

In some cases, only attributes provided by a Tango device are interesting for the application. You can use the AttributeProxy class. Its main synchronous methods are :

- read() to read the attribute value

- write() to write the attribute value

- write_read() to write then read the attribute value

Data are transmitted using the DeviceAttribute class.

### Asynchronous model

Asynchronous access to Tango device are provided using DeviceProxy or AttributeProxy, CallBack and ApiUtil classes methods. The main asynchronous call methods and used classes are :

- To execute a command on a device

  - DeviceProxy::command_inout_asynch() and DeviceProxy::command_inout_reply() in polling model.

  - DeviceProxy::command_inout_asynch(), DeviceProxy::get_asynch_replies() and CallBack class in callback pull model

  - DeviceProxy::command_inout_asynch(), ApiUtil::set_asynch_cb_sub_model() and CallBack class in callback push model

- To read a device attribute

  - DeviceProxy::read_attribute_asynch() and DeviceProxy::read_attribute_reply() in polling model

  - DeviceProxy::read_attribute_asynch(), DeviceProxy::get_asynch_replies() and CallBack class in callback pull model.

  - DeviceProxy::read_attribute_asynch(), ApiUtil::set_asynch_cb_sub_model() and CallBack class in callback push model

- To write a device attribute

  - DeviceProxy::write_attribute_asynch() in polling model

  - DeviceProxy::write_attribute_asynch() and CallBack class in callback pull model

  - DeviceProxy::write_attribute_asynch(), ApiUtil::set_asynch_cb_sub_model() and CallBack class in callback push model

For commands, data are send/received to/from device using the DeviceData class. For attributes, data are send/received to/from device attribute using the DeviceAttribute class. It is also possible to generate asynchronous request(s) using the AttributeProxy class following the same schema than above. Methods to use are :

- read_asynch() and read_reply() to asynchronously read the attribute value

- write_asynch() and write_reply() to asynchronously write the attribute value

## Events

### Introduction

Events are a critical part of any distributed control system. Their aim is to provide a communication mechanism which is fast and efficient.

The standard CORBA communication paradigm is a synchronous or asynchronous two-way call. In this paradigm the call is initiated by the client who contacts the server. The server handles the client’s request and sends the answer to the client or throws an exception which the client catches. This paradigm involves two calls to receive a single answer and requires the client to be active in initiating the request. If the client has a permanent interest in a value he is obliged to poll the server for an update in a value every time. This is not efficient in terms of network bandwidth nor in terms of client programming.

For clients who are permanently interested in values the event-driven communication paradigm is a more efficient and natural way of programming. In this paradigm the client registers her interest once in an event (value). After that the server informs the client every time the event has occurred. This paradigm avoids the client polling, frees it for doing other things, is fast and makes efficient use of the network.

The rest of this chapter explains how the TANGO events are implemented and the application programmer’s interface.

### Event definition

TANGO events represent an alternative channel for reading TANGO device attributes. Device attributes values are sent to all subscribed clients when an event occurs. Events can be an attribute value change, a change in the data quality or a periodically send event. The clients continue receiving events as long as they stay subscribed. Most of the time, the device server polling thread detects the event and then pushes the device attribute value to all clients. Nevertheless, in some cases, the delay introduced by the polling thread in the event propagation is detrimental. For such cases, some API calls directly push the event. Until TANGO release 8, the omniNotify implementation of the CORBA Notification service was used to dispatch events. Starting with TANGO 8, this CORBA Notification service has been replaced by the ZMQ library which implements a Publish/Subscribe communication model well adapted to TANGO events communication.

### Event types

The following eight event types have been implemented in TANGO :

1. change - an event is triggered and the attribute value is sent when the attribute value changes significantly. The exact meaning of significant is device attribute dependent. For analog and digital values this is a delta fixed per attribute, for string values this is any non-zero change i.e. if the new attribute value is not equal to the previous attribute value. The delta can either be specified as a relative or absolute change. The delta is the same for all clients unless a filter is specified (see below). To easily write applications using the change event, it is also triggered in the following case :

   1. When a spectrum or image attribute size changes.

   2. At event subscription time

   3. When the polling thread receives an exception during attribute reading

   4. When the polling thread detects that the attribute quality factor has changed.

   5. The first good reading of the attribute after the polling thread has received exception when trying to read the attribute

   6. The first time the polling thread detects that the attribute quality factor has changed from INVALID to something else

   7. When a change event is pushed manually from the device server code. (DeviceImpl::push_change_event()).

   8. By the methods Attribute::set_quality() and Attribute::set_value_date_quality() if a client has subscribed to the change event on the attribute. This has been implemented for cases where the delay introduced by the polling thread in the event propagation is not authorized.

2. periodic - an event is sent at a fixed periodic interval. The frequency of this event is determined by the event_period property of the attribute and the polling frequency. The polling frequency determines the highest frequency at which the attribute is read. The event_period determines the highest frequency at which the periodic event is sent. Note if the event_period is not an integral number of the polling period there will be a beating of the two frequencies [1]. Clients can reduce the frequency at which they receive periodic events by specifying a filter on the periodic event counter.

3. archive - an event is sent if one of the archiving conditions is satisfied. Archiving conditions are defined via properties in the database. These can be a mixture of delta_change and periodic. Archive events can be send from the polling thread or can be manually pushed from the device server code (DeviceImpl::push_archive_event()).

4. attribute configuration - an event is sent if the attribute configuration is changed.

5. data ready - This event is sent when coded by the device server programmer who uses a specific method of one of the Tango device server class to fire the event (DeviceImpl::push_data_ready_event()). The rule of this event is to inform a client that it is now possible to read an attribute. This could be useful in case of attribute with many data.

6. user - The criteria and configuration of these user events are managed by the device server programmer who uses a specific method of one of the Tango device server class to fire the event (DeviceImpl::push_event()).

7. device interface change - This event is sent when the device interface changes. Using Tango, it is possible to dynamically add/remove attribute/command to a device. This event is the way to inform client(s) that attribute/command has been added/removed from a device. Note that this type of event is attached to a device and not to one attribute (like all other event types). This event is triggered in the following case :

   1. A dynamic attribute or command is added or removed. The event is sent after a small delay (50 mS) in order to eliminate the risk of events storm in case several attributes/commands are added/removed in a loop

   2. At the end of admin device RestartServer or DevRestart command

   3. After a re-connection due to a device server restart. Because the device interface is not memorized, the event is sent even if it is highly possible that the device interface has not changed. A flag in the data propagated with the event inform listening applications that the device interface change is not guaranteed.

   4. At event re-connection time. This case is similar to the previous one (device interface change not guaranteed)

8. pipe - This is the kind of event which has to be used when the user want to push data through a pipe. This kind of event is only sent by the user code by using a specific method (DeviceImpl::push_pipe_event()). There is no way to ask the Tango kernel to automatically push this kind of event.

The first three above events are automatically generated by the TANGO library or fired by the user code. Events number 4 and 7 are only automatically sent by the library and events 5, 6 and 8 are fired only by the user code.

### Event filtering (Removed in Tango release 8 and above)

Please, note that this feature is available only for Tango releases older than Tango 8. The CORBA Notification Service allows event filtering. This means that a client can ask the Notification Service to send the event only if some filter is evaluated to true. Within the Tango control system, some pre-defined fields can be used as filter. These fields depend on the event type.

Event type | Filterable field name | Filterable field value | type
--- | --- | --- | ---
change | delta_change_rel | Relative change (in %) since last even | double
delta_change_abs | Absolute change since last event | double
quality | Is set to 1 when the attribute quality factor has changed, otherwise it is 0 | double
forced_event | Is set to 1 when the event was fired on exception or a quality factor set to invalid | double
periodic | counter | Incremented each time the event is sent | long
archive | delta_change_rel | Relative change (in %) since last event | double
delta_change_abs | Absolute change since last event | double

quality

Is set to 1 when the attribute quality

  factor has changed, otherwise it is 0

double

counter | Incremented each time the event is sent for periodic reason. Set to -1 if event sent for change reason | long
forced_event | Is set to 1 when the event was fired on exception or a quality factor set to invalid | double
delta_event | Number of milli-seconds since previous event | double

Filter are defined as a string following a grammar defined by CORBA. It is defined in [NotificationService]. The following example shows you the most common use of these filters in the Tango world :

- To receive periodic event one out of every three, the filter must be

  $counter % 3 == 0

- To receive change event only if the relative change is greater than % (positive and negative), the filter must be

  $delta_change_rel >= 20 or $delta_change_rel <= -20

- To receive a change event only on quality change, the filter must be

  $quality == 1

For user events, the filter field name(s) and their value are defined by the device server programmer.

### Application Programmer’s Interface

How to setup and use the TANGO events ? The interfaces described here are intended as user friendly interfaces to the underlying CORBA calls. The interface is modeled after the asynchronous command_inout() interface so as to maintain coherency. The event system supports push callback model as well as the pull callback model.

The two event reception modes are:

- Push callback model : On event reception a callbacks method gets immediately executed.

- Pull callback model : The event will be buffered the client until the client is ready to receive the event data. The client triggers the execution of the callback method.

The event reception buffer in the pull callback model, is implemented as a round robin buffer. The client can choose the size when subscribing for the event. This way the client can set-up different ways to receive events.

- Event reception buffer size = 1 : The client is interested only in the value of the last event received. All other events that have been received since the last reading are discarded.

- Event reception buffer size > 1 : The client has chosen to keep an event history of a given size. When more events arrive since the last reading, older events will be discarded.

- Event reception buffer size = ALL_EVENTS : The client buffers all received events. The buffer size is unlimited and only restricted by the available memory for the client.

#### Configuring events

The attribute configuration set is used to configure under what conditions events are generated. A set of standard attribute properties (part of the standard attribute configuration) are read from the database at device startup time and used to configure the event engine. If there are no properties defined then default values specified in the code are used.

##### change

The attribute properties and their default values for the change event are :

1. rel_change - a property of maximum 2 values. It specifies the positive and negative relative change of the attribute value w.r.t. the value of the previous change event which will trigger the event. If the attribute is a spectrum or an image then a change event is generated if any one of the attribute value’s satisfies the above criterium. If only one property is specified then it is used for the positive and negative change. If no property is specified, no events are generated.

2. abs_change - a property of maximum 2 values.It specifies the positive and negative absolute change of the attribute value w.r.t the value of the previous change event which will trigger the event. If the attribute is a spectrum or an image then a change event is generated if any one of the attribute value’s satisfies the above criterium. If only one property is specified then it is used for the positive and negative change. If no properties are specified then the relative change is used.

##### periodic

The attribute properties and their default values for the periodic event are :

1. event_period - the minimum time between events (in milliseconds). If no property is specified then a default value of 1 second is used.

##### archive

The attribute properties and their default values for the archive event are :

1. archive_rel_change - a property of maximum 2 values which specifies the positive and negative relative change w.r.t. the previous attribute value which will trigger the event. If the attribute is a spectrum or an image then an archive event is generated if any one of the attribute value’s satisfies the above criterium. If only one property is specified then it is used for the positive and negative change. If no properties are specified then no events are generate.

2. archive_abs_change - a property of maximum 2 values which specifies the positive and negative absolute change w.r.t the previous attribute value which will trigger the event. If the attribute is a spectrum or an image then an archive event is generated if any one of the attribute value’s satisfies the above criterium. If only one property is specified then it is used for the positive and negative change. If no properties are specified then the relative change is used.

3. archive_period - the minimum time between archive events (in milliseconds). If no property is specified, no periodic archiving events are send.

#### C++ Clients

This is the interface for clients who want to receive events. The main action of the client is to subscribe and unsubscribe to events. Once the client has subscribed to one or more events the events are received in a separate thread by the client.

Two reception modes are possible:

- On event reception a callbacks method gets immediately executed.

- The event will be buffered until the client until the client is ready to receive the event data.

The mode to be used has to be chosen when subscribing for the event.

##### Subscribing to events

The client call to subscribe to an event is named DeviceProxy::subscribe_event() . During the event subscription the client has to choose the event reception mode to use.

Push model:

    1int DeviceProxy::subscribe_event(
    2             const string &attribute,
    3             Tango::EventType event,
    4             Tango::CallBack *callback,
    5             bool stateless = false);

The client implements a callback method which is triggered when the event is received. Note that this callback method will be executed by a thread started by the underlying ORB. This thread is not the application main thread. For Tango releases before 8, a similar call with one extra parameter for event filtering is also available.

Pull model:

    1int DeviceProxy::subscribe_event(
    2             const string &attribute,
    3             Tango::EventType event,
    4             int event_queue_size,
    5             bool stateless = false);

The client chooses the size of the round robin event reception buffer. Arriving events will be buffered until the client uses DeviceProxy::get_events() to extract the event data. For Tango releases before 8, a similar call with one extra parameter for event filtering is also available.

On top of the user filter defined by the filters parameter, basic filtering is done based on the reason specified and the event type. For example when reading the state and the reason specified is change the event will be fired only when the state changes. Events consist of an attribute name and the event reason. A standard set of reasons are implemented by the system, additional device specific reasons can be implemented by device servers programmers.

The stateless flag = false indicates that the event subscription will only succeed when the given attribute is known and available in the Tango system. Setting stateless = true will make the subscription succeed, even if an attribute of this name was never known. The real event subscription will happen when the given attribute will be available in the Tango system.

Note that in this model, the callback method will be executed by the thread doing the DeviceProxy::get_events() call.

##### The CallBack class

In C++, the client has to implement a class inheriting from the Tango CallBack class and pass this to the DeviceProxy::subscribe_event() method. The CallBack class is the same class as the one proposed for the TANGO asynchronous call. This is as follows for events :

     1class MyCallback : public Tango::CallBack
     2{
     3   .
     4   .
     5   .
     6   public:
     7   void push_event(Tango::EventData *);
     8   void push_event(Tango::AttrConfEventData *);
     9   void push_event(Tango::DataReadyEventData *);
    10   void push_event(Tango::DevIntrChangeEventData *);
    11   void push_event(Tango::PipeEventData *);
    12}

where EventData is defined as follows :

    1class EventData
    2{
    3   DeviceProxy       *device;
    4   string            attr_name;
    5   string            event;
    6   DeviceAttribute   *attr_value;
    7   bool              err;
    8   DevErrorList      errors;
    9}

AttrConfEventData is defined as follows :

    1class AttrConfEventData
    2{
    3   DeviceProxy       *device;
    4   string            attr_name;
    5   string            event;
    6   AttributeInfoEx   *attr_conf;
    7   bool              err;
    8   DevErrorList      errors;
    9}

DataReadyEventData is defined as follows :

     1class DataReadyEventData
     2{
     3   DeviceProxy       *device;
     4   string            attr_name;
     5   string            event;
     6   int               attr_data_type;
     7   int               ctr;
     8   bool              err;
     9   DevErrorList      errors;
    10}

DevIntrChangeEventData is defined as follows :

     1class DevIntrChangeEventData
     2{
     3   DeviceProxy            device;
     4   string                 event;
     5   string                 device_name;
     6   CommandInfoList        cmd_list;
     7   AttributeInfoListEx    att_list;
     8   bool                   dev_started;
     9   bool                   err;
    10   DevErrorList           errors;
    11}

and PipeEventData is defined as follows :

    1class PipeEventData
    2{
    3   DeviceProxy       *device;
    4   string            pipe_name;
    5   string            event;
    6   DevicePipe        *pipe_value;
    7   bool              err;
    8   DevErrorList      errors;
    9}

In push model, there are some cases (same callback used for events coming from different devices hosted in device server process running on different hosts) where the callback method could be executed concurently by different threads started by the ORB. The user has to code his callback method in a thread safe manner.

##### Unsubscribing from an event

Unsubscribe a client from receiving the event specified by event_id is done by calling the DeviceProxy::unsubscribe_event() method :

    1void DeviceProxy::unsubscribe_event(int event_id);

##### Extract buffered event data

When the pull model was chosen during the event subscription, the received event data can be extracted with DeviceProxy::get_events(). Two possibilities are available for data extraction. Either a callback method can be executed for every event in the buffer when using

    1int DeviceProxy::get_events(
    2             int event_id,
    3             CallBack *cb);

Or all the event data can be directly extracted as EventDataList, AttrConfEventDataList , DataReadyEventDataList, DevIntrChangeEventDataList or PipeEventDataList when using

     1int DeviceProxy::get_events(
     2             int event_id,
     3             EventDataList &event_list);
     4
     5int DeviceProxy::get_events(
     6             int event_id,
     7             AttrConfEventDataList &event_list);
     8
     9int DeviceProxy::get_events(
    10             int event_id,
    11             DataReadyEventDataList &event_list);
    12
    13int DeviceProxy::get_events(
    14             int event_id,
    15             DevIntrChangeEventDataList &event_list);
    16
    17int DeviceProxy::get_events(
    18             int event_id,
    19             PipeEventDataList &event_list);

The event data lists are vectors of EventData, AttrConfEventData, DataReadyEventData or PipeEventData pointers with special destructor and clean-up methods to ease the memory handling.

    1class EventDataList:public vector<EventData *>
    2class AttrConfEventDataList:public vector<AttrConfEventData *>
    3class DataReadyEventDataList:public vector<DataReadyEventData *>
    4class DevIntrChangeEventDataList:public vector<DevIntrChangeEventData *>
    5class PipeEventDataList:public vector<PipeEventData *>

##### Example

Here is a typical code example of a client to register and receive events. First, you have to define a callback method as follows:

     1class DoubleEventCallBack : public Tango::CallBack
     2{
     3   void push_event(Tango::EventData*);
     4};
     5
     6
     7void DoubleEventCallBack::push_event(Tango::EventData *myevent)
     8{
     9    Tango::DevVarDoubleArray *double_value;
    10    try
    11    {
    12        cout << "DoubleEventCallBack::push_event(): called attribute "
    13             << myevent->attr_name
    14             << " event "
    15             << myevent->event
    16             << " (err="
    17             << myevent->err
    18             << ")" << endl;
    19
    20
    21         if (!myevent->err)
    22         {
    23             *(myevent->attr_value) >> double_value;
    24             cout << "double value "
    25                  << (*double_value)[0]
    26                  << endl;
    27             delete double_value;
    28         }
    29    }
    30    catch (...)
    31    {
    32         cout << "DoubleEventCallBack::push_event(): could not extract data !\n";
    33    }
    34}

Note

If the event is an error event (myevent->err == true), the attr_value field in myevent EventData object will be empty (null pointer). The same applies for some other kinds of events. For example, attr_conf field in AttrConfEventData object will be a null pointer in case of error event (if the err field is true). As a consequence, the device server programmer should always check the err field before trying to extract the EventData::attr_value or AttrConfEventData::attr_conf fields associated to the event.

Then the main code must subscribe to the event and choose the push or the pull model for event reception.

Push model:

     1DoubleEventCallBack *double_callback = new DoubleEventCallBack;
     2
     3Tango::DeviceProxy *mydevice = new Tango::DeviceProxy("my/device/1");
     4
     5int event_id;
     6const string attr_name("current");
     7event_id = mydevice->subscribe_event(attr_name,
     8                         Tango::CHANGE_EVENT,
     9                         double_callback);
    10cout << "event_client() id = " << event_id << endl;
    11
    12// The callback methods are executed by the Tango event reception thread.
    13// The main thread is not concerned of event reception.
    14// Whatch out with synchronisation and data access in a multi threaded environment!
    15
    16sleep(1000); // wait for events
    17
    18mydevice->unsubscribe_event(event_id);

Pull model:

     1DoubleEventCallBack *double_callback = new DoubleEventCallBack;
     2int event_queue_size = 100; // keep the last 100 events
     3
     4Tango::DeviceProxy *mydevice = new Tango::DeviceProxy("my/device/1");
     5
     6int event_id;
     7const string attr_name("current");
     8event_id = mydevice->subscribe_event(attr_name,
     9                         Tango::CHANGE_EVENT,
    10                         event_queue_size);
    11cout << "event_client() id = " << event_id << endl;
    12
    13// Check every 3 seconds whether new events have arrived and trigger the callback method
    14// for the new events.
    15
    16for (int i=0; i < 100; i++)
    17{
    18    sleep (3);
    19
    20    // Read the stored event data from the queue and call the callback method for every event.
    21    mydevice->get_events(event_id, double_callback);
    22}
    23
    24event_test->unsubscribe_event(event_id);

## Group

A Tango Group provides the user with a single point of control for a collection of devices. By analogy, one could see a Tango Group as a proxy for a collection of devices. For instance, the Tango Group API supplies a command_inout() method to execute the same command on all the elements of a group.

A Tango Group is also a hierarchical object. In other words, it is possible to build a group of both groups and individual devices. This feature allows creating logical views of the control system - each view representing a hierarchical family of devices or a sub-system.

In this chapter, we will use the term hierarchy to refer to a group and its sub-groups. The term Group designates to the local set of devices attached to a specific Group.

### Getting started with Tango group

The quickest way of getting started is to study an example…

Imagine we are vacuum engineers who need to monitor and control hundreds of gauges distributed over the 16 cells of a large-scale instrument. Each cell contains several penning and pirani gauges. It also contains one strange gauge. Our main requirement is to be able to control the whole set of gauges, a family of gauges located into a particular cell (e.g. all the penning gauges of the 6th cell) or a single gauge (e.g. the strange gauge of the 7th cell). Using a Tango Group, such features are quite straightforward to obtain.

Reading the description of the problem, the device hierarchy becomes obvious. Our gauges group will have the following structure:

     1-> gauges
     2  |  -> cell-01
     3  |     |-> inst-c01/vac-gauge/strange
     4  |     |-> penning
     5  |     |   |-> inst-c01/vac-gauge/penning-01
     6  |     |   |-> inst-c01/vac-gauge/penning-02
     7  |     |   |- ...
     8  |     |   |-> inst-c01/vac-gauge/penning-xx
     9  |     |-> pirani
    10  |         |-> inst-c01/vac-gauge/pirani-01
    11  |         |-> ...
    12  |         |-> inst-c01/vac-gauge/pirani-xx
    13  |  -> cell-02
    14  |     |-> inst-c02/vac-gauge/strange
    15  |     |-> penning
    16  |     |   |-> inst-c02/vac-gauge/penning-01
    17  |     |   |-> ...
    18  |     |
    19  |     |-> pirani
    20  |     |   |-> ...
    21  |  -> cell-03
    22  |     |-> ...
    23  |         | -> ...

In the C++, such a hierarchy can be build as follows (basic version):

     1//- step0: create the root group
     2Tango::Group *gauges = new Tango::Group("gauges");
     3
     4
     5//- step1: create a group for the n-th cell
     6Tango::Group *cell = new Tango::Group("cell-01");
     7
     8
     9//- step2: make the cell a sub-group of the root group
    10gauges->add(cell);
    11
    12
    13//- step3: create a "penning" group
    14Tango::Group *gauge_family = new Tango::Group("penning");
    15
    16
    17//- step4: add all penning gauges located into the cell (note the wildcard)
    18gauge_family->add("inst-c01/vac-gauge/penning*");
    19
    20
    21//- step5: add the penning gauges to the cell
    22cell->add(gauge_family);
    23
    24
    25//- step6: create a "pirani" group
    26gauge_family = new Tango::Group("pirani");
    27
    28
    29//- step7: add all pirani gauges located into the cell (note the wildcard)
    30gauge_family->add("inst-c01/vac-gauge/pirani*");
    31
    32
    33//- step8: add the pirani gauges to the cell
    34cell->add(gauge_family);
    35
    36
    37//- step9: add the "strange" gauge to the cell
    38cell->add("inst-c01/vac-gauge/strange");
    39
    40
    41//- repeat step 1 to 9 for the remaining cells
    42cell = new Tango::Group("cell-02");
    43...

Important note: There is no particular order to create the hierarchy. However, the insertion order of the devices is conserved throughout the lifecycle of the Group and cannot be changed. That way, the Group implementation can guarantee the order in which results are returned (see below).

Keeping a reference to the root group is enough to manage the whole hierarchy (i.e. there no need to keep trace of the sub-groups or individual devices). The Group interface provides methods to retrieve a sub-group or an individual device.

Be aware that a C++ group allways gets the ownership of its children and deletes them when it is itself deleted. Therefore, never try to delete a Group (respectively a DeviceProxy) returned by a call to Tango::Group::get_group() (respectively to Tango::Group::get_device()). Use the Tango::Group::remove() method instead (see the Tango Group class API documentation for details).

We can now perform any action on any element of our gauges group. For instance, let’s ping the whole hierarchy to be sure that all devices are alive.

    1//- ping the whole hierarchy
    2if (gauges->ping() == true)
    3{
    4    std::cout << "all devices alive" << std::endl;
    5}
    6else
    7{
    8    std::cout << "at least one dead/busy/locked/... device" << std::endl;
    9}

### Enabling and disabling group members

Devices belonging to a group can be temporarily excluded from all operations performed on the group using the Group::disable and Group::enable calls.

Device name passed to the disable (enable) methods can contain wildcards (`*`). Note that only the first matching device will be disabled (enabled). The search algorithm is breadth-first search. All group elements are searched (in the insertion order) for a match before descending recursively to sub-groups. Recursive search can be disabled with the forward flag (see a section dedicated to the forwarding).

During group operations like attribute read or command calls, entries for disabled elements will be included in the result set, however they will not have any value and will be marked as disabled (GroupReply::group_element_enabled will be false).

Note that if exceptions are enabled, any attempt to access the result (e.g. via get_data()) from a disabled device will raise `Tango::DevFailed`. Otherwise an empty value will be returned.

Below is an example using the gauges group:

     1// will disable: inst-c01/vac-gauge/penning-01
     2gauges->disable("inst-c01/*/penn");
     3
     4// will disable nothing
     5const bool forwarded = true;
     6gauges->disable("inst-c01/vac-gauge/pirani-01", not forwarded);
     7
     8// will disable: inst-c01/vac-gauge/pirani-01
     9gauge_family->disable("inst-c01/vac-gauge/pirani-01");
    10
    11// will enable: inst-c01/vac-gauge/penning-01
    12gauges->enable("inst-c01/*");
    13
    14auto states = gauges->command_inout("State");
    15for (auto& state : states)
    16{
    17    if (state.group_element_enabled())
    18    {
    19        // it's safe to access the value
    20        std::cout << state.dev_name() << ": " << state.get_data() << "\n";
    21    }
    22    else
    23    {
    24        std::cout << state.dev_name() << ": is disabled\n";
    25    }
    26}

### Forward or not forward?

Since a Tango Group is a hierarchical object, any action performed on a group can be forwarded to its sub-groups. Most of the methods in the Group interface have a so-called forward option controlling this propagation. When set to false, the action is only performed on the local set of devices. Otherwise, the action is also forwarded to the sub-groups, in other words, propagated along the hierarchy. In C++ , the forward option defaults to true (thanks to the C++ default argument value). There is no such mechanism in Java and the forward option must be systematically specified.

### Executing a command

As a proxy for a collection of devices, the Tango Group provides an interface similar to the DeviceProxy’s. For the execution of a command, the Group interface contains several implementations of the command_inout method. Both synchronous and asynchronous forms are supported.

#### Obtaining command results

Command results are returned using a Tango::GroupCmdReplyList. This is nothing but a vector containing a Tango::GroupCmdReply for each device in the group. The Tango::GroupCmdReply contains the actual data (i.e. the Tango::DeviceData). By inheritance, it may also contain any error occurred during the execution of the command (in which case the data is invalid).

We previously indicated that the Tango Group implementation guarantees that the command results are returned in the order in which its elements were attached to the group. For instance, if g1 is a group containing three devices attached in the following order:

    1g1->add("my/device/01");
    2g1->add("my/device/03");
    3g1->add("my/device/02");

the results of

    1Tango::GroupCmdReplyList crl = g1->command_inout("Status");

will be organized as follows:

crl[0] contains the status of my/device/01
crl[1] contains the status of my/device/03
crl[2] contains the status of my/device/02

Things get more complicated if sub-groups are added between devices.

     1g2->add("my/device/04");
     2g2->add("my/device/05");
     3
     4
     5g4->add("my/device/08");
     6g4->add("my/device/09");
     7
     8
     9g3->add("my/device/06");
    10g3->add(g4);
    11g3->add("my/device/07");
    12
    13
    14g1->add("my/device/01");
    15g1->add(g2);
    16g1->add("my/device/03");
    17g1->add(g3);
    18g1->add("my/device/02");

The result order in the Tango::GroupCmdReplyList depends on the value of the forward option. If set to true, the results will be organized as follows:

    1Tango::GroupCmdReplyList crl = g1->command_inout("Status", true);

crl[0] contains the status of my/device/01 which belongs to g1
crl[1] contains the status of my/device/04 which belongs to g1.g2
crl[2] contains the status of my/device/05 which belongs to g1.g2
crl[3] contains the status of my/device/03 which belongs to g1
crl[4] contains the status of my/device/06 which belongs to g1.g3
crl[5] contains the status of my/device/08 which belongs to g1.g3.g4
crl[6] contains the status of my/device/09 which belongs to g1.g3.g
crl[7] contains the status of my/device/07 which belongs to g1.g3
crl[8] contains the status of my/device/02 which belongs to g1

If the forward option is set to false, the results are:

    1Tango::GroupCmdReplyList crl = g1->command_inout("Status", false);

crl[0] contains the status of my/device/01 which belongs to g
crl[1] contains the status of my/device/03 which belongs to g1
crl[2] contains the status of my/device/02 which belongs to g1

The Tango::GroupCmdReply contains some public members allowing the identification of both the device (Tango::GroupCmdReply::dev_name) and the command (Tango::GroupCmdReply::obj_name). It means that, depending of your application, you can associate a response with its source using its position in the response list or using the Tango::GroupCmdReply::dev_name member.

#### Case 1: a command, no argument

As an example, we execute the Status command on the whole hierarchy synchronously.

    1Tango::GroupCmdReplyList crl = gauges->command_inout("Status");

As a first step in the results processing, it could be interesting to check value returned by the has_failed() method of the GroupCmdReplyList. If it is set to true, it means that at least one error occurred during the execution of the command (i.e. at least one device gave error).

    1if (crl.has_failed())
    2{
    3    cout << "at least one error occurred" << endl;
    4}
    5else
    6{
    7    cout << "no error " << endl;
    8}

Now, we have to process each individual response in the list.

#### A few words on error handling and data extraction

Depending of the application and/or the developer’s programming habits, each individual error can be handle by the C++ (or Java) exception mechanism or using the dedicated has_failed() method. The GroupReply class - which is the mother class of both GroupCmdReply and GroupAttrReply - contains a static method to enable (or disable) exceptions called enable_exception(). By default, exceptions are disabled. The following example is proposed with both exceptions enable and disable.

In C++, data can be extracted directly from an individual reply. The GroupCmdReply interface contains a template operator >> allowing the extraction of any supported Tango type (in fact the actual data extraction is delegated to DeviceData::operator >>). One dedicated extract method is also provided in order to extract DevVarLongStringArray and DevVarDoubleStringArray types to std::vectors.

Error and data handling C++ example:

     1//-------------------------------------------------------
     2//- synch. group command example with exception enabled
     3//-------------------------------------------------------
     4//- enable exceptions and save current mode
     5bool last_mode = GroupReply::enable_exception(true);
     6//- process each response in the list ...
     7for (int r = 0; r < crl.size(); r++)
     8{
     9//- enter a try/catch block
    10   try
    11   {
    12//- try to extract the data from the r-th reply
    13//- suppose data contains a double
    14       double ans;
    15       crl[r] >> ans;
    16       cout << crl[r].dev_name()
    17            << "::"
    18            << crl[r].obj_name()
    19            << " returned "
    20            << ans
    21            << endl;
    22    }
    23    catch (const DevFailed& df)
    24    {
    25//- DevFailed caught while trying to extract the data from reply
    26      for (int err = 0; err < df.errors.length(); err++)
    27      {
    28           cout << "error: " << df.errors[err].desc.in() << endl;
    29      }
    30//- alternatively, one can use crl[r].get_err_stack() see below
    31    }
    32    catch (...)
    33    {
    34       cout << "unknown exception caught";
    35    }
    36}
    37//- restore last exception mode (if needed)
    38GroupReply::enable_exception(last_mode);
    39//- Clear the response list (if reused later in the code)
    40crl.reset();
    41
    42
    43//-------------------------------------------------------
    44//- synch. group command example with exception disabled
    45//-------------------------------------------------------
    46//- disable exceptions and save current mode bool
    47last_mode = GroupReply::enable_exception(false);
    48//- process each response in the list ...
    49for (int r = 0; r < crl.size(); r++)
    50{
    51//- did the r-th device give error?
    52    if (crl[r].has_failed() == true)
    53    {
    54//- printout error description
    55       cout << "an error occurred while executing "
    56            << crl[r].obj_name()
    57            << " on "
    58            << crl[r].dev_name() << endl;
    59//- dump error stack
    60       const DevErrorList& el = crl[r].get_err_stack();
    61       for (int err = 0; err < el.size(); err++)
    62       {
    63           cout << el[err].desc.in();
    64       }
    65    }
    66    else
    67    {
    68//- no error (suppose data contains a double)
    69       double ans;
    70       bool result = crl[r] >> ans;
    71       if (result == false)
    72       {
    73           cout << "could not extract double from "
    74                << crl[r].dev_name()
    75                << " reply"
    76                << endl;
    77       }
    78       else
    79       {
    80           cout << crl[r].dev_name()
    81                << "::"
    82                << crl[r].obj_name()
    83                << " returned "
    84                << ans
    85                << endl;
    86       }
    87    }
    88}
    89//- restore last exception mode (if needed)
    90GroupReply::enable_exception(last_mode);
    91//- Clear the response list (if reused later in the code)
    92crl.reset();

Now execute the same command asynchronously. C++ example:

     1//-------------------------------------------------------
     2//- asynch. group command example (C++ example)
     3//-------------------------------------------------------
     4long request_id = gauges->command_inout_asynch("Status");
     5//- do some work
     6do_some_work();
     7
     8
     9//- get results
    10crl = gauges->command_inout_reply(request_id);
    11//- process responses as previously describe in the synch. implementation
    12for (int r = 0; r < crl.size(); r++)
    13{
    14//- data processing and error handling goes here
    15//- copy/paste code from previous example
    16. . .
    17}
    18//- clear the response list (if reused later in the code)
    19crl.reset();

#### Case 2: a command, one argument

Here, we give an example in which the same input argument is applied to all devices in the group (or its sub-groups).

In C++:

    1//- the argument value
    2double d = 0.1;
    3//- insert it into the TANGO generic container for command: DeviceData
    4Tango::DeviceData dd;
    5dd << d;
    6//- execute the command: Dev_Void SetDummyFactor (Dev_Double)
    7Tango::GroupCmdReplyList crl = gauges->command_inout("SetDummyFactor", dd);

Since the SetDummyFactor command does not return any value, the individual replies (i.e. the GroupCmdReply) do not contain any data. However, we have to check their has_failed() method returned value to be sure that the command completed successfully on each device (acknowledgement). Note that in such a case, exceptions are useless since we never try to extract data from the replies.

In C++ we should have something like:

     1//- no need to process the results if no error occurred (Dev_Void command)
     2if (crl.has_failed())
     3{
     4//- at least one error occurred
     5    for (int r = 0; r < crl.size(); r++)
     6    {
     7//- handle errors here (see previous C++ examples)
     8    }
     9}
    10//- clear the response list (if reused later in the code)
    11crl.reset();

See case 1 for an example of asynchronous command.

#### Case 3: a command, several arguments

Here, we give an example in which a specific input argument is applied to each device in the hierarchy. In order to use this form of command_inout, the user must have an a priori and perfect knowledge of the devices order in the hierarchy. In such a case, command arguments are passed in an array (with one entry for each device in the hierarchy).

The C++ implementation provides a template method which accepts a std::vector of C++ type for command argument. This allows passing any kind of data using a single method.

The size of this vector must equal the number of device in the hierarchy (respectively the number of device in the group) if the forward option is set to true (respectively set to false). Otherwise, an exception is thrown.

The first item in the vector is applied to the first device in the hierarchy, the second to the second device in the hierarchy, and so on…That’s why the user must have a perfect knowledge of the devices order in the hierarchy.

Assuming that gauges are ordered by name, the SetDummyFactor command can be executed on group cell-01 (and its sub-groups) as follows:

Remember, cell-01 has the following internal structure:

     1-> gauges
     2   | -> cell-01
     3   |    |-> inst-c01/vac-gauge/strange
     4   |    |-> penning
     5   |    |   |-> inst-c01/vac-gauge/penning-01
     6   |    |   |-> inst-c01/vac-gauge/penning-02
     7   |    |   |-> ...
     8   |    |   |-> inst-c01/vac-gauge/penning-xx
     9   |    |-> pirani
    10   |        |-> inst-c01/vac-gauge/pirani-01
    11   |        |-> ...
    12   |        |-> inst-c01/vac-gauge/pirani-xx

Passing a specific argument to each device in C++:

     1//- get a reference to the target group
     2Tango::Group *g = gauges->get_group("cell-01");
     3//- get number of device in the hierarchy (starting at cell-01)
     4long n_dev = g->get_size(true);
     5//- Build argin list
     6std::vector<double> argins(n_dev);
     7//- argument for inst-c01/vac-gauge/strange
     8argins[0] = 0.0;
     9//- argument for inst-c01/vac-gauge/penning-01
    10argins[1] = 0.1;
    11//- argument for inst-c01/vac-gauge/penning-02
    12argins[2] = 0.2;
    13//- argument for remaining devices in cell-01.penning
    14. . .
    15//- argument for devices in cell-01.pirani
    16. . .
    17//- the reply list
    18Tango::GroupCmdReplyList crl;
    19//- enter a try/catch block (see below)
    20try
    21{
    22//- execute the command
    23    crl = g->command_inout("SetDummyFactor", argins, true);
    24    if (crl.has_failed())
    25    {
    26//- error handling goes here (see case 1)
    27    }
    28}
    29catch (const DevFailed& df)
    30{
    31//- see below
    32}
    33crl.reset();

If we want to execute the command locally on cell-01 (i.e. not on its sub-groups), we should write the following C++ code:

     1//- get a reference to the target group
     2Tango::Group *g = gauges->get_group("cell-01");
     3//- get number of device in the group (starting at cell-01)
     4long n_dev = g->get_size(false);
     5//- Build argin list
     6std::vector<double> argins(n_dev);
     7//- argins for inst-c01/vac-gauge/penning-01
     8argins[0] = 0.1;
     9//- argins for inst-c01/vac-gauge/penning-02
    10argins[1] = 0.2;
    11//- argins for remaining devices in cell-01.penning
    12. . .
    13//- the reply list
    14Tango::GroupCmdReplyList crl;
    15//- enter a try/catch block (see below)
    16try
    17{
    18//- execute the command
    19    crl = g->command_inout("SetDummyFactor", argins, false);
    20    if (crl.has_failed())
    21    {
    22//- error handling goes here (see case 1)
    23    }
    24}
    25catch (const DevFailed& df)
    26{
    27//- see below
    28}
    29crl.reset();

Note: if we want to execute the command locally on cell-01 (i.e. not on its sub-groups), we should write the following code:

     1//- get a reference to the target group
     2Group g = gauges.get_group("cell-01");
     3//- get pre-build arguments list for the group (starting@cell-01)
     4DeviceData[] argins = g.get_command_specific_argument_list(false);
     5//- argins for inst-c01/vac-gauge/penning-01
     6argins[0].insert(0.1);
     7//- argins for inst-c01/vac-gauge/penning-02
     8argins[1].insert(0.2);
     9//- argins for remaining devices in cell-01.penning
    10. . .
    11//- the reply list
    12GroupCmdReplyList crl;
    13//- enter a try/catch block (see below)
    14try
    15{
    16//- execute the command
    17    crl = g.command_inout("SetDummyFactor", argins, false, false);
    18    if (crl.has_failed())
    19    {
    20//- error handling goes here (see case 1)
    21    }
    22}
    23catch (DevFailed d)
    24{
    25//- see below
    26}

This form of command_inout (the one that accepts an array of value as its input argument), may throw an exception before executing the command if the number of elements in the input array does not match the number of individual devices in the group or in the hierarchy (depending on the forward option).

An asynchronous version of this method is also available. See case 1 for an example of asynchronous command.

### Reading attribute(s)

In order to read attribute(s), the Group interface contains several implementations of the read_attribute() and read_attributes() methods. Both synchronous and asynchronous forms are supported. Reading several attributes is very similar to reading a single attribute. Simply replace the std::string used for attribute name by a vector of std::string with one element for each attribute name. In case of read_attributes() call, the order of attribute value returned in the GroupAttrReplyList is all attributes for first element in the group followed by all attributes for the second group element and so on.

#### Obtaining attribute values

Attribute values are returned using a GroupAttrReplyList. This is nothing but an array containing a GroupAttrReply for each device in the group. The GroupAttrReply contains the actual data (i.e. the DeviceAttribute). By inheritance, it may also contain any error occurred during the execution of the command (in which case the data is invalid).

Here again, the Tango Group implementation guarantees that the attribute values are returned in the order in which its elements were attached to the group. See Obtaining command results for details.

The GroupAttrReply contains some public methods allowing the identification of both the device (GroupAttrReply::dev_name) and the attribute (GroupAttrReply::obj_name). It means that, depending of your application, you can associate a response with its source using its position in the response list or using the Tango::GroupAttrReply::dev_name member.

#### A few words on error handling and data extraction

Here again, depending of the application and/or the developer’s programming habits, each individual error can be handle by the C++ exception mechanism or using the dedicated has_failed() method. The GroupReply class - which is the mother class of both GroupCmdReply and GroupAttrReply - contains a static method to enable (or disable) exceptions called enable_exception(). By default, exceptions are disabled. The following example is proposed with both exceptions enable and disable.

In C++, data can be extracted directly from an individual reply. The GroupAttrReply interface contains a template operator>> allowing the extraction of any supported Tango type (in fact the actual data extraction is delegated to DeviceAttribute::operator>>).

Reading an attribute is very similar to executing a command.

Reading an attribute in C++:

     1//-----------------------------------------------------------------
     2//- synch. read "vacuum" attribute on each device in the hierarchy
     3//- with exceptions enabled - C++ example
     4//-----------------------------------------------------------------
     5//- enable exceptions and save current mode
     6bool last_mode = GroupReply::enable_exception(true);
     7//- read attribute
     8Tango::GroupAttrReplyList arl = gauges->read_attribute("vacuum");
     9//- for each response in the list ...
    10for (int r = 0; r < arl.size(); r++)
    11{
    12//- enter a try/catch block
    13   try
    14   {
    15//- try to extract the data from the r-th reply
    16//- suppose data contains a double
    17      double ans;
    18      arl[r] >> ans;
    19      cout << arl[r].dev_name()
    20           << "::"
    21           << arl[r].obj_name()
    22           << " value is "
    23           << ans << endl;
    24   }
    25   catch (const DevFailed& df)
    26   {
    27//- DevFailed caught while trying to extract the data from reply
    28      for (int err = 0; err < df.errors.length(); err++)
    29      {
    30         cout << "error: " << df.errors[err].desc.in() << endl;
    31      }
    32//- alternatively, one can use arl[r].get_err_stack() see below
    33   }
    34   catch (...)
    35   {
    36      cout << "unknown exception caught";
    37   }
    38}
    39//- restore last exception mode (if needed)
    40GroupReply::enable_exception(last_mode);
    41//- clear the reply list (if reused later in the code)
    42arl.reset();

In C++, an asynchronous version of the previous example could be:

     1//- read the attribute asynchronously
     2long request_id = gauges->read_attribute_asynch("vacuum");
     3//- do some work
     4do_some_work();
     5
     6
     7//- get results
     8Tango::GroupAttrReplyList arl = gauges->read_attribute_reply(request_id);
     9//- process replies as previously described in the synch. implementation
    10for (int r = 0; r < arl.size(); r++)
    11{
    12//- data processing and/or error handling goes here
    13...
    14}
    15//- clear the reply list (if reused later in the code)
    16arl.reset();

### Writing an attribute

The Group interface contains several implementations of the write_attribute() method. Both synchronous and asynchronous forms are supported. However, writing more than one attribute at a time is not supported.

#### Obtaining acknowledgement

Acknowledgements are returned using a GroupReplyList. This is nothing but an array containing a GroupReply for each device in the group. The GroupReply may contain any error occurred during the execution of the command. The return value of the has_failed() method indicates whether an error occurred or not. If this flag is set to true, the GroupReply::get_err_stack() method gives error details.

Here again, the Tango Group implementation guarantees that the attribute values are returned in the order in which its elements were attached to the group. See Obtaining command results for details.

The GroupReply contains some public members allowing the identification of both the device (GroupReply::dev_name) and the attribute (GroupReply::obj_name). It means that, depending of your application, you can associate a response with its source using its position in the response list or using

#### Case 1: one value for all devices

Here, we give an example in which the same attribute value is written on all devices in the group (or its sub-groups). Exceptions are supposed to be disabled.

Writing an attribute in C++:

     1//-----------------------------------------------------------------
     2//- synch. write "dummy" attribute on each device in the hierarchy
     3//-----------------------------------------------------------------
     4//- assume each device support a "dummy" writable attribute
     5//- insert the value to be written into a generic container
     6Tango::DeviceAttribute value(std::string("dummy"), 3.14159);
     7//- write the attribute
     8Tango::GroupReplyList rl = gauges->write_attribute(value);
     9//- any error?
    10if (rl.has_failed() == false)
    11{
    12    cout << "no error" << endl;
    13}
    14else
    15{
    16    cout << "at least one error occurred" << endl;
    17//- for each response in the list ...
    18    for (int r = 0; r < rl.size(); r++)
    19    {
    20//- did the r-th device give error?
    21       if (rl[r].has_failed() == true)
    22       {
    23//- printout error description
    24           cout << "an error occurred while reading "
    25                << rl[r].obj_name()
    26                << " on "
    27                << rl[r].dev_name()
    28                << endl;
    29//- dump error stack
    30           const DevErrorList& el = rl[r].get_err_stack();
    31           for (int err = 0; err < el.size(); err++)
    32           {
    33              cout << el[err].desc.in();
    34           }
    35        }
    36     }
    37}
    38//- clear the reply list (if reused later in the code)
    39rl.reset();

Here is a C++ asynchronous version:

     1//- insert the value to be written into a generic container
     2Tango::DeviceAttribute value(std::string("dummy"), 3.14159);
     3//- write the attribute asynchronously
     4long request_id = gauges.write_attribute_asynch(value);
     5//- do some work
     6do_some_work();
     7
     8
     9//- get results
    10Tango::GroupReplyList rl = gauges->write_attribute_reply(request_id);
    11//- process replies as previously describe in the synch. implementation ...

#### Case 2: a specific value per device

Here, we give an example in which a specific attribute value is applied to each device in the hierarchy. In order to use this form of write_attribute(), the user must have an a priori and perfect knowledge of the devices order in the hierarchy.

The C++ implementation provides a template method which accepts a std::vector of C++ type for command argument. This allows passing any kind of data using a single method.

The size of this vector must equal the number of device in the hierarchy (respectively the number of device in the group) if the forward option is set to true (respectively set to false). Otherwise, an exception is thrown.

The first item in the vector is applied to the first device in the group, the second to the second device in the group, and so on…That’s why the user must have a perfect knowledge of the devices order in the group.

Assuming that gauges are ordered by name, the dummy attribute can be written as follows on group cell-01 (and its sub-groups) as follows:

Remember, cell-01 has the following internal structure:

     1-> gauges
     2    | -> cell-01
     3    |     |-> inst-c01/vac-gauge/strange
     4    |     |-> penning
     5    |     |    |-> inst-c01/vac-gauge/penning-01
     6    |     |    |-> inst-c01/vac-gauge/penning-02
     7    |     |    |-> ...
     8    |     |    |-> inst-c01/vac-gauge/penning-xx
     9    |     |-> pirani
    10    |          |-> inst-c01/vac-gauge/pirani-01
    11    |          |-> ...
    12    |          |-> inst-c01/vac-gauge/pirani-xx

C++ version:

     1//- get a reference to the target group
     2Tango::Group *g = gauges->get_group("cell-01");
     3//- get number of device in the hierarchy (starting at cell-01)
     4long n_dev = g->get_size(true);
     5//- Build value list
     6std::vector<double> values(n_dev);
     7//- value for inst-c01/vac-gauge/strange
     8values[0] = 3.14159;
     9//- value for inst-c01/vac-gauge/penning-01
    10values[1] = 2 * 3.14159;
    11//- value for inst-c01/vac-gauge/penning-02
    12values[2] = 3 * 3.14159;
    13//- value for remaining devices in cell-01.penning
    14. . .
    15//- value for devices in cell-01.pirani
    16. . .
    17//- the reply list
    18Tango::GroupReplyList rl;
    19//- enter a try/catch block (see below)
    20try
    21{
    22//- write the "dummy" attribute
    23    rl = g->write_attribute("dummy", values, true);
    24    if (rl.has_failed())
    25    {
    26//- error handling (see previous cases)
    27    }
    28}
    29catch (const DevFailed& df)
    30{
    31//- see below
    32}
    33rl.reset();

Note: if we want to execute the command locally on cell-01 (i.e. not on its sub-groups), we should write the following code

     1//- get a reference to the target group
     2Tango::Group *g = gauges->get_group("cell-01");
     3//- get number of device in the group
     4long n_dev = g->get_size(false);
     5//- Build value list
     6std::vector<double> values(n_dev);
     7//- value for inst-c01/vac-gauge/penning-01
     8values[0] = 2 * 3.14159;
     9//- value for inst-c01/vac-gauge/penning-02
    10values[1] = 3 * 3.14159;
    11//- value for remaining devices in cell-01.penning
    12. . .
    13//- the reply list
    14Tango::GroupReplyList rl;
    15//- enter a try/catch block (see below)
    16try
    17{
    18//- write the "dummy" attribute
    19   rl = g->write_attribute("dummy", values, false);
    20   if (rl.has_failed())
    21   {
    22//- error handling (see previous cases)
    23   }
    24}
    25catch (const DevFailed& df)
    26{
    27//- see below
    28}
    29rl.reset();

This form of write_attribute() (the one that accepts an array of value as its input argument), may throw an exception before executing the command if the number of elements in the input array does not match the number of individual devices in the group or in the hierarchy (depending on the forward option).

An asynchronous version of this method is also available.

## Reading/Writing device pipe

Reading or writing device pipe is made possible using DeviceProxy class methods. To read a pipe, you have to use the method read_pipe(). To write a pipe, use the write_pipe() method. A method write_read_pipe() is also provided in case you need to write then read a pipe in a non-interuptible way. All these calls generate synchronous request and support only reading or writing a single pipe at a time. Those pipe related DeviceProxy class methods (read_pipe, write_pipe,…) use DevicePipe class instances. A DevicePipe instance is nothing more than a string for the pipe name and a DevicePipeBlob instance called the root blob. In a DevicePipeBlob instance, you have:

- The blob name

- One array of DataElement. Each instance of this DataElement class has:

  - A name

  - A value which can be either

    - Scalar or array of any basic Tango type

    - Another DevicePipeBlob

Therefore, this is a recursive data structure and you may have DevicePipeBlob in DevicePipeBlob. There is no limit on the depth of this recursivity even if it is not recommended to have a too large depth. The following figure summarizes DevicePipe data structure

Figure 4.1: DevicePipe data structure

Many methods to insert/extract data into/from a DevicePipe are available. In the DevicePipe class, these methods simply forward their action to the DevicePipe root blob. The same methods are available in the DevicePipeBlob in case you need to use the recursivity provided by this data structure.

### Reading a pipe

When you read a pipe, you have to extract data received from the pipe. Because data transferred through a pipe can change at any moment, two differents cases are possible:

1. The client has a prior knowledge of what should be transferred through the pipe

2. The client does not know at all what has been received through the pipe

Those two cases are detailed in the following sub-chapters.

#### Extracting data with pipe content prior knowledge

To extract data from a DevicePipe object (or from a DevicePipeBlob object), you have to use its extraction operator >>. Let’s suppose that we already know (prior knowledge) that the pipe contains 3 data elements with a Tango long, an array of double and finally an array of unsigned short. The code you need to extract these data is (Without error case treatment detailed in a next sub-chapter)

    1DevicePipe dp = mydev.read_pipe("MyPipe");
    2
    3DevLong dl;
    4vector<double> v_db;
    5DevVarUShortArray *dvush = new DevVarUShortArray();
    6
    7dp >> dl >> v_db >> dvush;
    8
    9delete dvush;

The pipe is read at line 1. Pipe (or root blob) data extracttion is at line 7. As you can see, it is just a matter of chaining extraction operator (>>) into local data (declared line 3 to 5). In this example, the transported array of double is extracted into a C++ vector while the unsigned short array is extracted in a Tango sequence data type. When you extract data into a vector, there is a unavoidable memory copy between the DevicePipe object and the vector. When you extract data in a Tango sequence data type, there is no memory copy but the extraction method consumes the memory and it is therefore caller responsability to delete the memory. This is the rule of line 9. If there is a DevicePipeBlob inside the DevicePipe, simply extract it into one instance of the DevicePipeBlob class.

You may notice that the pipe root blob data elements name are lost in the previous example. The Tango API also has a DataElement class which allows you to retrieve/set data element name. The following code is how you can extract pipe data and retrieve data element name (same pipe then previously)

    1DevicePipe dp = mydev.read_pipe("MyPipe");
    2
    3DataElement<DevLong> de_dl;
    4DataElement<vector<double> > de_v_db;
    5DataElement<DevVarUShortArray *> de_dvush(new DevVarUShortArray());
    6
    7dp >> de_dl >> de_v_db >> de_dvush;
    8
    9delete de_dvush.value;

The extraction line (number 7) is similar to the previous case but local data are instances of DataElement class. This is template class and instances are created at lines 4 to 6. Each DataElement instance has only two elements which are:

1. The data element name (a C++ string): name

2. The data element value (One instance of the template parameter): value

#### Extracting data in a generic way (without prior knowledge)

Due to the dynamicity of the data transferred through a pipe, the API alows to extract data from a pipe without any prior knowledge of its content. This is achived with methods get_data_elt_nb(), get_data_elt_type(), get_data_elt_name() and the extraction operator >>. These methods belong to the DevicePipeBlob class but they also exist on the DevicePipe class for its root blob. Here is one example of how you use them:

     1DevicePipe dp = mydev.read_pipe("MyPipe");
     2
     3size_t nb_de = dp.get_data_elt_nb();
     4for (size_t loop = 0;loop < nb_de;loop++)
     5{
     6   int data_type = dp.get_data_elt_type(loop);
     7   string de_name = dp.get_data_elt_name(loop);
     8   switch(data_type)
     9   {
    10      case DEV_LONG:
    11      {
    12          DevLong lg;
    13          dp >> lg;
    14      }
    15      break;
    16
    17      case DEVVAR_DOUBLEARRAY:
    18      {
    19          vector<double> v_db;
    20          dp >> v_db;
    21      }
    22      break;
    23      ....
    24   }
    25   ...
    26}

The number of data element in the pipe root blob is retrieve at line 3. Then a loop for each data element is coded. For each data element, its value data type and its name are retrieved at lines 6 and 7. Then, according to the data element value data type, the data are extracted using the classical extraction operator (lines 13 or 20)

#### Error management

By default, in case of error, the DevicePipe object throws different kind of exceptions according to the error kind. It is possible to disable exception throwing. If you do so, the code has to test the DevicePipe state after extraction. The possible error cases are:

- DevicePipe object is empty

- Wrong data type for extraction (For instance extraction into a double data while the DataElement contains a string)

- Wrong number of DataElement (Extraction code extract 5 data element while the pipe contains only four)

- Mix of extraction (or insertion) method kind (classical operators << or >>) and [] operator.

Methods exceptions() and reset_exceptions() of the DevicePipe and DevicePipeBlob classes allow the user to select which kind of error he is interested in. For error treatment without exceptions, methods has_failed() and state() has to be used. See reference documentation for details about these methods.

### Writing a pipe

Writing data into a DevicePipe or a DevicePipeBlob is similar to reading data from a pipe. The main method is the insertion operator <<. Let’s have a look at a first example if you want to write a pipe with a Tango long, a vector of double and finally an array of unsigned short.

     1DevicePipe dp("MyPipe");
     2
     3vector<string> de_names {"FirstDE","SecondDE","ThirdDE"};
     4db.set_data_elt_names(de_names);
     5
     6DevLong dl = 666;
     7vector<double> v_db {1.11,2.22};
     8unsigned short *array = new unsigned short [100];
     9DevVarUShortArray *dvush = create_DevVarUShortArray(array,100);
    10
    11try
    12{
    13   dp << dl << v_db << dvush;
    14   mydev.write_pipe(dp);
    15}
    16catch (DevFailed &e)
    17{
    18   cout << "DevicePipeBlob insertion failed" << endl;
    19   ....
    20}

Insertion into the DevicePipe is done at line 12 with the insert operators. The main difference with extracting data from the pipe is at line 3 and 4. When inserting data into a pipe, you need to FIRST define its number od name of data elements. In our example, the device pipe is initialized to carry three data element and the names of these data elements is defined at line 4. This is a mandatory requirement. If you don’t define data element number, exception will be thrown during the use of insertion methods. The population of the array used for the third pipe data element is not represented here.

It’s also possible to use DataElement class instances to set the pipe data element. Here is the previous example modified to use DataElement class.

     1DevicePipe dp("MyPipe");
     2
     3DataElement<DevLong> de_dl("FirstElt",666);
     4vector<double>  v_db {1.11,2.22};
     5DataElement<vector<double> > de_v_db("SecondElt,v_db");
     6
     7unsigned short *array = new unsigned short [100];
     8DevVarUShortArray *dvush = create_DevVarUShortArray(array,100);
     9DataElement<DevVarUShortArray *> de_dvush("ThirdDE",array);
    10
    11try
    12{
    13   dp << de_dl << de_v_db << de_dvush;
    14   mydev.write_pipe(dp);
    15}
    16catch (DevFailed &e)
    17{
    18   cout << "DevicePipeBlob insertion failed" << endl;
    19   ....
    20}

The population of the array used for the third pipe data element is not represented here. Finally, there is a third way to insert data into a device pipe. You have to defined number and names of the data element within the pipe (similar to first insertion method) but you are able to insert data into the data element in any order using the operator overwritten for the DevicePipe and DevicePipeBlob classes. Look at the following example:

     1DevicePipe dp("MyPipe");
     2
     3vector<string> de_names {"FirstDE","SecondDE","ThirdDE"};
     4db.set_data_elt_names(de_names);
     5
     6DevLong dl = 666;
     7vector<double> v_db = {1.11,2.22};
     8unsigned short *array = new unsigned short [100];
     9DevVarUShortArray *dvush = create_DevVarUShortArray(array,100);
    10
    11dp["SecondDE"] << v_db;
    12dp["FirstDE"] << dl;
    13dp["ThirdDE"] << dvush;

Insertion into the device pipe is now done at lines 11 to 13. The population of the array used for the third pipe data element is not represented here. Note that the data element name is case insensitive.

#### Error management

When inserting data into a DevicePipe or a DevicePipeBlob, error management is very similar to reading data from from a DevicePipe or a DevicePipeBlob. The difference is that there is one more case which could trigger one exception during the insertion. This case is

- Insertion into the DevicePipe (or DevicePipeBlob) if its data element number have not been set.

## Device locking

Starting with Tango release 7 (and device inheriting from Device_4Impl), device locking is supported. For instance, this feature could be used by an application doing a scan on a synchrotron beam line. In such a case, you want to move an actuator then read a sensor, move the actuator again, read the sensor…You don’t want the actuator to be moved by another client while the application is doing the scan. If the application doing the scan locks the actuator device, it will be sure that this device is reserved for the application doing the scan and other client will not be able to move it until the scan application un-locks this actuator.

A locked device is protected against:

- command_inout call except for device state and status requested via command and for the set of commands defined as allowed following the definition of allowed command in the Tango control access schema.

- write_attribute and write_pipe call

- write_read_attribute, write_read_attributes and write_read_pipe call

- set_attribute_config and set_pipe_config call

- polling and logging commands related to the locked device

Other clients trying to do one of these calls on a locked device will get a DevFailed exception. In case of application with locked device crashed, the lock will be automatically release after a defined interval. The API provides a set of methods for application code to lock/unlock device. These methods are:

- DeviceProxy::lock() and DeviceProxy::unlock() to lock/unlock device

- DeviceProxy::locking_status(), DeviceProxy::is_locked(), DeviceProxy::is_locked_by_me() and DeviceProxy::get_locker() to get locking information

These methods are precisely described in the API reference chapters.

## Reconnection and exception

The Tango API automatically manages re-connection between client and server in case of communication error during a network access between a client and a server. By default, when a communication error occurs, an exception is returned to the caller and the connection is internally marked as bad. On the next try to contact the device, the API will try to re-build the network connection. With the set_transparency_reconnection() method of the DeviceProxy class, it is even possible not to have any exception thrown in case of communication error. The API will try to re-build the network connection as soon as it is detected as bad. This is the default mode. See Reconnection and exception for more details on this subject.

## Thread safety

Starting with Tango 7.2, some classes of the C++ API has been made thread safe. These classes are:

- DeviceProxy

- Database

- Group

- ApiUtil

- AttributeProxy

This means that it is possible to share between threads a pointer to a DeviceProxy instance. It is safe to execute a call on this DeviceProxy instance while another thread is also doing a call to the same DeviceProxy instance. Obviously, this also means that it is possible to create thread local DeviceProxy instances and to execute method calls on these instances. Nevertheless, data local to a DeviceProxy instance like its timeout are not managed on a per thread basis. For a DeviceProxy instance shared between two threads, if thread 1 changes the instance timeout, thread 2 will also see this change.

## Compiling and linking a Tango client

Compiling and linking a Tango client is similar to compiling and linking a Tango device server. Please, refer to chapter Compiling and linking a C++ device server to get all the details.

[1]

note: the polling is not synchronized is currently not synchronized on the hour