/[svn]/linuxsampler/trunk/src/common/SynchronizedConfig.h

Diff of /linuxsampler/trunk/src/common/SynchronizedConfig.h

Parent Directory | Revision Log | View Patch Patch

-revision 1887 by persson,
Sat Apr 18 08:17:16 2009 UTC
+revision 2500 by schoenebeck,
Fri Jan 10 12:20:05 2014 UTC
 Line 1
  /***************************************************************************
   *                                                                         *
-  *   Copyright (C) 2006-2009 Andreas Persson                               *
+  *   Copyright (C) 2006-2014 Andreas Persson                               *
   *                                                                         *
   *   This program is free software; you can redistribute it and/or modify  *
   *   it under the terms of the GNU General Public License as published by  *
 Line 24
  #include <set>
  #include <unistd.h>
  #include "lsatomic.h"
+ #include "Mutex.h"
  namespace LinuxSampler {
      /**
-      * Thread safe management of configuration data, where the data is
+      * Thread-safe management of configuration data, where the data is
       * updated by a single non real time thread and read by a number
       * of real time threads.
       *
-Line 46 
 namespace LinuxSampler {
+Line 47 
 namespace LinuxSampler {
       * the data to be read, and Unlock() must be called when finished
       * reading the data. (Neither Lock nor Unlock will block the real
       * time thread, or use any system calls.)
+      *
+      * Note that the non real time side isn't safe for concurrent
+      * access, so if there are multiple non real time threads that
+      * update the configuration data, a mutex has to be used.
+      *
+      * Implementation note: the memory order parameters and fences are
+      * very carefully chosen to make the code fast but still safe for
+      * memory access reordering made by the CPU.
       */
      template<class T>
      class SynchronizedConfig {
-Line 65 
 namespace LinuxSampler {
+Line 74 
 namespace LinuxSampler {
                       *          object to be read by the real time
                       *          thread
                       */
-                     const T& Lock() {
+                     /*const*/ T& Lock() { //TODO const currently commented for the DoubleBuffer usage below
                          lock.store(lockCount += 2, memory_order_relaxed);
                          atomic_thread_fence(memory_order_seq_cst);
-                         return parent.config[parent.indexAtomic.load(
+                         return parent->config[parent->indexAtomic.load(
                                  memory_order_acquire)];
                      }
-Line 85 
 namespace LinuxSampler {
+Line 94 
 namespace LinuxSampler {
                      }
                      Reader(SynchronizedConfig& config);
-                     ~Reader();
+                     Reader(SynchronizedConfig* config);
+                     virtual ~Reader();
                  private:
                      friend class SynchronizedConfig;
-                     SynchronizedConfig& parent;
+                     SynchronizedConfig* parent;
                      int lockCount; // increased in every Lock(),
                                     // lowest bit is always set.
                      atomic<int> lock; // equals lockCount when inside
-Line 113 
 namespace LinuxSampler {
+Line 123 
 namespace LinuxSampler {
              T& GetConfigForUpdate();
              /**
+              * Get the data on update side <b>unprotected</b>, that is
+              * <b>without</b> locking or any means of synchronizations.
+              *
+              * Due to its nature this must only be called for read access and
+              * you have to make sure by yourself, that the data/member you
+              * access is really safe for concurrent read access (i.e. SGI's
+              * implementation of std::vector::size() would be safe).
+              *
+              * Only use this when you are absolutely sure what you are doing!
+              */
+             const T& GetUnsafeUpdateConfig() const {
+                 return config[updateIndex];
+             }
+             /**
               * Atomically switch the newly updated configuration
               * object with the one used by the real time thread, then
               * wait for the real time thread to finish working with
-Line 180 
 namespace LinuxSampler {
+Line 205 
 namespace LinuxSampler {
      template <class T>
      SynchronizedConfig<T>::Reader::Reader(SynchronizedConfig& config) :
+         parent(&config), lock(0), lockCount(1) {
+         parent->readers.insert(this);
+     }
+     template <class T>
+     SynchronizedConfig<T>::Reader::Reader(SynchronizedConfig* config) :
          parent(config), lock(0), lockCount(1) {
-         parent.readers.insert(this);
+         parent->readers.insert(this);
      }
      template <class T>
      SynchronizedConfig<T>::Reader::~Reader() {
-         parent.readers.erase(this);
+         parent->readers.erase(this);
      }
+     // ----- Convenience classes on top of SynchronizedConfig ----
+     /**
+      * Base interface class for classes that implement synchronization of data
+      * shared between multiple threads.
+      */
+     template<class T>
+     class Synchronizer {
+     public:
+         /**
+          * Signal intention to enter a synchronized code block. Depending
+          * on the actual implementation, this call may block the calling
+          * thread until it is safe to actually use the protected data. After
+          * this call returns, it is safe for the calling thread to access and
+          * modify the shared data. As soon as the thread is done with accessing
+          * the shared data, it MUST call endSync().
+          *
+          * @return the shared protected data
+          */
+         virtual void beginSync() = 0; //TODO: or call it lock() instead ?
+         /**
+          * Retrieve reference to critical, shared data. This method shall be
+          * called between a beginSync() and endSync() call pair, to be sure
+          * that shared data can be accessed safely.
+          */
+         virtual T& syncedData() = 0;
+         /**
+          * Signal that the synchronized code block has been left. Depending
+          * on the actual implementation, this call may block the calling
+          * thread for a certain amount of time.
+          */
+         virtual void endSync() = 0; //TODO: or call it unlock() instead ?
+     };
+     /**
+      * Wraps as a kind of pointer class some data object shared with other
+      * threads, to protect / synchronize the shared data against
+      * undeterministic concurrent access. It does so by locking the shared
+      * data in the Sync constructor and unlocking the shared data in the Sync
+      * destructor. Accordingly it can always be considered safe to access the
+      * shared data during the whole life time of the Sync object. Due to
+      * this design, a Sync object MUST only be accessed and destroyed
+      * by exactly one and the same thread which created that same Sync object.
+      */
+     template<class T>
+     class Sync {
+     public:
+         Sync(Synchronizer<T>* syncer) {
+             this->syncer = syncer;
+             syncer->beginSync();
+         }
+         virtual ~Sync() {
+             syncer->endSync();
+         }
+         /*Sync& operator =(const Sync& arg) {
+             *this->data = *arg.data;
+             return *this;
+         }*/
+         /*Sync& operator =(const T& arg) {
+             *this->data = arg;
+             return *this;
+         }*/
+         const T& operator *() const { return syncer->syncedData(); }
+         T&       operator *()       { return syncer->syncedData(); }
+         const T* operator ->() const { return &syncer->syncedData(); }
+         T*       operator ->()       { return &syncer->syncedData(); }
+     private:
+         Synchronizer<T>* syncer; ///< Points to the object that shall be responsible to protect the shared data.
+     };
+     /**
+      * BackBuffer object to be accessed by multiple non-real-time threads.
+      *
+      * Since a back buffer is designed for being accessed by non-real-time
+      * threads, its methods involved may block the calling thread for a long
+      * amount of time.
+      */
+     template<class T>
+     class BackBuffer : public SynchronizedConfig<T>, public Synchronizer<T> {
+     public:
+         virtual void beginSync() OVERRIDE {
+             mutex.Lock();
+         }
+         virtual T& syncedData() OVERRIDE {
+             return SynchronizedConfig<T>::GetConfigForUpdate();
+         }
+         virtual void endSync() OVERRIDE {
+             const T clone = SynchronizedConfig<T>::GetConfigForUpdate();
+             SynchronizedConfig<T>::SwitchConfig() = clone;
+             mutex.Unlock();
+         }
+         const T& unsafeData() const {
+             return SynchronizedConfig<T>::GetUnsafeUpdateConfig();
+         }
+     private:
+         Mutex mutex;
+     };
+     /**
+      * FrontBuffer object to be accessed by exactly ONE real-time thread.
+      * A front buffer is designed for real-time access. That is, its methods
+      * involved are lock free, that is none of them block the calling thread
+      * for a long time.
+      *
+      * If you need the front buffer's data to be accessed by multiple real-time
+      * threads instead, then you need to create multiple instances of the
+      * FrontBuffer object. They would point to the same data, but ensure
+      * protection against concurrent access among those real-time threads.
+      */
+     template<class T>
+     class FrontBuffer : public SynchronizedConfig<T>::Reader, public Synchronizer<T> {
+     public:
+         FrontBuffer(BackBuffer<T>& backBuffer) : SynchronizedConfig<T>::Reader::Reader(&backBuffer) {}
+         virtual void beginSync() OVERRIDE { data = &SynchronizedConfig<T>::Reader::Lock(); }
+         virtual T& syncedData() OVERRIDE { return *data; }
+         virtual void endSync() OVERRIDE { SynchronizedConfig<T>::Reader::Unlock(); }
+     private:
+         T* data;
+     };
+     /**
+      * Synchronization / protection of data shared between multiple threads by
+      * using a double buffer design. The FrontBuffer is meant to be accessed by
+      * exactly one real-time thread, whereas the BackBuffer is meant to be
+      * accessed by multiple non-real-time threads.
+      *
+      * This class is built on top of SynchronizedConfig as convenient API to
+      * reduce the amount of code required to protect shared data.
+      */
+     template<class T>
+     class DoubleBuffer {
+     public:
+         DoubleBuffer() : m_front(m_back) {}
+         /**
+          * Synchronized access of the shared data for EXACTLY one real-time
+          * thread.
+          *
+          * The returned shared data is wrapped into a Sync object, which
+          * ensures that the shared data is protected against concurrent access
+          * during the life time of the returned Sync object.
+          */
+         inline
+         Sync<T> front() { return Sync<T>(&m_front); }
+         /**
+          * Synchronized access of the shared data for multiple non-real-time
+          * threads.
+          *
+          * The returned shared data is wrapped into a Sync object, which
+          * ensures that the shared data is protected against concurrent access
+          * during the life time of the returned Sync object.
+          *
+          * As soon as the returned Sync object is destroyed, the FrontBuffer
+          * will automatically be exchanged by the hereby modified BackBuffer.
+          */
+         inline
+         Sync<T> back() { return Sync<T>(&m_back); }
+         /**
+          * Get the backbuffer data <b>unprotected</b>, that is <b>without</b>
+          * locking or any means of synchronizations.
+          *
+          * Due to its nature this must only be called for read access and
+          * you have to make sure by yourself, that the data/member you
+          * access is really safe for concurrent read access (i.e. SGI's
+          * implementation of std::vector::size() would be safe).
+          *
+          * Only use this when you are absolutely sure what you are doing!
+          */
+         const T& unsafeBack() const { return m_back.unsafeData(); }
+     private:
+         BackBuffer<T> m_back; ///< Back buffer (non real-time thread(s) side).
+         FrontBuffer<T> m_front; ///< Front buffer (real-time thread side).
+     };
  } // namespace LinuxSampler

 Legend:



Removed from v.1887
 


changed lines


 
Added in v.2500
 Legend:



Removed from v.1887
 


changed lines


 
Added in v.2500
-Removed from v.1887
+Added in v.2500

	ViewVC Help
Powered by ViewVC