SLAC PEP-II
BABAR
SLAC<->RAL
Babar logo
Workbook HEPIC Databases PDG HEP preprints
Organization Detector Computing Physics Documentation
Personnel Glossary Sitemap Search Hypernews
Unwrap page!
Wkbk. Search
Wkbk. Sitemap
Introduction
Non SLAC
HOWTO's
Introduction
Logging In
QuickTour
Detector
Info Resources
Software Infrastructure
CM2 Introduction
Unix
OO
SRT
Objectivity
Event Store
Framework
Beta
Modifying Code
Writing and Editing
Compiling
Debugging
Analysis
Framework II
Analysis
Find Data
Batch Processing
PAW
PAW II
ROOT I
ROOT II
ROOT III
Advanced Infrastructure
New Releases
Workdir
Main Packages
Event Displays
Gen/Sim/Reco
Contributing Software
SRT and CVS
Coding
Advanced Topics
Make CM2 Ntuples
New Packages
New Packages 2
Persistent Classes
Java
Site Installation
Check this page for HTML 4.01 Transitional compliance with the
W3C Validator
(More checks...)

Workbook for BaBar Offline Users - Writing Classes for Persistent Objects

Designing classes that work properly in the database.

Contents


Introduction

Persistent classes are those classes used to write data to a persistent system, e.g. to disk. Classes exist to write data from online data acquisition and reconstruction to the various levels of the BaBar event store, as well as detector conditions and alignment information which is written to the BaBar Conditions Database.

Who Should Write Persistent Classes

Persistent classes refer to objects that are stored in the BaBar Database. Errors in the creation of these classes can mess up the database and cause many delays for other users. Therefore writers of persistent classes should remain in contact with database experts and take care to adhere to BaBar coding guidelines.

General Guidelines for Designing Persistent Classes

Data is stored in the BaBar object-oriented databases in the form of persistent objects. The data is first read in as a transient object (the usual type of object in a C++ program, which lives only as long as the code that created it is being executed). The programmer then provides classes that create persistent-capable objects from the transient objects. Objects are stored to, and retrieved from, the database by proxies. These are also provided by the programmer, although in many applications there exists code provided by the expert groups (e.g. database group) for common use.

In general, for a package, Packagename, which creates transient objects, there will exist another package, PackagenameP which contains the information to create, store and retrieve the corresponding persistent objects.

You should only write persistent classes for objects which are to be stored in the database, do not use the same syntax for transient objects.

You should test your persistent classes by setting up your own developer federation and consult with an expert before writing persistent data to the BaBar databases.

Database code is written in ddl (database description language) which is similar to C++. However, ddl provides a more restrictive framework from which to create persistent objects, and there is no exact mapping between transient objects and their persistent-capable counterparts.

One restriction which must be borne in mind when writing persistent classes is that the database cannot store objects containing pointers. This means that, for example, arrays of arrays stored using pointers cannot be trivially stored in the database.

To get started writing persistent classes, the best teacher is pre-existing code. Look in cvsweb for packages in which there is a packaged called Packagename with a matching package called PackagenameP. For example, the SvtPidCalib code which stores calibration data in the Conditions Database.

To retrieve persistent data, you must create a proxy and register it with the database. You then use the proxy to retrieve persistent data from the database and the persistent data held by the proxy is read into transient objects and then manipulated in your analysis


Rules for Writing Persistent Classes

When designing persistent classes, a number of general software design strategeies should be adhered to. These rules are generally applicable for persistent programming. The design strageties and coding rules are summarized below (information from BAD508, section on writing persistent classes for the mini database):
  • A single transient reconstruction object should be persisted only once
  • All transient objects of the same class must be stored in a single. (composite) persistent object per event, to minimize per-object persistent overhead.
  • Data sotred in embedded classes should be packed to occupy only as many bits as required.
    • Boolean data should be stored as a single bit.
    • Integer data should only use as many bits as required by their range
    • Float data should be packed and stored as integers. The Least Significant Bit should be defined to correspond to roughtly 1% of the intrinsic detector resolution of the quantity being stored.
    • Packed integer and float values should use physically reasonable ranges, not 'worst possible' ranges. Values beyong the physically reasonable range should be appropriately truncated.
    • Float data with an extreme natural range should be packed logarithmically.
    • Float data should be packed using the standard packers defined in the CommonUtils package.
  • When the packed size of a piece of information is smaller than a standard type (char, short, or long), several pieces of information should be combined (bitwise OR) into a standard type data member.
  • Data members of embedded classes should be aligned to the size of the largest-size data member. This avoids compiler-generated padding when building arrays of embedded classes.
  • Persistent classes should have long-aligned data members.
  • Embedded and persistent classes should use ODMG (platform-independent) types to define their fundamental data members.
  • Embedded classes should not have any virtual functions, to avoid the persistent overhead of storing and retrieving virtual tables.
  • Variable Arrays (ooVArrays) used in persistent classes must be sized only once, either on initialization, or in the obdy of the constructor of the class which owns them, to avoid creating persistent memory fragments. Of a class contains more than one ooVArray, they should be sized in the same order as they are declared in the class definition.

How to add new code to the BaBar Repository

New packages for persistent classes (or new classes within packages) can be added to the BaBar framework in the same way as new analysis packages. However, it is the duty of the package/class coordinator to carefully ensure that the new code will not damage the BaBar database which could lead to significant delays to users. As such, new code should be carefully checked with as recent a release as possible, and in a private federation before being commited to the BaBar code. To add new classes to existing packages, following the instructions in the WorkBook Chapter SRT and CVS Background for Software Contributors. To add entire new classes, carefully follow the instructions in the WorkBook Chapter New Packages: Getting your package into CVS.
General Related Documents:

Back to Workbook Front Page

Authors:
Joseph Perl
Jenny Williams

Last modification: 7 May 2003
Last significant update: 7 May 2003