ROOT » IO » IO » TKey

class TKey: public TNamed


The TKey class includes functions to book space in a file,
to create I/O buffers, to fill these buffers,
to compress/uncompress data buffers.

Before saving (making persistent) an object in a file, a key must
be created. The key structure contains all the information to
uniquely identify a persistent object in a file.
fNbytes    = Number of bytes for the compressed object+key
fObjlen    = Length of uncompressed object
fDatime    = Date/Time when the object was written
fKeylen    = Number of bytes for the key structure
fCycle     = Cycle number of the object
fSeekKey   = Address of the object on file (points to fNbytes)
This is a redundant information used to cross-check
the data base integrity.
fSeekPdir  = Pointer to the directory supporting this object
fClassName = Object class name
fName      = Name of the object
fTitle     = Title of the object

In the 16 highest bits of fSeekPdir is encoded a pid offset.  This
offset is to be added to the pid index stored in the TRef object
and the referenced TObject.

The TKey class is used by ROOT to:
- to write an object in the current directory
- to write a new ntuple buffer

The structure of a file is shown in TFile::TFile.
The structure of a directory is shown in TDirectoryFile ctor.
The TKey class is used by the TBasket class.
See also TTree.


Function Members (Methods)

public:
virtual~TKey()
voidTObject::AbstractMethod(const char* method) const
virtual voidTObject::AppendPad(Option_t* option = "")
virtual voidBrowse(TBrowser* b)
static TClass*Class()
virtual const char*TObject::ClassName() const
virtual voidTNamed::Clear(Option_t* option = "")
virtual TObject*TNamed::Clone(const char* newname = "") const
virtual Int_tTNamed::Compare(const TObject* obj) const
virtual voidTNamed::Copy(TObject& named) const
virtual voidDelete(Option_t* option = "")
virtual voidDeleteBuffer()
virtual Int_tTObject::DistancetoPrimitive(Int_t px, Int_t py)
virtual voidTObject::Draw(Option_t* option = "")
virtual voidTObject::DrawClass() constMENU
virtual TObject*TObject::DrawClone(Option_t* option = "") constMENU
virtual voidTObject::Dump() constMENU
virtual voidTObject::Error(const char* method, const char* msgfmt) const
virtual voidTObject::Execute(const char* method, const char* params, Int_t* error = 0)
virtual voidTObject::Execute(TMethod* method, TObjArray* params, Int_t* error = 0)
virtual voidTObject::ExecuteEvent(Int_t event, Int_t px, Int_t py)
virtual voidTObject::Fatal(const char* method, const char* msgfmt) const
virtual voidFillBuffer(char*& buffer)
virtual TObject*TObject::FindObject(const char* name) const
virtual TObject*TObject::FindObject(const TObject* obj) const
virtual char*GetBuffer() const
TBuffer*GetBufferRef() const
virtual const char*GetClassName() const
Short_tGetCycle() const
const TDatime&GetDatime() const
virtual Option_t*TObject::GetDrawOption() const
static Long_tTObject::GetDtorOnly()
TFile*GetFile() const
virtual const char*GetIconName() const
Short_tGetKeep() const
Int_tGetKeylen() const
TDirectory*GetMotherDir() const
virtual const char*TNamed::GetName() const
Int_tGetNbytes() const
virtual char*TObject::GetObjectInfo(Int_t px, Int_t py) const
static Bool_tTObject::GetObjectStat()
Int_tGetObjlen() const
virtual Option_t*TObject::GetOption() const
virtual Long64_tGetSeekKey() const
virtual Long64_tGetSeekPdir() const
virtual const char*GetTitle() const
virtual UInt_tTObject::GetUniqueID() const
Int_tGetVersion() const
virtual Bool_tTObject::HandleTimer(TTimer* timer)
virtual ULong_tHash() const
virtual voidIncrementPidOffset(UShort_t offset)
virtual voidTObject::Info(const char* method, const char* msgfmt) const
virtual Bool_tTObject::InheritsFrom(const char* classname) const
virtual Bool_tTObject::InheritsFrom(const TClass* cl) const
virtual voidTObject::Inspect() constMENU
voidTObject::InvertBit(UInt_t f)
virtual TClass*IsA() const
virtual Bool_tTObject::IsEqual(const TObject* obj) const
virtual Bool_tIsFolder() const
Bool_tTObject::IsOnHeap() const
virtual Bool_tTNamed::IsSortable() const
Bool_tTObject::IsZombie() const
virtual voidKeep()
virtual voidls(Option_t* option = "") const
voidTObject::MayNotUse(const char* method) const
virtual Bool_tTObject::Notify()
voidTObject::Obsolete(const char* method, const char* asOfVers, const char* removedFromVers) const
voidTObject::operator delete(void* ptr)
voidTObject::operator delete(void* ptr, void* vp)
voidTObject::operator delete[](void* ptr)
voidTObject::operator delete[](void* ptr, void* vp)
void*TObject::operator new(size_t sz)
void*TObject::operator new(size_t sz, void* vp)
void*TObject::operator new[](size_t sz)
void*TObject::operator new[](size_t sz, void* vp)
virtual voidTObject::Paint(Option_t* option = "")
virtual voidTObject::Pop()
virtual voidPrint(Option_t* option = "") const
virtual Int_tRead(TObject* obj)
virtual voidReadBuffer(char*& buffer)
virtual Bool_tReadFile()
voidReadKeyBuffer(char*& buffer)
virtual TObject*ReadObj()
virtual void*ReadObjectAny(const TClass* expectedClass)
virtual TObject*ReadObjWithBuffer(char* bufferRead)
virtual voidTObject::RecursiveRemove(TObject* obj)
voidTObject::ResetBit(UInt_t f)
virtual voidTObject::SaveAs(const char* filename = "", Option_t* option = "") constMENU
virtual voidTObject::SavePrimitive(ostream& out, Option_t* option = "")
voidTObject::SetBit(UInt_t f)
voidTObject::SetBit(UInt_t f, Bool_t set)
virtual voidSetBuffer()
virtual voidTObject::SetDrawOption(Option_t* option = "")MENU
static voidTObject::SetDtorOnly(void* obj)
voidSetMotherDir(TDirectory* dir)
virtual voidTNamed::SetName(const char* name)MENU
virtual voidTNamed::SetNameTitle(const char* name, const char* title)
static voidTObject::SetObjectStat(Bool_t stat)
virtual voidSetParent(const TObject* parent)
virtual voidTNamed::SetTitle(const char* title = "")MENU
virtual voidTObject::SetUniqueID(UInt_t uid)
virtual voidShowMembers(TMemberInspector& insp) const
virtual Int_tSizeof() const
virtual voidStreamer(TBuffer&)
voidStreamerNVirtual(TBuffer& ClassDef_StreamerNVirtual_b)
virtual voidTObject::SysError(const char* method, const char* msgfmt) const
Bool_tTObject::TestBit(UInt_t f) const
Int_tTObject::TestBits(UInt_t f) const
TKey()
TKey(TDirectory* motherDir)
TKey(TDirectory* motherDir, const TKey& orig, UShort_t pidOffset)
TKey(Long64_t pointer, Int_t nbytes, TDirectory* motherDir = 0)
TKey(const TObject* obj, const char* name, Int_t bufsize, TDirectory* motherDir)
TKey(const char* name, const char* title, const TClass* cl, Int_t nbytes, TDirectory* motherDir)
TKey(const TString& name, const TString& title, const TClass* cl, Int_t nbytes, TDirectory* motherDir)
TKey(const void* obj, const TClass* cl, const char* name, Int_t bufsize, TDirectory* motherDir)
virtual voidTObject::UseCurrentStyle()
virtual voidTObject::Warning(const char* method, const char* msgfmt) const
virtual Int_tTObject::Write(const char* name = 0, Int_t option = 0, Int_t bufsize = 0)
virtual Int_tTObject::Write(const char* name = 0, Int_t option = 0, Int_t bufsize = 0) const
virtual Int_tWriteFile(Int_t cycle = 1, TFile* f = 0)
protected:
voidBuild(TDirectory* motherDir, const char* classname, Long64_t filepos)
virtual voidCreate(Int_t nbytes, TFile* f = 0)
virtual voidTObject::DoError(int level, const char* location, const char* fmt, va_list va) const
voidTObject::MakeZombie()
virtual Int_tRead(const char* name)
virtual voidReset()
virtual Int_tWriteFileKeepBuffer(TFile* f = 0)
private:
TKey&operator=(const TKey&)
TKey(const TKey&)

Data Members

public:
static TObject::(anonymous)TObject::kBitMask
static TObject::EStatusBitsTObject::kCanDelete
static TObject::EStatusBitsTObject::kCannotPick
static TObject::EStatusBitsTObject::kHasUUID
static TObject::EStatusBitsTObject::kInvalidObject
static TObject::(anonymous)TObject::kIsOnHeap
static TObject::EStatusBitsTObject::kIsReferenced
static TObject::EStatusBitsTObject::kMustCleanup
static TObject::EStatusBitsTObject::kNoContextMenu
static TObject::(anonymous)TObject::kNotDeleted
static TObject::EStatusBitsTObject::kObjInCanvas
static TObject::(anonymous)TObject::kOverwrite
static TObject::(anonymous)TObject::kSingleKey
static TObject::(anonymous)TObject::kWriteDelete
static TObject::(anonymous)TObject::kZombie
protected:
char*fBufferObject buffer
TBuffer*fBufferRefPointer to the TBuffer object
TStringfClassNameObject Class name
Short_tfCycleCycle number
TDatimefDatimeDate/Time of insertion in file
Short_tfKeylenNumber of bytes for the key itself
Int_tfLeftNumber of bytes left in current segment
TDirectory*fMotherDir! pointer to mother directory
TStringTNamed::fNameobject identifier
Int_tfNbytesNumber of bytes for the object on file
Int_tfObjlenLength of uncompressed object in bytes
UShort_tfPidOffset! Offset to be added to the pid index in this key/buffer. This is actually saved in the high bits of fSeekPdir
Long64_tfSeekKeyLocation of object on file
Long64_tfSeekPdirLocation of parent directory on file
TStringTNamed::fTitleobject title
Int_tfVersionKey version identifier
private:
static TKey::EStatusBitskIsDirectoryFile

Class Charts

Inheritance Inherited Members Includes Libraries
Class Charts

Function documentation

TKey()
 TKey default constructor.
TKey(TDirectory* motherDir)
 TKey default constructor.
TKey(TDirectory* motherDir, const TKey& orig, UShort_t pidOffset)
 Copy a TKey from its original directory to the new 'motherDir'
TKey(Long64_t pointer, Int_t nbytes, TDirectory* motherDir = 0)
 Create a TKey object to read keys.
 Constructor called by TDirectoryFile::ReadKeys and by TFile::TFile.
 A TKey object is created to read the keys structure itself.
TKey(const char* name, const char* title, const TClass* cl, Int_t nbytes, TDirectory* motherDir)
 Create a TKey object with the specified name, title for the given class.

  WARNING: in name avoid special characters like '^','$','.' that are used
  by the regular expression parser (see TRegexp).
TKey(const TString& name, const TString& title, const TClass* cl, Int_t nbytes, TDirectory* motherDir)
 Create a TKey object with the specified name, title for the given class.

  WARNING: in name avoid special characters like '^','$','.' that are used
  by the regular expression parser (see TRegexp).
TKey(const TObject* obj, const char* name, Int_t bufsize, TDirectory* motherDir)
 Create a TKey object for a TObject* and fill output buffer

  WARNING: in name avoid special characters like '^','$','.' that are used
  by the regular expression parser (see TRegexp).
TKey(const void* obj, const TClass* cl, const char* name, Int_t bufsize, TDirectory* motherDir)
 Create a TKey object for any object obj of class cl d and fill
 output buffer.

  WARNING: in name avoid special characters like '^','$','.' that are used
  by the regular expression parser (see TRegexp).
void Build(TDirectory* motherDir, const char* classname, Long64_t filepos)
 method used in all TKey constructor to initialize basic data fields
 filepos is used to calculate correct version number of key
 if filepos==-1, end of file position is used
void Browse(TBrowser* b)
 Read object from disk and call its Browse() method.
 If object with same name already exist in memory delete it (like
 TDirectoryFile::Get() is doing), except when the key references a
 folder in which case we don't want to re-read the folder object
 since it might contain new objects not yet saved.
void Create(Int_t nbytes, TFile* f = 0)
 Create a TKey object of specified size
 if externFile!=0, key will be allocated in specified file,
 otherwise file of mother directory will be used
~TKey()
 TKey default destructor.
void Delete(Option_t* option = "")
 Delete an object from the file.
 Note: the key is not deleted. You still have to call "delete key".
 This is different from the behaviour of TObject::Delete()!
void DeleteBuffer()
 Delete key buffer(s).
Short_t GetCycle() const
 Return cycle number associated to this key.
TFile * GetFile() const
 Returns file to which key belong
Short_t GetKeep() const
 Returns the "KEEP" status.
void FillBuffer(char*& buffer)
 Encode key header into output buffer.
ULong_t Hash() const
 This Hash function should redefine the default from TNamed.
void IncrementPidOffset(UShort_t offset)
 Increment fPidOffset by 'offset'.
 This offset is used when a key (or basket) is transfered from one file to
 the other.  In this case the TRef and TObject might have stored a pid
 index (to retrieve TProcessIDs) which refered to their order on the
 original file, the fPidOffset is to be added to those values to correctly
 find the TProcessID.  This fPidOffset needs to be increment if the
 key/basket is copied and need to be zero for new key/basket.
Bool_t IsFolder() const
 Check if object referenced by the key is a folder.
void Keep()
 Set the "KEEP" status.
 When the KEEP flag is set to 1 the object cannot be purged.
void ls(Option_t* option = "") const
 List Key contents.
void Print(Option_t* option = "") const
 Print key contents.
TObject * ReadObj()
 To read a TObject* from the file.

  The object associated to this key is read from the file into memory
  Once the key structure is read (via Streamer) the class identifier
  of the object is known.
  Using the class identifier we find the TClass object for this class.
  A TClass object contains a full description (i.e. dictionary) of the
  associated class. In particular the TClass object can create a new
  object of the class type it describes. This new object now calls its
  Streamer function to rebuilt itself.

  Use TKey::ReadObjectAny to read any object non-derived from TObject

  Note:
  A C style cast can only be used in the case where the final class
  of this object derives from TObject as a first inheritance, otherwise
  one must use a dynamic_cast.

  Example1: simplified case:
      class MyClass : public TObject, public AnotherClass
   then on return, one get away with using:
    MyClass *obj = (MyClass*)key->ReadObj();

  Example2: Usual case (recommended unless performance is critical)
    MyClass *obj = dynamic_cast<MyClass*>(key->ReadObj());
  which support also the more complex inheritance like:
    class MyClass : public AnotherClass, public TObject

  Of course, dynamic_cast<> can also be used in the example 1.
TObject * ReadObjWithBuffer(char* bufferRead)
 To read a TObject* from bufferRead.
 This function is identical to TKey::ReadObj, but it reads directly
 from bufferRead instead of reading from a file.
  The object associated to this key is read from the buffer into memory
  Using the class identifier we find the TClass object for this class.
  A TClass object contains a full description (i.e. dictionary) of the
  associated class. In particular the TClass object can create a new
  object of the class type it describes. This new object now calls its
  Streamer function to rebuilt itself.

  NOTE :
  This function is called only internally by ROOT classes.
  Although being public it is not supposed to be used outside ROOT.
  If used, you must make sure that the bufferRead is large enough to
  accomodate the object being read.
void * ReadObjectAny(const TClass* expectedClass)
  To read an object (non deriving from TObject) from the file.

  If expectedClass is not null, we checked that that actual class of
  the object stored is suitable to be stored in a pointer pointing
  to an object of class 'expectedClass'.  We also adjust the value
  of the returned address so that it is suitable to be cast (C-Style)
  a  a pointer pointing to an object of class 'expectedClass'.

  So for example if the class Bottom inherits from Top and the object
  stored is of type Bottom you can safely do:

     TClass *TopClass = TClass::GetClass("Top");
     Top *ptr = (Top*) key->ReadObjectAny( TopClass );
     if (ptr==0) printError("the object stored in the key is not of the expected type\n");

  The object associated to this key is read from the file into memory
  Once the key structure is read (via Streamer) the class identifier
  of the object is known.
  Using the class identifier we find the TClass object for this class.
  A TClass object contains a full description (i.e. dictionary) of the
  associated class. In particular the TClass object can create a new
  object of the class type it describes. This new object now calls its
  Streamer function to rebuilt itself.
Int_t Read(TObject* obj)
 To read an object from the file.
 The object associated to this key is read from the file into memory.
 Before invoking this function, obj has been created via the
 default constructor.
void ReadBuffer(char*& buffer)
 Decode input buffer.
 In some situation will add key to gDirectory ???
void ReadKeyBuffer(char*& buffer)
 Decode input buffer.
Bool_t ReadFile()
 Read the key structure from the file
void SetParent(const TObject* parent)
 Set parent in key buffer.
void Reset()
 Reset the key as it had not been 'filled' yet.
Int_t Sizeof() const
 Return the size in bytes of the key header structure.
 Int_t nbytes = sizeof fNbytes;      4
             += sizeof(Version_t);   2
             += sizeof fObjlen;      4
             += sizeof fKeylen;      2
             += sizeof fCycle;       2
             += sizeof fSeekKey;     4 or 8
             += sizeof fSeekPdir;    4 or 8
              =                     22
void Streamer(TBuffer& )
 Stream a class object.
Int_t WriteFile(Int_t cycle = 1, TFile* f = 0)
 Write the encoded object supported by this key.
 The function returns the number of bytes committed to the file.
 If a write error occurs, the number of bytes returned is -1.
Int_t WriteFileKeepBuffer(TFile* f = 0)
 Write the encoded object supported by this key.
 The function returns the number of bytes committed to the file.
 If a write error occurs, the number of bytes returned is -1.
const char * GetIconName() const
 Title can keep 32x32 xpm thumbnail/icon of the parent object.
const char * GetTitle() const
 Returns title (title can contain 32x32 xpm thumbnail/icon).
TKey(const TKey& )
TKey& operator=(const TKey& )
Int_t Read(const char* name)
{ return TObject::Read(name); }
const char * GetClassName() const
{return fClassName.Data();}
char * GetBuffer() const
{return fBuffer+fKeylen;}
TBuffer * GetBufferRef() const
{return fBufferRef;}
const TDatime & GetDatime() const
{return fDatime;}
Int_t GetKeylen() const
{return fKeylen;}
TDirectory* GetMotherDir() const
{ return fMotherDir; }
Int_t GetNbytes() const
{return fNbytes;}
Int_t GetObjlen() const
{return fObjlen;}
Int_t GetVersion() const
{return fVersion;}
Long64_t GetSeekKey() const
{return fSeekKey;}
Long64_t GetSeekPdir() const
{return fSeekPdir;}
void SetBuffer()
{ fBuffer = new char[fNbytes];}
void SetMotherDir(TDirectory* dir)
{ fMotherDir = dir; }