ThreadingPolicies.h

Go to the documentation of this file.

/*  Copyright (C) 2008 National Institute For Space Research (INPE) - Brazil.
 
    This file is part of the TerraLib - a Framework for building GIS enabled applications.
 
    TerraLib is free software: you can redistribute it and/or modify
    it under the terms of the GNU Lesser General Public License as published by
    the Free Software Foundation, either version 3 of the License,
    or (at your option) any later version.
 
    TerraLib is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    GNU Lesser General Public License for more details.
 
    You should have received a copy of the GNU Lesser General Public License
    along with TerraLib. See COPYING. If not, write to
    TerraLib Team at <terralib-team@terralib.org>.
 */
 
/*!
  \file terralib/common/ThreadingPolicies.h
 
  \brief Threading policies that can be applied to TerraLib classes that need some synchronization schema.
 
  \ingroup common
*/
 
#ifndef __TERRALIB_COMMON_INTERNAL_THREADINGPOLICIES_H
#define __TERRALIB_COMMON_INTERNAL_THREADINGPOLICIES_H
 
// BOOST
#include <boost/noncopyable.hpp>
#include <boost/thread.hpp>
 
#define TE_SINGLETHREADING 1
#define TE_MULTITHREADING  2
 
//#define TE_THREADING_POLICIES TE_SINGLETHREADING
 
#ifndef TE_THREADING_POLICIES
  #define TE_THREADING_POLICIES TE_MULTITHREADING
#endif
 
#if !defined TE_DEFAULT_MUTEX_POLICY
  #define TE_DEFAULT_MUTEX_POLICY  ::boost::mutex
#endif
 
#if !defined TE_DEFAULT_LOCK_READING_POLICY
  #define TE_DEFAULT_LOCK_READING_POLICY  ::boost::lock_guard<TE_DEFAULT_MUTEX_POLICY>
#endif
 
#if !defined TE_DEFAULT_LOCK_WRITING_POLICY
  #define TE_DEFAULT_LOCK_WRITING_POLICY  ::boost::lock_guard<TE_DEFAULT_MUTEX_POLICY>
#endif
 
namespace te
{
  namespace common
  {
    /*!
      \class NonLockable
 
      \brief This policy doesn't actually perform a lock.
 
      Requirements on types:
      <ul>
      <li>NONE. </li>
      </ul>
    */
    template<class Host,
             class MutexPolicy = void,
             class LockReadingPolicy = void,
             class LockWritingPolicy = void> class NonLockable
    {
      public:
 
        typedef MutexPolicy MutexPolicyType;
        typedef LockReadingPolicy LockReadingPolicyType;
        typedef LockWritingPolicy LockWritingPolicyType;
 
        /*!
          \class NonLockingPolicy
 
          \brief This class doesn't truelly acquire a lock over the host object/class.
 
          Requirements on LockingPolicy type:
          <ul>
          <li>NONE</li>
          </ul>
        */
        template<class LockingPolicy> class NonLockingPolicy
        {
          public:
 
            /*! \brief Constructor to keep the semantics of class-level lock. */
            explicit NonLockingPolicy()
            {
            }
 
            /*!
              \brief Constructor.
              
              \param host The host object that uses the lock semantics.
            */
            explicit NonLockingPolicy(const Host&)
            {              
            }
 
            /*!
              \brief Constructor.
              
              \param host A pointer to the host object that uses the lock semantics.
            */
            explicit NonLockingPolicy(const Host*)
            {
            }
 
            /*! \brief Destructor. */
            ~NonLockingPolicy()
            {
            }
 
          private:
 
            NonLockingPolicy(const NonLockingPolicy&);
            NonLockingPolicy& operator=(const NonLockingPolicy&);
        };
 
        typedef volatile Host VolatileType;
        typedef NonLockingPolicy<LockReadingPolicy> LockRead;
        typedef NonLockingPolicy<LockWritingPolicy> LockWrite;
    };
 
#if TE_THREADING_POLICIES == TE_MULTITHREADING
 
    /*!
      \class ObjectLevelLockable
 
      \brief This policy assures an object-level locking scheme for a derived class.
 
      Requirements on types:
      <ul>
      <li>Host: is the type of the derived class from this policy. </li>
      <li>MutexPolicy: any type that have a lock and unlock method. When using boost it can be one of the follwoing: boost::mutex, bost::timed_mutex, bost::recursive_mutex, boost::recursive_timed_mutex or boost::shared_mutex.</li>
      <li>The LockReadingPolicy and LockWritingPolicy may be: boost::lock_guard, boost::unique_lock, boost::shared_lock, boost::upgrade_lock, boost::upgrade_to_unique_lock</li>
      </ul>
    */
    template<class Host,
             class MutexPolicy = TE_DEFAULT_MUTEX_POLICY,
             class LockReadingPolicy = TE_DEFAULT_LOCK_READING_POLICY,
             class LockWritingPolicy = TE_DEFAULT_LOCK_WRITING_POLICY> class ObjectLevelLockable
    {
      public:
 
        /*!
          \class ObjectLevelLockingPolicy
 
          \brief This class acquires a lock over the host object.
 
          Requirements on type LockingPolicy:
          <ul>
          <li>it must be one of: boost::lock_guard, boost::unique_lock, boost::shared_lock, boost::upgrade_lock, boost::upgrade_to_unique_lock</li>
          </ul>
        */
        template<class LockingPolicy> class ObjectLevelLockingPolicy
        {
          public:
 
            /*!
              \brief Through this constructor the host object will be locked.
              
              \param host The host object to be locked.
            */
            explicit ObjectLevelLockingPolicy(const Host& host)
              : m_lock(host.m_mtx)
            {              
            }
 
            /*!
              \brief Through this constructor the pointed host object will be locked.
              
              \param host A pointer to the host object to be locked.
            */
            explicit ObjectLevelLockingPolicy(const Host* host)
              :  m_lock(host->m_mtx)
            {
            }
 
            /*! \brief Destructor. */
            ~ObjectLevelLockingPolicy()
            {
            }
 
          private:
 
            ObjectLevelLockingPolicy(const ObjectLevelLockingPolicy&);
            ObjectLevelLockingPolicy& operator=(const ObjectLevelLockingPolicy&);
 
          private:
 
            LockingPolicy m_lock; //!< lock policy.
        };
 
        typedef volatile Host VolatileType;
        typedef ObjectLevelLockingPolicy<LockReadingPolicy> LockRead;
        typedef ObjectLevelLockingPolicy<LockWritingPolicy> LockWrite;
 
        friend class ObjectLevelLockingPolicy<LockReadingPolicy>;
        friend class ObjectLevelLockingPolicy<LockWritingPolicy>;
 
      protected:
 
        /*! \brief Default constructor. */
        ObjectLevelLockable()
          : m_mtx()
        {
        }
 
        /*! \brief Copy constructor. */
        ObjectLevelLockable(const ObjectLevelLockable&)
          : m_mtx()
        {
        }
 
        /*! \brief Destructor. */
        ~ObjectLevelLockable()
        {
        }
 
      private:
 
        mutable MutexPolicy m_mtx;  //!< The mutex used to control the object lock.
    };
 
    /*!
      \class ClassLevelLockable
 
      \brief This policy assures a class-level locking scheme for a derived class.
 
      Requirements on types:
      <ul>
      <li>Host: is the type of the derived class from this policy. </li>
      <li>MutexPolicy: any type that have a lock and unlock method. When using boost it can be one of the follwoing: boost::mutex, bost::timed_mutex, bost::recursive_mutex, boost::recursive_timed_mutex or boost::shared_mutex.</li>
      <li>The LockReadingPolicy and LockWritingPolicy may be: boost::lock_guard, boost::unique_lock, boost::shared_lock, boost::upgrade_lock, boost::upgrade_to_unique_lock</li>
      </ul>
    */
    template<class Host,
             class MutexPolicy = TE_DEFAULT_MUTEX_POLICY,
             class LockReadingPolicy = TE_DEFAULT_LOCK_READING_POLICY,
             class LockWritingPolicy = TE_DEFAULT_LOCK_WRITING_POLICY> class ClassLevelLockable
    {
      public:
 
        /*!
          \class ClassLevelLockingPolicy
 
          \brief This class acquires a lock over the object class.
 
          Requirements on type LockingPolicy:
          <ul>
          <li>it must be one of: boost::lock_guard, boost::unique_lock, boost::shared_lock, boost::upgrade_lock, boost::upgrade_to_unique_lock</li>
          </ul>
        */
        template<class LockingPolicy> class ClassLevelLockingPolicy : public boost::noncopyable
        {
          public:
 
            /*! \brief Default constructor. */
            explicit ClassLevelLockingPolicy()
              : m_lock(Host::sm_mtx)
            {
            }
 
            /*! \brief Constructor to keep the semantics of object-level lock. */
            explicit ClassLevelLockingPolicy(const Host& host)
              : m_lock(Host::sm_mtx)
            {              
            }
 
            /*! \brief Constructor to keep the semantics of object-level lock. */
            explicit ClassLevelLockingPolicy(const Host* host)
              : m_lock(Host::sm_mtx)
            {
            }
 
            /*! \brief Destructor. */
            ~ClassLevelLockingPolicy()
            {
            }
 
          private:
 
            ClassLevelLockingPolicy(const ClassLevelLockingPolicy&);
            ClassLevelLockingPolicy& operator=(const ClassLevelLockingPolicy&);
 
          private:
 
            LockingPolicy m_lock; //!< lock policy.
        };
 
        typedef volatile Host VolatileType;
        typedef ClassLevelLockingPolicy<LockReadingPolicy> LockRead;
        typedef ClassLevelLockingPolicy<LockWritingPolicy> LockWrite;
 
        friend class ClassLevelLockingPolicy<LockReadingPolicy>;
        friend class ClassLevelLockingPolicy<LockWritingPolicy>;
 
      private:
 
        static MutexPolicy sm_mtx;  //!< The mutex used to control the class lock.        
    };
 
    template<class Host, class MutexPolicy, class LockReadingPolicy, class LockWritingPolicy> MutexPolicy ClassLevelLockable<Host, MutexPolicy, LockReadingPolicy, LockWritingPolicy>::sm_mtx;
 
#else // TE_THREADING_POLICIES == TE_SINGLETHREADING
  template<class Host,
           class MutexPolicy = void,
           class LockReadingPolicy = void,
           class LockWritingPolicy = void> class ObjectLevelLockable : public NonLockable<ObjectLevelLockable<Host, MutexPolicy, LockReadingPolicy, LockWritingPolicy>, MutexPolicy, LockReadingPolicy, LockWritingPolicy>
  {
  };
 
  template<class Host,
           class MutexPolicy = TE_DEFAULT_MUTEX_POLICY,
           class LockReadingPolicy = TE_DEFAULT_LOCK_READING_POLICY,
           class LockWritingPolicy = TE_DEFAULT_LOCK_WRITING_POLICY> class ClassLevelLockable : public NonLockable<ClassLevelLockable<Host, MutexPolicy, LockReadingPolicy, LockWritingPolicy>, MutexPolicy, LockReadingPolicy, LockWritingPolicy>
  {
  };
 
#endif // TE_THREADING_POLICIES == TE_MULTITHREADING
 
  } // end namespace common
}   // end namespace te
 
#endif  // __TERRALIB_COMMON_INTERNAL_THREADINGPOLICIES_H