Object.h

Go to the documentation of this file.

// $Id: Object.h 4472 2020-04-15 13:33:18Z 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_Object
#define DABC_Object
 
#ifndef DABC_defines
#include "dabc/defines.h"
#endif
 
#ifndef DABC_Reference
#include "dabc/Reference.h"
#endif
 
#ifndef DABC_ConfigIO
#include "dabc/ConfigIO.h"
#endif
 
namespace dabc {
 
   class Manager;
   class Thread;
   class Mutex;
   class Configuration;
   class ReferencesVector;
   class HierarchyContainer;
 
   extern const char* xmlDeviceNode;
   extern const char* xmlThreadNode;
   extern const char* xmlMemoryPoolNode;
   extern const char* xmlModuleNode;
   extern const char* xmlConnectionNode;
 
   extern const char* xmlQueueAttr;
   extern const char* xmlBindAttr;
   extern const char* xmlSignalAttr;
   extern const char* xmlRateAttr;
   extern const char* xmlLoopAttr;
   extern const char* xmlInputQueueSize;
   extern const char* xmlOutputQueueSize;
   extern const char* xmlInlineDataSize;
 
   extern const char* xmlPoolName;
   extern const char* xmlWorkPool;
   extern const char* xmlFixedLayout;
   extern const char* xmlCleanupTimeout;
   extern const char* xmlBufferSize;
   extern const char* xmlNumBuffers;
   extern const char* xmlNumSegments;
   extern const char* xmlAlignment;
   extern const char* xmlShowInfo;
 
   extern const char* xmlNumInputs;
   extern const char* xmlNumOutputs;
   extern const char* xmlInputPrefix;
   extern const char* xmlInputMask;
   extern const char* xmlOutputPrefix;
   extern const char* xmlOutputMask;
 
   extern const char* xmlUseAcknowledge;
   extern const char* xmlFlushTimeout;
   extern const char* xmlConnTimeout;
 
   // list of parameters, taken from URL
   // this parameters can be (should be) used in many places, which
   // allows to specify them through standardized URL syntax
   extern const char* xmlProtocol;
   extern const char* xmlHostName;
   extern const char* xmlFileName;     // used as file name option in separate xml node
   extern const char* xmlFileNumber;   // used as file number option in separate xml node
   extern const char* xmlFileSizeLimit; // used as separate xml node
   extern const char* xml_maxsize;      // used as option in file url
   extern const char* xml_number;       // used as option in file url
   extern const char* xml_flush;        // used as flush attribute in url
 
   extern const char* xmlMcastAddr;
   extern const char* xmlMcastPort;
   extern const char* xmlMcastRecv;
 
   extern const char* typeThread;
   extern const char* typeDevice;
   extern const char* typeSocketDevice;
   extern const char* typeSocketThread;
   extern const char* typeApplication;
 
   class Object {
      friend class Manager;
      friend class Reference;
 
      private:
 
         enum EState {
            stConstructor       = 0,      
            stNormal            = 1,      
            stWaitForThread     = 2,      
            stDoingDestroy      = 3,      
            stWaitForDestructor = 4,      
            stDestructor        = 5       
         };
 
         static unsigned  gNumInstances;  
         static unsigned  gNumCreated;    
 
         void Constructor();
 
         void Destructor();
 
         bool IncReference(bool withmutex = true);
 
         bool DecReference(bool ask_to_destroy, bool do_decrement = true, bool from_thread = false);
 
         inline EState GetState() const { return (EState) (fObjectFlags & flStateMask); }
 
         inline void SetState(EState st) { fObjectFlags = (fObjectFlags & ~flStateMask) | (unsigned) st ; }
 
         static Reference SearchForChild(Reference& ref, const char* name, bool firsttime, bool force) throw();
 
         void SetCleanupBit();
 
      protected:
 
         enum EFlags {
            flStateMask      = 0x000f,  
            flIsOwner        = 0x0010,  
            flCleanup        = 0x0020,  
            flHasThread      = 0x0040,  
            flAutoDestroy    = 0x0080,  
            flLogging        = 0x0100,  
            flNoMutex        = 0x0200,  
            flHidden         = 0x0400,  
            flChildsHidden   = 0x0800,  
            flTopXmlLevel    = 0x1000   
         };
 
         unsigned           fObjectFlags;    
         Reference          fObjectParent;   
         std::string        fObjectName;     
         Mutex*             fObjectMutex;    
         int                fObjectRefCnt;   
         ReferencesVector*  fObjectChilds;   
         int                fObjectBlock;    
 
         inline bool GetFlag(unsigned fl) const { return (fObjectFlags & fl) != 0; }
 
         inline void SetFlag(unsigned fl, bool on = true) { fObjectFlags = (on ? (fObjectFlags | fl) : (fObjectFlags & ~fl)); }
 
         inline Mutex* ObjectMutex() const { return fObjectMutex; }
 
         unsigned NumReferences();
 
         virtual bool DestroyByOwnThread() { return false; }
 
         bool DestroyCalledFromOwnThread();
 
         virtual void ObjectCleanup();
 
         virtual bool _DoDeleteItself() { return false; }
 
         void SetOwner(bool on = true);
 
         void SetAutoDestroy(bool on = true);
 
         virtual void ObjectDestroyed(Object*) {}
 
         bool IsNormalState();
 
         void FillFullName(std::string &fullname, Object* upto, bool exclude_top_parent = false) const;
 
         bool _IsNormalState();
 
         virtual Object *CreateInstance(const std::string &name) { return new Object(nullptr, name); }
 
         virtual void _ChildsChanged() {}
 
         struct ConstructorPair {
            friend class Object;
 
            private:
               Reference parent;
               std::string name;
 
               ConstructorPair() : parent(), name() {}
               ConstructorPair(const ConstructorPair& src) : parent(src.parent), name(src.name) {}
         };
 
         static ConstructorPair MakePair(Reference prnt, const std::string &fullname, bool withmanager = true);
 
         static ConstructorPair MakePair(Object* prnt, const std::string &fullname, bool withmanager = true);
 
         static ConstructorPair MakePair(const std::string &fullname, bool withmanager = true);
 
         Object(const ConstructorPair& pair, unsigned flags = flIsOwner);
 
      public:
 
         Object(const std::string &name, unsigned flags = flIsOwner);
 
         Object(Reference parent, const std::string &name, unsigned flags = flIsOwner);
 
         // FIXME: one should find a way to catch a call to the destructor
         virtual ~Object();
 
         Object* GetParent() const { return fObjectParent(); }
 
         Reference GetParentRef() const { return fObjectParent; }
 
         bool IsParent(Object* obj) const;
 
         const char* GetName() const { return fObjectName.c_str(); }
 
         bool IsName(const char* str) const { return fObjectName.compare(str)==0; }
 
         bool IsName(const std::string &str) const { return fObjectName.compare(str)==0; }
 
         bool IsName(const char* str, int len) const;
 
         bool IsNameMatch(const std::string &mask) const;
 
         bool IsOwner() const;
 
         bool IsLogging() const;
 
         void SetLogging(bool on = true);
 
         bool IsHidden() const;
 
         bool IsChildsHidden() const;
 
         bool IsTopXmlLevel() const;
 
         // List of children is __thread safe__ BUT may change in any time in between two calls
         // To perform some complex actions, references on child objects should be used
 
 
         // TODO: should it be public?
         // TODO: do we need another method
 
         bool AddChild(Object* child, bool withmutex = true) throw();
 
         bool AddChildAt(Object* child, unsigned pos, bool withmutex = true);
 
         bool RemoveChild(Object* child, bool cleanup = true) throw();
 
         bool RemoveChildAt(unsigned n, bool cleanup = true) throw();
 
         bool RemoveChilds(bool cleanup = true);
 
         unsigned NumChilds() const;
 
         Object* GetChild(unsigned n) const;
 
         Reference GetChildRef(unsigned n) const;
 
         bool GetAllChildRef(ReferencesVector* vect) const;
 
         Object* FindChild(const char* name) const;
 
         //TODO: one need method reverse to FindChild - MakePath()
         // one should be able to produce string which can be used to find specified object
 
         Reference FindChildRef(const char* name, bool force = false) const throw();
 
         Reference GetFolder(const std::string &name, bool force = false) throw();
 
         virtual void Print(int lvl = 0);
 
         std::string ItemName(bool compact = true) const;
 
         // ALL following methods about object destroyment and cleanup
 
         static void Destroy(Object* obj) throw();
 
         virtual const char* ClassName() const { return "Object"; }
 
         virtual bool Find(ConfigIO &cfg);
 
         virtual void BuildFieldsMap(RecordFieldsMap* cont) {}
 
         // operations with object name (and info) are __not thread safe__
         // therefore, in the case when object name must be changed,
         // locking should be applied by any other means
 
         static unsigned NumInstances() { return gNumInstances; }
 
         static void InspectGarbageCollector();
 
         static bool NameMatch(const std::string &name, const std::string &mask);
 
         static bool NameMatchM(const std::string &name, const std::string &mask);
 
#ifdef DABC_EXTRA_CHECKS
         static void DebugObject(const char* classname = 0, Object* instance = 0, int kind = 0);
#endif
 
      protected:
         void SetName(const char* name);
 
         void SetNameDirect(const char* name);
 
         void DeleteThis();
   };
};
 
#endif