# Presentation: 455405

## Interval of Validity ServiceIOVSvc

**ATLAS Software Week**
**May 12 2003**
**Architecture Session**

## Interval of Validity Service

- Purpose:
- associates valid time ranges with objects
- triggers updates of data, and validity ranges when object enters a new validity range
- allows use of call back functions
- Use cases:
- alignment data
- calibration objects
- detector description information
- anything which has a timed validity range associated with it

## Access Patterns

- Two types of access/usage patterns:
- pure data, held in dB, used as a data member inside a class. Only needs to have it’s contents refreshed when it enters a new validity range.
- Container class, eg GeoNode, which has no representation inside the dB, contains one or more IOV data objects from dB as data members. Needs to know when any of its constituent members enters a new validity range, at which point a callback method is triggered.
- No overlap between these patterns
- will never have an IOV data object which needs a callback
- will never have a container class which has data stored in database

## Class Example

**class myIOVClass {**
** ****public:****  virtual StatusCode CallBackFcn(int,list<string> &dbKeys);**
** ****private:****   ****const**** DataHandle<CalAlign> m_align1;****   ****const**** DataHandle<CalAlign> m_align2;**
**   ****myIOVAlg2* that;**
**};**
**myIOVClass::initialize() {****  ****  p_IOVSvc->regHandle(m_align1, dBkey1);****  p_IOVSvc->regFcn(&myIOVClass::CallBackFcn, this, ****	****	****      m_align1, dBkey1);****  p_IOVSvc->regFcn(&myIOVClass::CallBackFcn, this, **
**                   ****m_align2, dBkey2);**
**  ****p_IOVSvc->regFcn(&myIOVClass::CallBackFcn, this,**
**                   ****&myIOVClass2::OtherCallBackFcn, that);**
**}**

## Sequence Diagram

**Alg**

**Handle**

**Storegate**

**Proxy**

**IOVSvc**

**CondDB**

**NovaCnv**

**PPSvc**

- regHandle(**handle,key**)

- 

- accessData()

**T***

**DataObj*******

- reset()

- callback(**dbKey**)

**T***

- 

- regFcn(**this,&Fcn,handle,key**)

- reset()

- initialize

- execute

- async

- bindHandle(**handle**)

**IOVDbSvc**

**IOV,string**

- getData(**key**)

**DataObj*******

**PersSvc**

- updateAddress(**TA**)

- updateAddress(**TA**)

- buildIOA(**string**)

**IOA**

- setRange(**clID,key,IOV**)

- createObj(**IOA**)

- setAddress(**IOA**)

**IOA**

**IOA**

- buildIOA(**string**)

- partial **IOA**

- regProxy(**proxy**)

- bind(**handle,key**)

## Sequence

- In **Initialize()**, alg registers **DataHandle<alignData>** with the IOVSvc using **IOVSvc->regHandle(handle,key)**, using the same dBkey as is used in the dB.
- Alternatively, the algorithm registers container class (eg GeoNode) with **IOVSvc->regFcn(...)**, supplying callback fcn, DataHandle, pointer to the object, and the key as parameters.
- At first deref of the DataHandle, call is passed through to Proxy, which calls **updateAddress(TransientAddress)** on the IOVDbSvc. IOVDbSvc  talks to the CondDB to retrieve storage location of an element given a **(clID,dbKey)** pair. It gets back an IOV and a string which points to the actual location of the data from which an IOA can be built. It then calls **setRange()** on the IOVSvc, which adds the IOV to its list of registered intervals. The IOA is set in the TransientAddress, and then the DataProxy calls **createObj()** on the persistency converter for the actual data using this information, and gets back a **DataObj***. The **DataObj*** is passed back through the chain of sequences to the Algorithm, eventually being converted to a **T***.

## Sequence (cont)

- The next time the DataHandle is derefed, a **T*** is automatically returned from the Proxy.
- At the start of each event, the IOVSvc parses its list of registered entries to see if any are out of range. When it finds one, it first resets the corresponding proxy, then triggers the registered callback function. The callback function gets a list of the keys of the items which have gone out of range as a parameter.
- The next time one of the DataHandles is derefed, the initial sequence is replayed, getting back a new IOV and data.

## Callback Functions

- The parameter list of the callback functions is fixed. They must be of the form:
- For releases < 6.1.0, the function needed to be virtual. No longer necessary for gcc 3.2
- The list<string> parameter provides the list of keys of the objects which have triggered the callback.
- The macro **IOVSVC_CALLBACK_ARGS**, which provides a template for the callback function argument list, is provided in IOVSvc/IOVSvcDefs.h

**StatusCode callbackFcn(int &i, std::list<std::string> &keys);**

## Unregistered Retrieves

- It is now possible to retrieve data managed by the IOVSvc, without having to register a DataHandle with the Service.
- Only simple retrieves - no associated callback functions are called (as none have been registered!)
- Requires that the associated AddressProvider (eg IOVDbSvc) have already loaded the TransientAddress with the same ClassID and key as the requested object (done in the IAddressProvider::preLoadAddresses() method).
- Standard access patterns for the retrieve:

**const MyObj *m_obj;**
**p_condStore->retrieve(m_obj,”my_key”);**
**m_obj->DoSomething();**

## Duties of the AddressProvider

- The AddressProvider **must** pre load the TADs, and then **may** call **IOVSvc::preLoadTAD( TAD* )** to inform the IOVSvc of the existence of the TAD.
- If **IOVSvc::preLoadTAD** is not called, then the list of proxies known to the IOVSvc will not include these ones, and thus will not be listed at the start of the job. However, the first time **IOVSvc::getRange()** is called on such a proxy (eg, the first time the associated object is accessed), the IOVSvc will add the proxy to the list of proxies it manages, and continue.
- Calling **IOVSvc::preLoadTAD()** is recommended, as useful debugging information is printed out at the start of the job.

## Other Changes to IOVSvc

- IOVTime now holds times in 64 bits, and distinguishes between times that were set as (run,event) pairs, or 64 bit ints.
- Can force IOVSvc to preLoad all proxies it manages at the start of the job, instead of waiting for individual accesses to data. Use jobOption (bool) “preLoadProxies”. Can further force IOVSvc to access db for all these proxies, loading data, using jobOption (bool) “preLoadData”.
- IOVSvc provides direct access to converter (eg IOVDbSvc or IOVASCIIDbSvc), to get and set ranges, with **IOVSvc::getRangeFromDB()** and **IOVSvc::setRangeInDB(). **Uses** ****IIOVDbSvc**** **interface.

## Changes to IOVASCIIDbSvc

- To make use of unregistered retrieves, use the jobOption (vector<int>) “preLoadID” to supply the IOVASCIIDbSvc  with a list of ClassIDs to preload. All keys found in dB for those ClassIDs will be preloaded.
- Tags can now include whitespace.
- Changes made to the dB during the course of a run, via **IOVSvc::setRangeInDB(clid, key, range, tag)** or **IOVASCIIDbSvc::setRange(clid, key, range, tag)** can now be saved to disk, using the jobOption (bool) “saveChanges”.
- Run/event numbers in data files can be stored as:startRun startEvent stopRun stopEvent tag				*- or -*{[startRun,startEvent] - [stopRun,stopEvent]} tag

## Caveats

- The callback function must be virtual. This will no longer be necessary when we move to gcc 3.2 (release 6.1.0 and above).
- All DataHandles to elements that the IOVSvc will manage must be const, or you’ll get a runtime error.
- Don’t try to deref the DataHandle before the first event is loaded, eg in the initialize phase. The proxy hasn’t been filled, and you’ll get a pointer to a null object.
- Whenever you call **regFcn(...)**, you will get a warning that looks like this: ...lots of crap ... instantiated by ... instantiated by ...../../../Control/IOVSvc/IOVSvc-00-00-07/IOVSvc/CallBackID.icc:24: warning: unsigned int format, different type arg (arg 3)This is OK, and can be safely ignored. Warning is gone in 6.1.0.

## Other Stuff

- Full online documentation:
- _http://annwm.lbl.gov/~leggett/Atlas/__IOVSvc_