attribute.h

Go to the documentation of this file.

/******************************************************************************
 ** Copyright (c) 2025 MAK Technologies
 ** All rights reserved.
 ******************************************************************************/
 
#pragma once
 
//! \file attribute.h
//! \brief Provides attribute handling system for hierarchical data storage and manipulation
 
#include "vreUtil/export.h"
#include "vreUtil/logger.h"
#include "vreUtil/attribute_data.h"
#include "vreUtil/attributeHandle.h"
#include "vreUtil/attributeCallback.h"
 
#include <tbb/spin_mutex.h>
 
#include <list>
#include <map>
#include <chrono>
 
namespace makVre
{
 
//! \brief Core attribute class for shared data storage
//!
//! The DtAttribute class provides a flexible system for storing data to be shared
//! between various app systems and components. It supports type-safe access and
//! thread-safe change notifications. Attributes are organized in a heirarchical
//! tree structure. Attribute are identified by names, which must be unique within
//! each node.
class UTIL_DLL DtAttribute
{
public:
   //! \brief Returns a reference to the root attribute
   //!
   //! \return A reference to the root attribute handle
   static DtAttributeHandle& Root();
 
public:
   //! \brief Virtual destructor
   virtual ~DtAttribute();
 
   //! \brief Returns the handle for this attribute
   //!
   //! \return A handle to this attribute
   DtAttributeHandle handle();
 
   //! \brief Returns the const handle for this attribute
   //!
   //! \return A const handle to this attribute
   const DtAttributeHandle handle() const;
 
   //! \brief Conversion operator to DtAttributeHandle
   operator DtAttributeHandle();
 
   //! \brief Conversion operator to const DtAttributeHandle
   operator const DtAttributeHandle() const;
 
   //! \brief Returns the name associated with this attribute
   //!
   //! \return The name of this attribute
   virtual const std::string& name() const;
 
   //! \brief Returns the full path of this attribute in the hierarchy
   //!
   //! \return The full path string in dot notation
   virtual std::string path() const;
 
   //! \brief Returns the type of this attribute
   //!
   //! \return The type name as a string
   const std::string& type() const;
 
   //! \brief Checks if the attribute is of the specified type
   //!
   //! \return true if the attribute is of type T, false otherwise
   template <typename T>
   bool isType() const;
 
   //! \brief Checks if the attribute is of the specified type by name
   //!
   //! \param type The type name to check against
   //! \return true if the attribute is of the specified type, false otherwise
   bool isType(const std::string& type) const;
 
   //! \brief Checks if the attribute value is undefined
   //!
   //! \return true if the attribute has no defined value, false otherwise
   bool isSet() const;
 
   //! \brief Gets the value of the attribute
   //!
   //! \return The value of the attribute of type T
   //! \note Throws an assertion if the attribute is of a different type
   template <typename T>
   const T& get() const;
 
   //! \brief Gets the value of the attribute or a default value if undefined
   //!
   //! \param orValue The default value to return if the attribute is undefined
   //! \return The attribute value or the default value
   template <typename T>
   T getOr(T orValue) const;
 
   //! \brief Sets the value of the attribute
   //!
   //! If the new value differs from existing, change callbacks will be invoked.
   //!
   //! \param value The new value to set
   //! \return true if the new value differs from existing
   template <typename T>
   bool set(const T& value);
 
   // template <typename T>
   // bool set(T&& value);//TODO
 
   //! \brief Sets the value of the attribute only if it is currently undefined
   //!
   //! \param defaultValue The default value to set if the attribute is undefined
   //! \return true if the value was set, false if the attribute already had a value
   template <typename T>
   bool setIfNot(const T& defaultValue);
 
   template <typename T>
   void modifyFast(std::function<bool(T& value)> modifyFunc);
 
   template <typename T>
   bool modify(std::function<void(T& value)> modifyFunc);
 
   //! \brief Gets the value of a child attribute
   //!
   //! \param attribute The name of the child attribute
   //! \return The value of the child attribute
   template <typename T>
   const T& getAttribute(const std::string& attribute) const;
 
   //! \brief Gets the value of a child attribute or a default value if undefined
   //!
   //! \param attribute The name of the child attribute
   //! \param orValue The default value to return if the attribute is undefined
   //! \return The child attribute value or the default value
   template <typename T>
   T getAttributeOr(const std::string& attribute, T orValue) const;
 
   //! \brief Sets the value of a child attribute
   //!
   //! If the new value differs from existing, change callbacks will be invoked.
   //!
   //! \param attribute The name of the child attribute
   //! \param newValue The new value to set
   //! \return true if the value changed
   template <typename T>
   bool setAttribute(const std::string& attribute, const T& newValue);
 
   //! \brief Gets string representation of the attribute value
   //!
   //! \return String representation of the attribute value
   std::string getAsString() const;
 
   //! \brief Sets the attribute value from a string representation
   //!
   //! If the new value differs from existing, change callbacks will be invoked.
   //!
   //! \param newValue String representation of the new value
   //! \return true if the value changed
   bool setFromString(const std::string& newValue);
 
   //! \brief Gets the previous value of the attribute before the last change
   //!
   //! \return The previous value of the attribute
   template <typename T>
   const T& previousValue() const;
 
   //! \brief Unsets the attribute value
   //!
   //! Value is returned to an undefined, typeless state
   //!
   //! \return true if the attribute was unset, false otherwise
   bool unset();
 
   //! \brief Unsets (clears) a child attribute value
   //!
   //! Value is returned to an undefined, typeless state
   //!
   //! \param name The name of the child attribute to unset
   //! \return true if the child attribute was unset, false otherwise
   bool unset(const std::string& name);
 
   //! \brief Unsets this attribute and all child attributes, recursively
   //!
   //! \return true if all attributes were unset successfully
   bool unsetRecursive();
 
   //! \brief Set whether this attribute exists w/o handles assigned
   //!
   //! A persistent attribute will continue to exist in the attribute tree
   //! for the lifetime of the application. A non-persistent attribute will
   //! be deleted as soon as no handles are assigned to it. The default
   //! condition for attributes is persistent.
   //!
   //! \param persistent Set true for persistent, false for non-persistent
   void setPersistence(bool persistent);
 
   //! \brief Sets the persistence of this attribute and all child attributes
   //!
   //! \ref setPersistence
   //!
   //! \param persistent Set true for persistent, false for non-persistent
   void setPersistenceRecursive(bool persistent);
 
   //! \brief Check the persistence state of this attribute
   //!
   //! \ref setPersistence
   //!
   //! \return true if attribute is persitent, false if not
   bool isPersistent() const;
 
   //! \brief Checks if a child attribute exists
   //!
   //! \return true if the child attribute exists, false otherwise
   bool hasAttribute(const std::string& name) const;
 
   bool contains(const DtAttributeHandle& attr) const;
 
   bool containedBy(const DtAttributeHandle& attr) const;
 
   //! \brief Gets a handle to a child attribute
   //!
   //! \param name The name of the child attribute. Name may be
   //! a path to child subattributes in format
   //! "ChildName.GrandChild.GreatGrandChild"
   //! \return A handle to the child attribute
   DtAttributeHandle attribute(const std::string& name);
 
   //! \brief Const version of \ref attribute(const std::string&)
   const DtAttributeHandle attribute(const std::string& name) const;
 
   //! \brief Gets a handle to the parent attribute
   //!
   //! \return A handle to the parent attribute
   DtAttributeHandle parent();
 
   //! \brief Gets a const handle to the parent attribute
   //!
   //! \return A const handle to the parent attribute
   const DtAttributeHandle parent() const;
 
   //! \brief Gets a handle to the first child attribute
   //!
   //! \return A handle to the first child attribute
   DtAttributeHandle first();
 
   //! \brief Gets a const handle to the first child attribute
   //!
   //! \return A const handle to the first child attribute
   const DtAttributeHandle first() const;
 
   //! \brief Gets a handle to the next sibling attribute
   //!
   //! \return A handle to the next sibling attribute
   DtAttributeHandle next();
 
   //! \brief Gets a const handle to the next sibling attribute
   //!
   //! \return A const handle to the next sibling attribute
   const DtAttributeHandle next() const;
 
   //! \brief Gets a handle to the next sibling attribute, looping back to the first if at the end
   //!
   //! \return A handle to the next sibling attribute
   DtAttributeHandle next_looping();
 
   //! \brief Gets a const handle to the next sibling attribute, looping back to the first if at the end
   //!
   //! \return A const handle to the next sibling attribute
   const DtAttributeHandle next_looping() const;
 
   void forEach(std::function<void(DtAttributeHandle)> forEachFun);
 
   void forEach(std::function<void(const DtAttributeHandle)> forEachFun) const;
 
   //! \brief Checks if this attribute is the root attribute
   //!
   //! \return true if this is the root attribute, false otherwise
   bool isRoot() const;
 
   //! \brief Gets the raw data pointer
   //!
   //! \return The raw data pointer
   const void* raw() const;
 
   //! \brief Locks the attribute with a key
   //!
   //! \param key The key to use for locking
   //! \return true if the attribute was locked, false if it was already locked
   bool lock(unsigned int key);
 
   //! \brief Unlocks the attribute with a key
   //!
   //! \param key The key used for locking
   //! \return true if the attribute was unlocked, false if the key was incorrect
   bool unlock(unsigned int key);
 
   //! \brief Checks if the attribute is locked
   //!
   //! \return true if the attribute is locked, false otherwise
   bool locked() const;
 
   //! \brief Adds a change callback for this attribute
   //!
   //! \param callback The callback to add
   void addCallback(const DtAttributeCallbackBase& callback);
 
   //! \brief Removes a change callback from this attribute
   //!
   //! \param callback The callback to remove
   void removeCallback(const DtAttributeCallbackBase& callback);
 
   void checkPendingCallbacksRecursive();
 
   //! \brief Recursively dumps the attribute hierarchy to a table
   //!
   //! \param depth The current depth in the hierarchy
   //! \return A table representation of the attribute hierarchy
   using DumpItem = std::pair<DtAttributeHandle, std::list<std::string>>;
   using DumpTable = std::list<DumpItem>;
   void recursiveDumpToTable(DumpTable& output, int depth = 0) const;
 
   //! \brief Statistics structure for tracking attribute usage
   struct Stats
   {
      //! \brief Constructor initializing all counters to zero
      Stats()
         : myLookups(0)
         , myCreates(0)
         , mySets(0)
         , myChanges(0)
         , myGets(0)
         , myGetsUndefined(0)
      {
      }
 
      //! \brief Time when the attribute was created
      std::chrono::time_point<std::chrono::high_resolution_clock> myCreateTime;
 
      //! \brief Number of attribute lookups
      unsigned int myLookups;
 
      //! \brief Number of attribute creations
      unsigned int myCreates;
 
      //! \brief Number of attribute value sets
      unsigned int mySets;
 
      //! \brief Number of attribute value changes
      unsigned int myChanges;
 
      //! \brief Number of attribute value gets
      unsigned int myGets;
 
      //! \brief Number of attribute value gets when undefined
      unsigned int myGetsUndefined;
   };
 
   //! \brief Gets the attribute statistics
   //!
   //! \return The attribute statistics
   const Stats& stats() const { return myStats; }
 
   enum Trace
   {
      OFF,
      SET,
      CHANGE,
      GET,
      LOOKUP
   };
   static void QueueTrace(DtAttributeHandle attribute, Trace trace);
   static std::pair<DtAttributeHandle, Trace> QueuedTrace();
   static void CancelQueuedTrace();
 
protected:
   friend class DtAttributeHandle;
 
   //! \brief Shared pointer type for attributes
   using Ptr = std::shared_ptr<DtAttribute>;
 
   //! \brief Weak pointer type for attributes
   using Ref = std::weak_ptr<DtAttribute>;
 
   //! \brief Map type for storing child attributes
   using Map = std::map<std::string, std::pair<Ptr, Ref>>;
   using DataPtr = std::shared_ptr<DtAttributeData>;
   using Mutex = tbb::spin_mutex;
 
   using CallbackList = std::list<const DtAttributeCallbackBase*>;
   struct CallbacksForThread
   {
      CallbacksForThread()
         : valueChanged(false)
      {
      }
 
      bool valueChanged;
      CallbackList callbacks;
   };
   using CallbackThreadMap = std::map<unsigned int, CallbacksForThread>;
 
   static Ptr create(const std::string& name, Ptr parent);
 
   //! \brief Default constructor
   DtAttribute();
 
   //! \brief Constructor with name and parent
   //!
   //! \param name The name of the attribute
   //! \param parent The parent attribute
   DtAttribute(const std::string& name, Ptr parent);
 
   //! \brief Gets a shared pointer to this attribute
   //!
   //! \return A shared pointer to this attribute
   Ptr self() const;
 
 
   void forEach(std::function<void(Ptr)> forEachFun);
 
   void forEach(std::function<void(const Ptr)> forEachFun) const;
 
   //! \brief Recursive search for child attribute at path, relative to this
   //! 
   //! Recursive child names in path are delimited by '.', e.g. find("childName.grandChildName.greatGrandChildName")
   //! 
   //! \param path Name or path of names of child attribute to find
   //! \param orCreate If true, creates the attribute (and any intermediate path attributes) if not found; if false, returns null pointer when not found
   //! \return Shared pointer to the found or created attribute, or null if not found and orCreate is false
   Ptr find(const std::string& path, bool orCreate = false);
 
   //! \brief Const version of \ref find(const std::string&, bool)
   const Ptr find(const std::string& path, bool orCreate = false) const;
 
   Ptr addAttribute(const std::string& name);
   const Ptr addAttribute(const std::string& name) const;
 
   //! \brief Creates data storage for the specified type
   //!
   //! \note This is used to initialize the attribute data
   template <typename T>
   void createData() const;
 
   //! \brief Validates that the attribute data is of the specified type
   template <typename T>
   void validateData() const;
 
   void checkPendingCallbacks();
 
   //! \brief Invokes all registered change callbacks
   void invokeCallbacks(const Ptr& changed, unsigned int threadId);
 
   void valueChanged();
 
   //! \brief Checks if the attribute is locked
   //!
   //! \return true if locked and action should be prevented, false otherwise
   bool lockCheck() const;
 
   void doTrace() const;
 
protected:
   //! \brief The name of this attribute
   std::string myName;
 
   //! \brief The data stored in this attribute
   mutable DataPtr myData;
 
   //! \brief Flag indicating if the type was explicitly set
   mutable bool myExplicitType;
 
   //! \brief Mutex for thread synchronization
   mutable Mutex myMutex;
 
   //! \brief List of change callbacks
   CallbackThreadMap myChangeCallbacks;
 
   //! \brief Statistics for this attribute
   mutable Stats myStats;
 
   //! \brief Weak reference to self
   mutable Ref mySelf;
 
   //! \brief Shared pointer to parent
   Ptr myParent;
 
   //! \brief Map of child attributes
   mutable Map myAttributes;
 
   //! \brief Iterator in parent's attribute map referring to this attribute
   Map::iterator myItr;
 
   //! \brief Lock key
   unsigned int myLock;
 
   static std::pair<Ref, Trace> TheQueuedTrace;
   static std::pair<Ref, std::string> TheLastTrace;
};
 
//! \brief Type-specific attribute class
//!
//! This template class extends DtAttribute to provide type-specific
//! access to attribute values. It ensures type safety when getting
//! or setting values.
template <typename T>
class DtAttributeType : public DtAttribute
{
public:
   //! \brief Verifies that the attribute is of the correct type
   //!
   //! \return true if the attribute is of type T, false otherwise
   bool verifyType() const;
 
   //! \brief Gets the value of the attribute
   //!
   //! \return The value of the attribute
   const T& get() const;
 
   //! \brief Gets the value of the attribute or a default value if undefined
   //!
   //! \param orValue The default value to return if the attribute is undefined
   //! \return The attribute value or the default value
   T getOr(T orValue) const;
 
   //! \brief Sets the value of the attribute
   //!
   //! \param value The new value to set
   //! \return true if the value was successfully set, false otherwise
   bool set(const T& value);
 
   // bool set(T&& value);//TODO
 
   //! \brief Sets the value of the attribute only if it is currently undefined
   //!
   //! \param value The value to set if the attribute is undefined
   //! \return true if the value was set, false if the attribute already had a value
   bool setIfNot(const T& value);
 
   void modifyFast(std::function<bool(T& value)> modifyFunc);
 
   bool modify(std::function<void(T& value)> modifyFunc);
 
   const T& previousValue() const;
};
 
} // namespace makVre
 
#include "vreUtil/attribute_data.inl"
#include "vreUtil/attribute.inl"
#include "vreUtil/attributeHandle.inl"
#include "vreUtil/attributeCallback.inl"