General changes
The new OH is much more efficient in histogram publishing and receiving
due to the changes in the underlying IS package. In
addition to that there are some changes in both user's and developer's
OH APIs, which make some additional performance gain and simplify the
public API. These notes just mention the most important changes in the
OH package. For more detailed information please refer to the OH User's
and Developer's
guides.
Changes in API
Changes in the user's public API
- OHRootReceiver class has been changed. This class has now two
virtual methods instead of six as before. The first one is used to
receive the TH1, TH2 and TH3 histograms and the second one is used to
receive vectors of such histograms. These functions are defined
in the following way:
virtual void receive( OHRootHistogram & hh ) = 0;
virtual void receive( std::vector<OHRootHistogram*> & set ) = 0;
Note that these functions are defined
as pure virtual, so any user defined receiver class must implement both
of them. If one does not want to use one of those functions he can
provide an empty implementation. Both functions use the OHRootHistogram
class, which is defined in the following way:
struct OHRootHistogram
{
//! ROOT histogram
std::auto_ptr<TH1> histogram;
//! time of the last update
OWLTime time;
//! Histogram Annotations
std::vector< std::pair< std::string,std::string > > annotations;
}
The objects of this class are non copyable. The histogram attribute of
this class has the std::auto_ptr type. This has been done for making
user code less error prone concerning memory allocation. There are two
simple rules for using the object of the OHRootHistogram type:
- If user wants to keep the histogram after returning from the
OHRootReceiver::receive function, he must call the release method of the std::auto_ptr
class and store somewhere the pointer to the TH1 type, which is
returned
by this call. From now on the user will be responsible to free the
histogram when it is necessary and the OHRootHistogram::histogram
attribute will no more contain a valid histogram.
- If user want to use the histogram in the scope of the
OHRootReceiver::receive function only, then he can use the get function of the std::auto_ptr
class as many times as he need. This function returns the pointer to
the object of the TH1 class, which is kept by the
OHRootHistogram::histogram attribute. The histogram will be
automatically destroyed by exiting from the OHRootReceiver::receive
function.
The OHRootHistogram::histogram
attribute is polymorphic. Despite the fact that it is defined as of
std::auto_ptr<TH1> type, it can represent also 2 or 3
dimensional histograms because the TH2 class inherits the TH1 and TH3
class inherits the TH2. Using ROOT API one can always find out the
actual histogram type. For example this can be done in the following
way:
void receive( OHRootHistogram & hh )
{
if ( hh.histogram.get()->IsA( )->InheritsFrom( TH3::Class( ) ) ) {
TH3* histo = static_cast<TH3*>( hh.histogram.get() );
...
} else if ( hh.histogram.get()->IsA( )->InheritsFrom( TH2::Class( ) ) ) {
TH2* histo = static_cast<TH2*>( hh.histogram.get() );
...
} else {
TH1* histo = hh.histogram.get();
...
}
}
or alternatively:
void receive( OHRootHistogram & hh )
{
switch ( hh.histogram.get()->GetDimension() ) {
case 1:
TH1* histo = hh.histogram.get();
...
case 2:
TH2* histo = static_cast<TH2*>( hh.histogram.get() );
...
case 3:
TH3* histo = static_cast<TH3*>( hh.histogram.get() );
...
}
}
- New static function, called getRootHistogram, has been added to
the OHRootReceiver class. This function can be used to read a
particular histogram from the OH repository. It is much more efficient
then using the OHHistogramIterator for doing this operation.
- OHRawProvider class has been changed in order to simplify it's
usage. Template parameters have been moved from the OHRawProvider class
to it's functions. This allows to use the same provider object for
publishing histograms with different bin types and also eliminate the
need of explicitly specifying types of the bins, errors and axis for
the publishing histogram, because the type will be deducted by C++
compiler. For an example see the raw_provider.cxx
file.
Changes in the developer's API
The OHHistogramData class has been
changed significantly. Now it is defined
as template class, in which template parameter defines the type of the
histogram
bins. It has been done to gain the memory and network bandwidth for
histograms,
which do not need to have double bins type. This class is used as
interface for implementing system specific histogram publishing and
receiving APIs. The
OHRootProvider.h,
OHRootProvider.i
and
OHRootProvider.cxx
files can be used as an example of how the ROOT histogram publisher
class has been implemented using the new OHHistogramData class.
To be provided
Up-to-date user's and developer's guides.