framework/inc/threadhelp/lockhelper.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: lockhelper.hxx,v $
  10  * $Revision: 1.5 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __FRAMEWORK_THREADHELP_LOCKHELPER_HXX_
  32 #define __FRAMEWORK_THREADHELP_LOCKHELPER_HXX_
  33
  34 //_________________________________________________________________________________________________________________
  35 //      my own includes
  36 //_________________________________________________________________________________________________________________
  37
  38 #include <threadhelp/inoncopyable.h>
  39 #include <threadhelp/imutex.h>
  40 #include <threadhelp/irwlock.h>
  41 #include <threadhelp/fairrwlock.hxx>
  42
  43 //_________________________________________________________________________________________________________________
  44 //      interface includes
  45 //_________________________________________________________________________________________________________________
  46
  47 //_________________________________________________________________________________________________________________
  48 //      other includes
  49 //_________________________________________________________________________________________________________________
  50 #include <osl/mutex.hxx>
  51 #include <vos/mutex.hxx>
  52
  53 //_________________________________________________________________________________________________________________
  54 //      namespace
  55 //_________________________________________________________________________________________________________________
  56
  57 namespace framework{
  58
  59 //_________________________________________________________________________________________________________________
  60 //      const
  61 //_________________________________________________________________________________________________________________
  62
  63 /*-************************************************************************************************************//**
  64     @descr          If you use a lock or mutex as a member of your class and whish to use it earlier then other ones
  65                     you should have a look on this implementation. You must use it as the first base class
  66                     of your implementation - because base classes are initialized by his order and before your
  67                     member! Thats why ist a good place to declare your thread help member so.
  68 *//*-*************************************************************************************************************/
  69 enum ELockType
  70 {
  71     E_NOTHING       = 0 ,
  72     E_OWNMUTEX      = 1 ,
  73     E_SOLARMUTEX    = 2 ,
  74     E_FAIRRWLOCK    = 3
  75 };
  76
  77 #define ENVVAR_LOCKTYPE     DECLARE_ASCII("LOCKTYPE_FRAMEWORK")
  78 #define FALLBACK_LOCKTYPE   E_SOLARMUTEX
  79
  80 //_________________________________________________________________________________________________________________
  81 //      declarations
  82 //_________________________________________________________________________________________________________________
  83
  84 /*-************************************************************************************************************//**
  85     @short          helper to set right lock in right situation
  86     @descr          This helper support different types of locking:
  87                         a)  no locks - transparent for user!
  88                             This could be usefull for simluation or single threaded environments!
  89                         b)  own mutex
  90                             An object use his own osl-mutex to be threadsafe. Usefull for easy and exclusiv locking.
  91                         c)  solar mutex
  92                             An object use our solar mutex and will be a part of a greater safed "threadsafe code block".
  93                             Could be usefull for simulation and testing of higher modules!
  94                         d)  fair rw-lock
  95                             An object use an implementation of a fair rw-lock. This increase granularity of t hreadsafe mechanism
  96                             and should be used for high performance threadsafe code!
  97
  98     @attention      We support two interfaces - "IMutex" and "IRWLock". Don't mix using of it!
  99                     A guard implementation should use one interface only!
 100
 101     @implements     IMutex
 102     @implements     IRWLock
 103
 104     @base           INonCopyable
 105                     IMutex
 106                     IRWLock
 107
 108     @devstatus      draft
 109 *//*-*************************************************************************************************************/
 110 class LockHelper : public  IMutex
 111                  , public  IRWLock
 112                  , private INonCopyable
 113 {
 114     //-------------------------------------------------------------------------------------------------------------
 115     //  public methods
 116     //-------------------------------------------------------------------------------------------------------------
 117     public:
 118
 119         //-------------------------------------------------------------------------------------------------------------
 120         //  ctor/dtor
 121         //-------------------------------------------------------------------------------------------------------------
 122                  LockHelper( ::vos::IMutex* pSolarMutex = NULL );
 123         virtual ~LockHelper(                                   );
 124
 125         //-------------------------------------------------------------------------------------------------------------
 126         //  interface ::framework::IMutex
 127         //-------------------------------------------------------------------------------------------------------------
 128         virtual void acquire();
 129         virtual void release();
 130
 131         //-------------------------------------------------------------------------------------------------------------
 132         //  interface ::framework::IRWLock
 133         //-------------------------------------------------------------------------------------------------------------
 134         virtual void acquireReadAccess   ();
 135         virtual void releaseReadAccess   ();
 136         virtual void acquireWriteAccess  ();
 137         virtual void releaseWriteAccess  ();
 138         virtual void downgradeWriteAccess();
 139
 140         //-------------------------------------------------------------------------------------------------------------
 141         //  something else
 142         //-------------------------------------------------------------------------------------------------------------
 143         static LockHelper&  getGlobalLock       ( ::vos::IMutex* pSolarMutex = NULL );
 144         ::osl::Mutex&       getShareableOslMutex(                                   );
 145
 146     //-------------------------------------------------------------------------------------------------------------
 147     //  private methods
 148     //-------------------------------------------------------------------------------------------------------------
 149     private:
 150
 151         static ELockType& implts_getLockType();
 152
 153     //-------------------------------------------------------------------------------------------------------------
 154     //  private member
 155     //  a) Make some member mutable for using in const functions!
 156     //  b) "m_eLockType" define, which of follow members is used!
 157     //     You can use "m_pFairRWLock" as a fair rw-lock (multiple reader / one writer / looks for incoming order of threads too) ...
 158     //     or you can use a normal osl mutex ("m_pOwnMutex") ...
 159     //     ... or the solarmuex as "m_pSolarMutex" (must be set from outside! because some components must be vcl-free!)
 160     //     ... but sometimes you need a shareable osl mutex!
 161     //     In this case you has some problems: i  ) If your lock type is set to E_OWNMUTEX => it's easy; you can use your member "m_pOwnMutex" - it's a osl mutex.
 162     //                                              Creation and using of "m_pShareableOslMutex" isn't neccessary!
 163     //                                         ii ) Otherwise you have no osl mutex ... so you must create "m_pShareableOslMutex" and use it twice!
 164     //                                              In this case you must lock two member everytime - "m_pShareableMutex" AND "m_pFairRWLock" or "m_pSolarMutex" or ...
 165     //                                              It isn't realy fine - but the only possible way.
 166     //                                         iii) There exist another special case - E_NOTHING is set! Then we should create this shareable mutex ...
 167     //                                              nad you can use it ... but this implmentation ignore it.
 168     //-------------------------------------------------------------------------------------------------------------
 169     private:
 170
 171         ELockType               m_eLockType             ;
 172
 173         mutable FairRWLock*     m_pFairRWLock           ;
 174         mutable ::osl::Mutex*   m_pOwnMutex             ;
 175         mutable ::vos::IMutex*  m_pSolarMutex           ;
 176         mutable ::osl::Mutex*   m_pShareableOslMutex    ;
 177         mutable sal_Bool        m_bDummySolarMutex      ;
 178 };
 179
 180 }               //      namespace framework
 181
 182 #endif  //  #ifndef __FRAMEWORK_THREADHELP_LOCKHELPER_HXX_