Logo ROOT  
Reference Guide
TRef Class Reference

Persistent Reference link to a TObject A TRef is a lightweight object pointing to any TObject. This object can be used instead of normal C++ pointers in case

  • the referenced object R and the pointer P are not written to the same file
  • P is read before R
  • R and P are written to different Tree branches

When a top level object (eg Event *event) is a tree/graph of many objects, the normal ROOT Streaming mechanism ensures that only one copy of each object in the tree/graph is written to the output buffer to avoid circular dependencies.

However if the object event is split into several files or into several branches of one or more Trees, normal C++ pointers cannot be used because each I/O operation will write the referenced objects.

When a TRef is used to point to a TObject *robj, for example in a class with

TRef fRef;

one can do:

fRef = robj; //to set the pointer

This TRef and robj can be written with two different I/O calls in the same or different files, in the same or different branches of a Tree.

If the TRef is read and the referenced object has not yet been read, the TRef will return a null pointer. As soon as the referenced object will be read, the TRef will point to it. If the referenced object is contained in a TTree it can be auto-loaded using the TBranchRef mechanism, which is set up by simply calling TTree::BranchRef().

TRef also supports the complex situation where a TFile is updated multiple times on the same machine or a different machine.

How does it work

A TRef is itself a TObject with an additional transient pointer fPID. When the statement fRef = robj is executed, the following actions happen:

  • The pointer fPID is set to the current TProcessID.
  • The current ObjectNumber (see below) is incremented by one.
  • robj::fUniqueID is set to ObjectNumber.
  • In the fPID object, the element fObjects[ObjectNumber] is set to robj
  • ref::fUniqueID is also set to ObjectNumber.

After having set fRef, one can immediately return the value of robj using fRef.GetObject(). This function returns directly fObjects[fUniqueID] from the fPID object.

When the TRef is written, the process id number pidf of fPID is written in addition to the TObject part of TRef (fBits,fUniqueID).

When the TRef is read, its pointer fPID is set to the value stored in the TObjArray of TFile::fProcessIDs (fProcessIDs[pidf]). The pidf is stored as a UShort_t limiting a file to 65535 distinct ProcessID objects.

The pidf is stored in the bits 24->31 of the fUniqueID of the TRef. This implies that the number of TRefs in a single ProcessID should not exceed 2**24 = 16777216. For pidf greater than 254, the value 0xff is stored in those bits and we use the table TProcessID::fgObjPIDs which links the referenced object's address to its ProcessID.

See section "ObjectNumber" below for a recipe to minimize the object count. If the object-number exceeds this limit, it could be the sign that:

  • The object count is never reset (see below)
  • TRef is misused.

When a referenced object robj is written, TObject::Streamer writes in addition to the standard (fBits,fUniqueID) the pidf. When this robj is read by TObject::Streamer, the pidf is read. At this point, robj is entered into the table of objects of the TProcessID corresponding to pidf.

WARNING1:

If MyClass is the class of the referenced object, The TObject part of MyClass must be Streamed. One should not call MyClass::Class()->IgnoreTObjectStreamer()

WARNING2:

A TRef cannot point to another TRef.

ObjectNumber

When an object is referenced (see TRef assignment operator or TRefArray::Add) a unique identifier is computed and stored in both the fUniqueID of the referenced and referencing object. This uniqueID is computed by incrementing by one the static global in TProcessID::fgNumber. fUniqueID is some sort of serial object number in the current session. One can retrieve at any time the current value of fgNumber by calling the static function TProcessID::GetObjectCount or set this number via TProcessID::SetObjectCount.

To avoid a growing table of fObjects in TProcessID, in case, for example, one processes many events in a loop, it might be necessary to reset the ObjectNumber at the end of processing of one event. See an example in $ROOTSYS/test/Event.cxx (look at function Build).

The value of ObjectNumber (say saveNumber=TProcessID::GetObjectCount()) may be saved at the beginning of one event and reset to this original value at the end of the event via TProcessID::SetObjectCount(saveNumber). These actions may be stacked.

Action on Demand

The normal behaviour of a TRef has been described above. In addition, TRef supports also "Actions on Demand". It may happen that the object referenced is not yet in memory, on a separate file or not yet computed. In this case TRef is able to automatically execute an action:

  • call to a compiled function (static function of member function)
  • call to an interpreted function
  • execution of a C++ script

How to select this option? In the definition of the TRef data member in the original class, do:

TRef fRef; //EXEC:execName. points to something

When the special keyword "EXEC:" is found in the comment field of the member, the next string is assumed to be the name of a TExec object. When a file is connected, the dictionary of the classes on the file is read in memory (see TFile::ReadStreamerInfo). When the TStreamerElement object is read, a TExec object is automatically created with the name specified after the keyword "EXEC:" in case a TExec with a same name does not already exist.

The action to be executed via this TExec can be specified with:

  • a call to the TExec constructor, if the constructor is called before opening the file.
  • a call to TExec::SetAction at any time. One can compute a pointer to an existing TExec with a name with:
    TExec *myExec = gROOT->GetExec(execName);
    myExec->SetAction(actionCommand);
     where actionCommand is a string containing a C++ instruction. Examples:
    
    myExec->SetAction("LoadHits()");
    myExec->SetAction(".x script.C");

When a TRef is dereferenced via TRef::GetObject, its TExec will be automatically executed. In the function/script being executed, one or more of the following actions can be executed:

  • load a file containing the referenced object. This function typically looks in the file catalog (GRID).
  • compute a pointer to the referenced object and communicate this pointer back to the calling function TRef::GetObject via:
    When the TExec is called, it has access to the dereferencing TRef
    by calling GetStaticObject() (TRef::GetObject() sets fgObject to "this"
    before the call to TExec). This can be useful for accessing the TRef's
    fUniqueID.
    

As soon as an object is returned to GetObject, the fUniqueID of the TRef is set to the fUniqueID of the referenced object. At the next call to GetObject, the pointer stored in fPid:fObjects[fUniqueID] will be returned directly.

An example of action on demand is shown in $ROOTSYS/test/Event.h with the member:

TRef fWebHistogram; //EXEC:GetWebHistogram

When calling fWebHistogram.GetObject(), the function GetObject will automatically invoke a script GetWebHistogram.C via the interpreter.

An example of a GetWebHistogram.C script is shown below

void GetWebHistogram() {
TFile *f= TFile::Open("http://root.cern.ch/files/pippa.root");
f->cd("DM/CJ");
TH1 *h6 = (TH1*)gDirectory->Get("h6");
h6->SetDirectory(0);
delete f;
}

In the above example, a call to fWebHistogram.GetObject() executes the script with the function GetWebHistogram. This script connects a file with histograms: pippa.root on the ROOT Web site and returns the object h6 to TRef::GetObject.

Note that if the definition of the TRef fWebHistogram had been:

TRef fWebHistogram; //EXEC:GetWebHistogram()

then, the compiled or interpreted function GetWebHistogram() would have been called instead of the C++ script GetWebHistogram.C

Special case of a TRef pointing to an object with a TUUID

If the referenced object has a TUUID, its bit kHasUUID has been set. This case is detected by the TRef assignment operator. (For example, TFile and TDirectory have a TUUID) The TRef fPID points directly to the single object TProcessUUID (deriving from TProcessID) and managing the list of TUUIDs for a process. The TRef kHasUUID bit is set and its fUniqueID is set to the fUniqueID of the referenced object.

When the TRef is streamed to a buffer, the corresponding TUUID is also streamed with the TRef. When a TRef is read from a buffer, the corresponding TUUID is also read and entered into the global list of TUUIDs (if not already there). The TRef fUniqueID is set to the UUIDNumber. see TProcessUUID for more details.

Array of TRef

The special class TRefArray should be used to store multiple references. A TRefArray has one single pointer fPID for all objects in the array. It has a dynamic compact table of fUniqueIDs. Use a TRefArray rather then a collection of TRefs if all TRefs stem from the same process.

Example:

Suppose a TObjArray *mytracks containing a list of Track objects Suppose a TRefArray *pions containing pointers to the pion tracks in mytracks. This list is created with statements like: pions->Add(track); Suppose a TRefArray *muons containing pointers to the muon tracks in mytracks. The 3 arrays mytracks,pions and muons may be written separately.

Definition at line 32 of file TRef.h.

Public Member Functions

 TRef ()
 
 TRef (const TRef &ref)
 TRef copy ctor. More...
 
 TRef (TObject *obj)
 Create a ref to obj. More...
 
virtual ~TRef ()
 
TObjectGetObject () const
 Return a pointer to the referenced object. More...
 
TProcessIDGetPID () const
 
Bool_t IsValid () const
 
TRefoperator= (const TRef &ref)
 TRef assignment operator. More...
 
void operator= (TObject *obj)
 Assign object to reference. More...
 
virtual void SetAction (const char *name)
 Store the exec number (in the ROOT list of Execs) into the fBits of this TRef. More...
 
virtual void SetAction (TObject *parent)
 Find the action to be executed in the dictionary of the parent class and store the corresponding exec number into fBits. More...
 
- Public Member Functions inherited from TObject
 TObject ()
 TObject constructor. More...
 
 TObject (const TObject &object)
 TObject copy ctor. More...
 
virtual ~TObject ()
 TObject destructor. More...
 
void AbstractMethod (const char *method) const
 Use this method to implement an "abstract" method that you don't want to leave purely abstract. More...
 
virtual void AppendPad (Option_t *option="")
 Append graphics object to current pad. More...
 
virtual void Browse (TBrowser *b)
 Browse object. May be overridden for another default action. More...
 
ULong_t CheckedHash ()
 Check and record whether this class has a consistent Hash/RecursiveRemove setup (*) and then return the regular Hash value for this object. More...
 
virtual const char * ClassName () const
 Returns name of class to which the object belongs. More...
 
virtual void Clear (Option_t *="")
 
virtual TObjectClone (const char *newname="") const
 Make a clone of an object using the Streamer facility. More...
 
virtual Int_t Compare (const TObject *obj) const
 Compare abstract method. More...
 
virtual void Copy (TObject &object) const
 Copy this to obj. More...
 
virtual void Delete (Option_t *option="")
 Delete this object. More...
 
virtual Int_t DistancetoPrimitive (Int_t px, Int_t py)
 Computes distance from point (px,py) to the object. More...
 
virtual void Draw (Option_t *option="")
 Default Draw method for all objects. More...
 
virtual void DrawClass () const
 Draw class inheritance tree of the class to which this object belongs. More...
 
virtual TObjectDrawClone (Option_t *option="") const
 Draw a clone of this object in the current selected pad for instance with: gROOT->SetSelectedPad(gPad). More...
 
virtual void Dump () const
 Dump contents of object on stdout. More...
 
virtual void Error (const char *method, const char *msgfmt,...) const
 Issue error message. More...
 
virtual void Execute (const char *method, const char *params, Int_t *error=0)
 Execute method on this object with the given parameter string, e.g. More...
 
virtual void Execute (TMethod *method, TObjArray *params, Int_t *error=0)
 Execute method on this object with parameters stored in the TObjArray. More...
 
virtual void ExecuteEvent (Int_t event, Int_t px, Int_t py)
 Execute action corresponding to an event at (px,py). More...
 
virtual void Fatal (const char *method, const char *msgfmt,...) const
 Issue fatal error message. More...
 
virtual TObjectFindObject (const char *name) const
 Must be redefined in derived classes. More...
 
virtual TObjectFindObject (const TObject *obj) const
 Must be redefined in derived classes. More...
 
virtual Option_tGetDrawOption () const
 Get option used by the graphics system to draw this object. More...
 
virtual const char * GetIconName () const
 Returns mime type name of object. More...
 
virtual const char * GetName () const
 Returns name of object. More...
 
virtual char * GetObjectInfo (Int_t px, Int_t py) const
 Returns string containing info about the object at position (px,py). More...
 
virtual Option_tGetOption () const
 
virtual const char * GetTitle () const
 Returns title of object. More...
 
virtual UInt_t GetUniqueID () const
 Return the unique object id. More...
 
virtual Bool_t HandleTimer (TTimer *timer)
 Execute action in response of a timer timing out. More...
 
virtual ULong_t Hash () const
 Return hash value for this object. More...
 
Bool_t HasInconsistentHash () const
 Return true is the type of this object is known to have an inconsistent setup for Hash and RecursiveRemove (i.e. More...
 
virtual void Info (const char *method, const char *msgfmt,...) const
 Issue info message. More...
 
virtual Bool_t InheritsFrom (const char *classname) const
 Returns kTRUE if object inherits from class "classname". More...
 
virtual Bool_t InheritsFrom (const TClass *cl) const
 Returns kTRUE if object inherits from TClass cl. More...
 
virtual void Inspect () const
 Dump contents of this object in a graphics canvas. More...
 
void InvertBit (UInt_t f)
 
virtual Bool_t IsEqual (const TObject *obj) const
 Default equal comparison (objects are equal if they have the same address in memory). More...
 
virtual Bool_t IsFolder () const
 Returns kTRUE in case object contains browsable objects (like containers or lists of other objects). More...
 
R__ALWAYS_INLINE Bool_t IsOnHeap () const
 
virtual Bool_t IsSortable () const
 
R__ALWAYS_INLINE Bool_t IsZombie () const
 
virtual void ls (Option_t *option="") const
 The ls function lists the contents of a class on stdout. More...
 
void MayNotUse (const char *method) const
 Use this method to signal that a method (defined in a base class) may not be called in a derived class (in principle against good design since a child class should not provide less functionality than its parent, however, sometimes it is necessary). More...
 
virtual Bool_t Notify ()
 This method must be overridden to handle object notification. More...
 
void Obsolete (const char *method, const char *asOfVers, const char *removedFromVers) const
 Use this method to declare a method obsolete. More...
 
void operator delete (void *ptr)
 Operator delete. More...
 
void operator delete[] (void *ptr)
 Operator delete []. More...
 
voidoperator new (size_t sz)
 
voidoperator new (size_t sz, void *vp)
 
voidoperator new[] (size_t sz)
 
voidoperator new[] (size_t sz, void *vp)
 
TObjectoperator= (const TObject &rhs)
 TObject assignment operator. More...
 
virtual void Paint (Option_t *option="")
 This method must be overridden if a class wants to paint itself. More...
 
virtual void Pop ()
 Pop on object drawn in a pad to the top of the display list. More...
 
virtual void Print (Option_t *option="") const
 This method must be overridden when a class wants to print itself. More...
 
virtual Int_t Read (const char *name)
 Read contents of object with specified name from the current directory. More...
 
virtual void RecursiveRemove (TObject *obj)
 Recursively remove this object from a list. More...
 
void ResetBit (UInt_t f)
 
virtual void SaveAs (const char *filename="", Option_t *option="") const
 Save this object in the file specified by filename. More...
 
virtual void SavePrimitive (std::ostream &out, Option_t *option="")
 Save a primitive as a C++ statement(s) on output stream "out". More...
 
void SetBit (UInt_t f)
 
void SetBit (UInt_t f, Bool_t set)
 Set or unset the user status bits as specified in f. More...
 
virtual void SetDrawOption (Option_t *option="")
 Set drawing option for object. More...
 
virtual void SetUniqueID (UInt_t uid)
 Set the unique object id. More...
 
virtual void SysError (const char *method, const char *msgfmt,...) const
 Issue system error message. More...
 
R__ALWAYS_INLINE Bool_t TestBit (UInt_t f) const
 
Int_t TestBits (UInt_t f) const
 
virtual void UseCurrentStyle ()
 Set current style settings in this object This function is called when either TCanvas::UseCurrentStyle or TROOT::ForceStyle have been invoked. More...
 
virtual void Warning (const char *method, const char *msgfmt,...) const
 Issue warning message. More...
 
virtual Int_t Write (const char *name=0, Int_t option=0, Int_t bufsize=0)
 Write this object to the current directory. More...
 
virtual Int_t Write (const char *name=0, Int_t option=0, Int_t bufsize=0) const
 Write this object to the current directory. More...
 

Static Public Member Functions

static Int_t AddExec (const char *name)
 If Exec with name does not exist in the list of Execs, it is created. More...
 
static TObjArrayGetListOfExecs ()
 Return a pointer to the static TObjArray holding the list of Execs. More...
 
static TObjectGetStaticObject ()
 Returns the static object. More...
 
static void SetObject (TObject *obj)
 static Obsolete function kept for back compatibility. More...
 
static void SetStaticObject (TObject *obj)
 Static function to set the object found on the Action on Demand function. More...
 
- Static Public Member Functions inherited from TObject
static Long_t GetDtorOnly ()
 Return destructor only flag. More...
 
static Bool_t GetObjectStat ()
 Get status of object stat flag. More...
 
static void SetDtorOnly (void *obj)
 Set destructor only flag. More...
 
static void SetObjectStat (Bool_t stat)
 Turn on/off tracking of objects in the TObjectTable. More...
 

Protected Attributes

TProcessIDfPID
 

Static Protected Attributes

static TObjArrayfgExecs = nullptr
 Pointer to ProcessID when TRef was written. More...
 
static TObjectfgObject = nullptr
 

Friends

Bool_t operator!= (const TRef &r1, const TRef &r2)
 Return kTRUE if r1 and r2 do not point to the same object. More...
 
Bool_t operator== (const TRef &r1, const TRef &r2)
 Return kTRUE if r1 and r2 point to the same object. More...
 

Additional Inherited Members

- Public Types inherited from TObject
enum  {
  kIsOnHeap = 0x01000000, kNotDeleted = 0x02000000, kZombie = 0x04000000, kInconsistent = 0x08000000,
  kBitMask = 0x00ffffff
}
 
enum  { kSingleKey = BIT(0), kOverwrite = BIT(1), kWriteDelete = BIT(2) }
 
enum  EDeprecatedStatusBits { kObjInCanvas = BIT(3) }
 
enum  EStatusBits {
  kCanDelete = BIT(0), kMustCleanup = BIT(3), kIsReferenced = BIT(4), kHasUUID = BIT(5),
  kCannotPick = BIT(6), kNoContextMenu = BIT(8), kInvalidObject = BIT(13)
}
 
- Protected Member Functions inherited from TObject
virtual void DoError (int level, const char *location, const char *fmt, va_list va) const
 Interface to ErrorHandler (protected). More...
 
void MakeZombie ()
 

#include <TRef.h>

Inheritance diagram for TRef:
[legend]

Constructor & Destructor Documentation

◆ TRef() [1/3]

TRef::TRef ( )
inline

Definition at line 42 of file TRef.h.

◆ TRef() [2/3]

TRef::TRef ( TObject obj)

Create a ref to obj.

Definition at line 262 of file TRef.cxx.

◆ TRef() [3/3]

TRef::TRef ( const TRef ref)

TRef copy ctor.

Definition at line 270 of file TRef.cxx.

◆ ~TRef()

virtual TRef::~TRef ( )
inlinevirtual

Definition at line 47 of file TRef.h.

Member Function Documentation

◆ AddExec()

Int_t TRef::AddExec ( const char *  name)
static

If Exec with name does not exist in the list of Execs, it is created.

returns the index of the Exec in the list.

Definition at line 339 of file TRef.cxx.

◆ GetListOfExecs()

TObjArray * TRef::GetListOfExecs ( )
static

Return a pointer to the static TObjArray holding the list of Execs.

Definition at line 359 of file TRef.cxx.

◆ GetObject()

TObject * TRef::GetObject ( ) const

Return a pointer to the referenced object.

Definition at line 377 of file TRef.cxx.

◆ GetPID()

TProcessID* TRef::GetPID ( ) const
inline

Definition at line 50 of file TRef.h.

◆ GetStaticObject()

TObject * TRef::GetStaticObject ( )
static

Returns the static object.

Definition at line 458 of file TRef.cxx.

◆ IsValid()

Bool_t TRef::IsValid ( ) const
inline

Definition at line 51 of file TRef.h.

◆ operator=() [1/2]

TRef & TRef::operator= ( const TRef ref)

TRef assignment operator.

Definition at line 307 of file TRef.cxx.

◆ operator=() [2/2]

void TRef::operator= ( TObject obj)

Assign object to reference.

Definition at line 278 of file TRef.cxx.

◆ SetAction() [1/2]

void TRef::SetAction ( const char *  name)
virtual

Store the exec number (in the ROOT list of Execs) into the fBits of this TRef.

Definition at line 429 of file TRef.cxx.

◆ SetAction() [2/2]

void TRef::SetAction ( TObject parent)
virtual

Find the action to be executed in the dictionary of the parent class and store the corresponding exec number into fBits.

This function searches a data member in the class of parent with an offset corresponding to this. If a comment "TEXEC:" is found in the comment field of the data member, the function stores the exec identifier of the exec statement following this keyword.

Definition at line 449 of file TRef.cxx.

◆ SetObject()

void TRef::SetObject ( TObject obj)
static

static Obsolete function kept for back compatibility.

In the near future will print a Warning, then will be deleted.

Definition at line 466 of file TRef.cxx.

◆ SetStaticObject()

void TRef::SetStaticObject ( TObject obj)
static

Static function to set the object found on the Action on Demand function.

This function may be called by the user in the function called when a "EXEC:" keyword is specified in the data member field of the TRef. The function can get access to the dereferencing TRef (i.e. this)using the static function GetStaticObject().

Definition at line 478 of file TRef.cxx.

Friends And Related Function Documentation

◆ operator!=

Bool_t operator!= ( const TRef r1,
const TRef r2 
)
friend

Return kTRUE if r1 and r2 do not point to the same object.

Definition at line 329 of file TRef.cxx.

◆ operator==

Bool_t operator== ( const TRef r1,
const TRef r2 
)
friend

Return kTRUE if r1 and r2 point to the same object.

Definition at line 320 of file TRef.cxx.

Member Data Documentation

◆ fgExecs

TObjArray * TRef::fgExecs = nullptr
staticprotected

Pointer to ProcessID when TRef was written.

Definition at line 37 of file TRef.h.

◆ fgObject

TObject * TRef::fgObject = nullptr
staticprotected

Definition at line 38 of file TRef.h.

◆ fPID

TProcessID* TRef::fPID
protected

Definition at line 35 of file TRef.h.


The documentation for this class was generated from the following files:
f
#define f(i)
Definition: RSha256.hxx:122
TFile::Open
static TFile * Open(const char *name, Option_t *option="", const char *ftitle="", Int_t compress=ROOT::RCompressionSetting::EDefaults::kUseCompiledDefault, Int_t netopt=0)
Create / open a file.
Definition: TFile.cxx:3946
TExec
Definition: TExec.h:28
gDirectory
#define gDirectory
Definition: TDirectory.h:236
TH1::SetDirectory
virtual void SetDirectory(TDirectory *dir)
By default when an histogram is created, it is added to the list of histogram objects in the current ...
Definition: TH1.cxx:8392
TRef::SetStaticObject
static void SetStaticObject(TObject *obj)
Static function to set the object found on the Action on Demand function.
Definition: TRef.cxx:478
TFile
Definition: TFile.h:54
TExec::SetAction
virtual void SetAction(const char *action)
Definition: TExec.h:45
TH1
Definition: TH1.h:57
TRef
Definition: TRef.h:32
gROOT
#define gROOT
Definition: TROOT.h:406