settingsManager.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/

// \file settingsManager.h
// \brief Manages settings saved out in an XML file
// The DtSettingsManager contains DtSettingsObjects which are seralized into
// a settings file using boost::serialize. This manager is not a data storage
// class -- it simply maintains a copy on behalf of a client which provides
// a setting. Such clients are called producers and provide functions which
// the manager can use to get the latest value. Values are only updated upon
// lookup and immediately before the file is written out to disk. Producers
// are not required -- independent settings can also be added to the manager.
// Changes to settings objects can be tracked by registering as a consumer
// for a given object.

#pragma once

#include "makSettingsManager/settingsObject.h"
#include "vlutil/vlFilename.h"

#include <tbb/mutex.h>
#include <map>
#include <set>
#include <list>
#include <mutex>

class DtSettingsObjectFactory;

// Definition for producer functions which are used with registerProducer
typedef void (*DtSettingsProducerFcn)(DtSettingsObject* object, void* usr);

// Holds producer details
struct DtSettingsProducer
{
   std::string type;
   DtSettingsProducerFcn producerFcn;
   void* usr;
};

// Definition for map of producers
typedef std::map<std::string, DtSettingsProducer> DtSettingsProducersMap;

// Definition for comsumer functions which are used with registerConsumer
typedef void (*DtSettingsConsumerFcn)(const DtSettingsObject* object, 
   void* usr);

// Holds consumer details
struct DtSettingsConsumer
{
   DtSettingsConsumer() : consumerFcn(0), usr(0), deleted(new bool(false)) {};
   DtSettingsConsumer(DtSettingsConsumerFcn fcn, void* u) : consumerFcn(fcn), usr(u), deleted(new bool(false)) {};
   DtSettingsConsumer(const DtSettingsConsumer& orig) : consumerFcn(orig.consumerFcn), usr(orig.usr), deleted(orig.deleted) {};

   DtSettingsConsumer& operator=(const DtSettingsConsumer& orig)
   {
      consumerFcn = orig.consumerFcn;
      usr = orig.usr;
      deleted = orig.deleted;

      return *this;
   }

   bool operator<(const DtSettingsConsumer& rhs) const
   {
      return consumerFcn < rhs.consumerFcn || (!(rhs.consumerFcn < consumerFcn) && usr < rhs.usr);
   }

   bool operator>(const DtSettingsConsumer& rhs) const
   {
      return (rhs < *this);
   }

   bool operator==(const DtSettingsConsumer& rhs) const
   {
      return ((consumerFcn == rhs.consumerFcn) &&
         (usr == rhs.usr));
   }

   bool operator!=(const DtSettingsConsumer& rhs) const
   {
      return !(*this == rhs);
   }

   DtSettingsConsumerFcn consumerFcn;
   void* usr;
   std::shared_ptr<bool> deleted;
};

// Definition for multi-map of consumers
typedef std::map<std::string, std::set<DtSettingsConsumer> > DtSettingsConsumersMultiMap;

// Definition for map of DtSettingsObjects
typedef std::map<std::string, DtSettingsObject*> DtSettingsMap ;

#include "makSettingsManager/makSettingsManagerDefines.h"
class DT_DLL_makSettingsManager DtSettingsManager
{
public:   
   // Constructor
   DtSettingsManager(const std::string& filename);
 
   // Destructor
   ~DtSettingsManager();

   // Calls read()
   virtual void init();
   
   // Opens and parses the settings file
   virtual bool read();
   
   // Updates all settings objects via their associated producer functions and
   // then writes out the settings file.
   virtual bool write();

   // DtSettingsObjectFactory
   static DtSettingsObjectFactory* factory();
   static void setFactory(DtSettingsObjectFactory* factory);
   
   // \brief Returns a pointer to the named settings object from the map.
   // If the object does not exist but a producer has been registered for it,
   // a new instance of the object will be created and returned.
   // If the object has been read in from the settings file but does not yet 
   // have a producer associated with it, its value will still be returned.
   // If the object does not exist in the map and there is no producer
   // associated with it, null (0) is returned.
   // Note that the return type is const because clients should only write 
   // settings data via their DtSettingsProducerFcn which they register with
   // registerProducer. 
   virtual const DtSettingsObject* lookupSetting(const std::string& name);

   // Updates an existing DtSettingsObject from the one provided by using
   // its setFrom method. If there is no DtSettingsObject in the DtSettingsMap
   // whose name corresponds to the name of the object provided, or if their
   // types do not match, false is returned and the setting is left unchanged.
   virtual bool setSetting(const DtSettingsObject* settingsObject);

   // Returns the key list of the settings map.
   virtual std::list<std::string>  settingsMapKeys();

   // \brief Registers a producer function as the source for the given setting
   // Associates the given DtSettingsProducerFcn with the given settings name.
   // All three arguments are copied into a DtSettingsProducer which is stored
   // in myProducersMap.
   // Whenever lookupSetting is called, this function will be used to update
   // the settings object with the most current data from the producer before
   // it is returned to the caller. If a producer with the same name is
   // already registered in myProducersMap, the associated settings object
   // in mySettingsMap is no longer considered valid and will be deleted.
   virtual void registerProducer(const std::string& type, const std::string& name,
      DtSettingsProducerFcn producerFcn, void* usr = 0);
   virtual void unregisterProducer(const std::string& type, const std::string& name,
      DtSettingsProducerFcn producerFcn, void* usr = 0);

   // DtSettingsConsumerFcn's are called whenever a named DtSettingsObject
   // changes. The arguments are copied into a DtSettingsConsumer used to
   // update the myConsumersMultiMap. 
   // @{
   virtual void registerConsumer(const std::string& name,
      DtSettingsConsumerFcn consumerFcn, void* usr = 0);  
   virtual void unregisterConsumer(const std::string& name,
      DtSettingsConsumerFcn consumerFcn, void* usr = 0);
   // @}

   // Registers an independent setting that does not have an associated
   // producer function. Independent settings are generally only used when
   // a given setting will never be associated with other settings grouped
   // into a subclass of DtSettingsObject.
   // @{
   virtual void addIndependentBool(const std::string& name, bool value);
   virtual void addIndependentInt(const std::string& name, int value);
   virtual void addIndependentDouble(const std::string& name, double value);
   virtual void addIndependentString(const std::string& name, const std::string& value);
   // @}

protected:
   // Settings file to read/write
   std::string myFilename;
   
   // Map of DtSettingsObjects
   DtSettingsMap mySettingsMap;
   
   // Map of DtSettingsProducers
   DtSettingsProducersMap myProducersMap;
   
   // Map of DtSettingsConsumers
   DtSettingsConsumersMultiMap myConsumersMultiMap;
   
   // DtSettingsObjectFactory
   static DtSettingsObjectFactory* theSettingsObjectFactory;

   tbb::mutex myConsumerMutex;
   std::recursive_mutex myProducerMutex;
};