Hierarchy.h

Go to the documentation of this file.

// $Id: Hierarchy.h 4471 2020-04-15 13:19:26Z linev $
 
/************************************************************
 * The Data Acquisition Backbone Core (DABC)                *
 ************************************************************
 * Copyright (C) 2009 -                                     *
 * GSI Helmholtzzentrum fuer Schwerionenforschung GmbH      *
 * Planckstr. 1, 64291 Darmstadt, Germany                   *
 * Contact:  http://dabc.gsi.de                             *
 ************************************************************
 * This software can be used under the GPL license          *
 * agreements as stated in LICENSE.txt file                 *
 * which is part of the distribution.                       *
 ************************************************************/
 
#ifndef DABC_Hierarchy
#define DABC_Hierarchy
 
#ifndef DABC_Record
#include "dabc/Record.h"
#endif
 
#ifndef DABC_Queue
#include "dabc/Queue.h"
#endif
 
#include <cstdint>
 
namespace dabc {
 
   extern const char* prop_kind;
   extern const char* prop_version;       // version number of hierarchy item
   extern const char* prop_realname;      // real name property specified, when dabc item can not have such name (including HTTP syntax)
   extern const char* prop_masteritem;    // relative name of master item, which should be loaded before item itself can be used
   extern const char* prop_producer;      // identifies item, which can deliver binary data for all its
   extern const char* prop_error;         // indicates any kind of error - typically in text form
   extern const char* prop_hash;          // content hash, which should describe if object is changed
   extern const char* prop_auth;          // when specified, enabled (true) or disabled (false) authentication for the elements
   extern const char* prop_history;       // indicates that history for that element is kept
   extern const char* prop_time;          // time property, supplied when history is created
   extern const char* prop_more;          // indicate that item can provide more hierarchy if requested
   extern const char* prop_view;          // property indicate preferable view for the item
 
 
   class Hierarchy;
 
   struct HistoryItem {
      public:
         uint64_t version{0};                
         RecordFieldsMap* fields{nullptr};   
         HistoryItem() = default;
         ~HistoryItem() { reset(); }
         void reset() { version = 0; delete fields; fields = nullptr; }
         RecordFieldsMap* take() { auto res = fields; fields = nullptr; return res; }
   };
 
 
   class HistoryContainer : public Object {
      public:
 
         bool        fEnabled{false};         
         bool        fChildsEnabled{false};   
         RecordFieldsMap* fPrev{nullptr};     
         RecordsQueue<HistoryItem> fArr;      
         uint64_t    fRemoteReqVersion{0};    
         uint64_t    fLocalReqVersion{0};     
         bool        fCrossBoundary{false};   
 
         HistoryContainer() :
            Object(0,"cont", flAutoDestroy | flIsOwner),
            fEnabled(false),
            fChildsEnabled(false),
            fPrev(nullptr),
            fArr(),
            fRemoteReqVersion(0),
            fLocalReqVersion(0),
            fCrossBoundary(false)
            {}
 
         virtual ~HistoryContainer()
         {
            delete fPrev; fPrev = nullptr;
         }
 
         uint64_t StoreSize(uint64_t version, int hist_limit = -1);
 
         bool Stream(iostream &s, uint64_t version, int hist_limit = -1);
 
         RecordFieldsMap* TakeNext()
         {
            if (fArr.Size()==0) return nullptr;
            RecordFieldsMap *next = fArr.Front().take();
            fArr.PopOnly();
            return next;
         }
   };
 
 
   class History : public Reference {
      DABC_REFERENCE(History, Reference, HistoryContainer)
 
      void Allocate(unsigned sz = 0)
      {
         SetObject(new HistoryContainer);
         if (sz>0) GetObject()->fArr.Allocate(sz);
      }
 
      bool DoHistory() const { return null() ? false : GetObject()->fEnabled && (GetObject()->fArr.Capacity()>0); }
 
      unsigned Capacity() const { return null() ? 0 : GetObject()->fArr.Capacity(); }
 
      unsigned Size() const { return null() ? 0 : GetObject()->fArr.Size(); }
 
      bool SaveTo(HStore& res);
   };
 
   // =======================================================
 
   class HistoryIterContainer;
 
   class HistoryIter : public Record {
 
      DABC_REFERENCE(HistoryIter, Record, RecordContainer)
 
      bool next();
   };
 
   // =================================================================
 
 
   enum HierarchyStreamKind {
      stream_NamesList,   // store only names list
      stream_Value,       // store only selected entry without childs (plus history, if specified)
      stream_Full,        // store full hierarchy (plus history, if specified)
      stream_NoDelete     // when reading, no any element will be deleted
   };
 
   class HierarchyContainer : public RecordContainer {
 
      friend class Hierarchy;
      friend class HistoryIter;
      friend class HistoryIterContainer;
 
      protected:
 
         enum {
            maskFieldsStored = 1,
            maskChildsStored = 2,
            maskDiffStored = 4,
            maskHistory = 8
         };
 
         uint64_t   fNodeVersion;       
 
         uint64_t   fNamesVersion;
 
         uint64_t   fChildsVersion;  
 
         bool       fAutoTime;          
 
         bool       fPermanent;         
 
         bool       fNodeChanged;       
         bool       fNamesChanged;      
         bool       fChildsChanged;     
 
         bool       fDisableDataReading;    
         bool       fDisableChildsReading;  
         bool       fDisableReadingAsChild; 
 
         Buffer     fBinData;           
 
         History    fHist;              
 
         Mutex*     fHierarchyMutex;    
 
         HierarchyContainer* TopParent();
 
         std::string ItemName();
 
         HierarchyContainer* CreateChildAt(const std::string &name, int indx);
 
         bool UpdateHierarchyFrom(HierarchyContainer* cont);
 
         bool DuplicateHierarchyFrom(HierarchyContainer* cont);
 
         void SetModified(bool node, bool hierarchy, bool recursive = false);
 
         void AddHistory(RecordFieldsMap* diff);
 
         bool ExtractHistoryStep(RecordFieldsMap* fields, unsigned step);
 
         void ClearHistoryEntries();
 
         bool CheckIfDoingHistory();
 
         unsigned MarkVersionIfChanged(uint64_t ver, uint64_t& tm, bool withchilds);
 
         void MarkReading(bool withchilds, bool readvalues, bool readchilds);
 
         void MarkChangedItems(uint64_t tm = 0);
 
         void EnableTimeRecording(bool withchilds = true);
 
         virtual Object *CreateInstance(const std::string &name) { return new HierarchyContainer(name); }
 
         virtual void _ChildsChanged() { fNamesChanged = true; fChildsChanged = true; fNodeChanged = true;  }
 
         uint64_t GetNextVersion() const;
 
         void SetVersion(uint64_t v) { fNodeVersion = v; }
 
         void CreateHMutex();
 
         virtual bool SaveTo(HStore& res, bool create_node = true);
 
      public:
         HierarchyContainer(const std::string &name);
         virtual ~HierarchyContainer();
 
         virtual const char* ClassName() const { return "Hierarchy"; }
 
         uint64_t StoreSize(unsigned kind = stream_Full, uint64_t v = 0, unsigned hist_limit = 0);
 
         bool Stream(iostream& s, unsigned kind = stream_Full, uint64_t v = 0, unsigned hist_limit = 0);
 
         bool IsNodeChanged(bool withchilds = true);
 
         uint64_t GetVersion() const { return fNodeVersion; }
 
         uint64_t GetChildsVersion() const { return fChildsVersion; }
 
         void BuildObjectsHierarchy(const Reference& top);
 
         Buffer& bindata() { return fBinData; }
   };
 
 
   // ______________________________________________________________
 
   class Hierarchy : public Record {
 
      DABC_REFERENCE(Hierarchy, Record, HierarchyContainer)
 
      
      void Create(const std::string &name, bool withmutex = false);
 
      Mutex* GetHMutex() const { return null() ? 0 : GetObject()->fHierarchyMutex; }
 
      Hierarchy FindMaster() const;
 
      std::string FindBinaryProducer(std::string& request_name, bool topmost = true);
 
      //RecordField& Field(const std::string &name) { return GetObject()->Fields().Field(name); }
      const RecordField& Field(const std::string &name) const { return GetObject()->Fields().Field(name); }
 
      bool IsAnyFieldChanged() const { return GetObject() ? GetObject()->Fields().WasChanged() : false; }
 
      void BuildNew(Reference top);
 
      void SetPermanent(bool on = true) { if (GetObject()) GetObject()->fPermanent = on; }
 
      bool Update(Hierarchy& src);
 
      bool Duplicate(const Hierarchy& src);
 
      void EnableHistory(unsigned length = 100, bool withchilds = false);
 
      void EnableTimeRecording(bool withchilds = true)
         { if (GetObject()) GetObject()->EnableTimeRecording(withchilds); }
 
      void MarkChangedItems(uint64_t tm = 0)
         { if (GetObject()) GetObject()->MarkChangedItems(tm); }
 
      bool HasLocalHistory() const;
 
      bool HasActualRemoteHistory() const;
 
      dabc::Buffer SaveToBuffer(unsigned kind = stream_Full, uint64_t version = 0, unsigned hlimit = 0);
 
      bool ReadFromBuffer(const dabc::Buffer& buf);
 
      bool UpdateFromBuffer(const dabc::Buffer& buf, HierarchyStreamKind kind = stream_Full);
 
      uint64_t GetVersion() const { return GetObject() ? GetObject()->GetVersion() : 0; }
 
      void SetVersion(uint64_t v) { if (GetObject()) GetObject()->SetVersion(v); }
 
      bool IsBinItemChanged(const std::string &itemname, uint64_t hash, uint64_t last_version = 0);
 
      bool FillBinHeader(const std::string &itemname, dabc::Command& cmd, uint64_t mhash = 0, const std::string &dflt_master_name = "");
 
      Hierarchy FindChild(const char* name) { return Record::FindChild(name); }
 
      bool RemoveEmptyFolders(const std::string &path);
 
      std::string ItemName() const;
 
      Hierarchy GetTop() const;
 
      bool DettachFromParent();
 
      void DisableReading(bool withchlds = true);
 
      void DisableReadingAsChild();
 
      void EnableReading(const Hierarchy &upto = nullptr);
 
      Hierarchy GetHChild(const std::string &name, bool allowslahes = false, bool force = false, bool sortorder = false);
 
      Hierarchy CreateHChild(const std::string &name, bool allowslahes = false, bool sortorder = false)
        { return GetHChild(name, allowslahes, true, sortorder); }
 
      bool RemoveHChild(const std::string &name, bool allowslahes = false);
 
      Hierarchy CreateFolder(const std::string &name) { return GetHChild(name, true); }
 
      HistoryIter MakeHistoryIter();
   };
 
}
 
#endif