framework/inc/threadhelp/writeguard.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: writeguard.hxx,v $
  10  * $Revision: 1.7 $
  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_WRITEGUARD_HXX_
  32 #define __FRAMEWORK_THREADHELP_WRITEGUARD_HXX_
  33
  34 //_________________________________________________________________________________________________________________
  35 //      my own includes
  36 //_________________________________________________________________________________________________________________
  37
  38 #include <threadhelp/inoncopyable.h>
  39 #include <threadhelp/irwlock.h>
  40
  41 //#ifndef __FRAMEWORK_THREADHELP_THREADHELPBASE_HXX_
  42 //#include <threadhelp/threadhelpbase.hxx>
  43 //#endif
  44
  45 //_________________________________________________________________________________________________________________
  46 //      interface includes
  47 //_________________________________________________________________________________________________________________
  48
  49 //_________________________________________________________________________________________________________________
  50 //      other includes
  51 //_________________________________________________________________________________________________________________
  52
  53 //_________________________________________________________________________________________________________________
  54 //      namespace
  55 //_________________________________________________________________________________________________________________
  56
  57 namespace framework{
  58
  59 //_________________________________________________________________________________________________________________
  60 //      const
  61 //_________________________________________________________________________________________________________________
  62
  63 //_________________________________________________________________________________________________________________
  64 //      declarations
  65 //_________________________________________________________________________________________________________________
  66
  67 /*-************************************************************************************************************//**
  68     @short          implement a guard to set write locks
  69     @descr                      This guard should be used to set a lock for reading AND writing object internal member.
  70                     We never need a own mutex to safe our internal member access - because
  71                     a guard is used as function-local member only. There exist no multithreaded access to it realy ...
  72
  73     @attention      a) To prevent us against wrong using, the default ctor, copy ctor and the =operator are maked private!
  74                     b) Use interface "IRWLock" of set LockHelper only - because we must support a finer granularity of locking.
  75                        Interface "IMutex" should be used by easier guard implementations ... like "ResetableGuard"!
  76
  77     @implements         -
  78     @base           INonCopyable
  79
  80     @devstatus          ready to use
  81 *//*-*************************************************************************************************************/
  82 class WriteGuard : private INonCopyable
  83 {
  84     //-------------------------------------------------------------------------------------------------------------
  85     //  public methods
  86     //-------------------------------------------------------------------------------------------------------------
  87     public:
  88
  89         /*-****************************************************************************************************//**
  90             @short      ctor
  91             @descr      These ctors initialize the guard with a reference to used lock member of object to protect.
  92                         Null isn't allowed as value!
  93
  94             @seealso    -
  95
  96             @param      "pLock" ,reference to used lock member of object to protect
  97             @param      "rLock" ,reference to used lock member of object to protect
  98             @return     -
  99
 100             @onerror    -
 101         *//*-*****************************************************************************************************/
 102         inline WriteGuard( IRWLock* pLock )
 103             :   m_pLock ( pLock     )
 104             ,   m_eMode ( E_NOLOCK  )
 105         {
 106             lock();
 107         }
 108
 109         //*********************************************************************************************************
 110         inline WriteGuard( IRWLock& rLock )
 111             :   m_pLock ( &rLock    )
 112             ,   m_eMode ( E_NOLOCK  )
 113         {
 114             lock();
 115         }
 116
 117         /*-****************************************************************************************************//**
 118             @short      dtor
 119             @descr      We unlock the used lock member automaticly if user forget it.
 120
 121             @seealso    -
 122
 123             @param      -
 124             @return     -
 125
 126             @onerror    -
 127         *//*-*****************************************************************************************************/
 128         inline ~WriteGuard()
 129         {
 130             unlock();
 131         }
 132
 133         /*-****************************************************************************************************//**
 134             @short      set write lock
 135             @descr      Call this method to set the write lock. The call will block till all current threads are synchronized!
 136
 137             @seealso    method unlock()
 138
 139             @param      -
 140             @return     -
 141
 142             @onerror    -
 143         *//*-*****************************************************************************************************/
 144         inline void lock()
 145         {
 146             switch( m_eMode )
 147             {
 148                 case E_NOLOCK       :   {
 149                                             // Acquire write access and set return state.
 150                                             // Mode is set later if it was successful!
 151                                             m_pLock->acquireWriteAccess();
 152                                             m_eMode = E_WRITELOCK;
 153                                         }
 154                                         break;
 155                 case E_READLOCK     :   {
 156                                             // User has downgrade to read access before!
 157                                             // We must release it before we can set a new write access!
 158                                             m_pLock->releaseReadAccess();
 159                                             m_pLock->acquireWriteAccess();
 160                                             m_eMode = E_WRITELOCK;
 161                                         }
 162                                         break;
 163                 default:                break; // nothing to do
 164             }
 165         }
 166
 167         /*-****************************************************************************************************//**
 168             @short      unset write lock
 169             @descr      Call this method to unlock the rw-lock temp.!
 170                         Normaly we do it at dtor automaticly for you ...
 171
 172             @seealso    method lock()
 173
 174             @param      -
 175             @return     -
 176
 177             @onerror    -
 178         *//*-*****************************************************************************************************/
 179         inline void unlock()
 180         {
 181             switch( m_eMode )
 182             {
 183                 case E_READLOCK     :   {
 184                                             // User has downgraded to a read lock before!
 185                                             // => There isn't realy a write lock ...
 186                                             m_pLock->releaseReadAccess();
 187                                             m_eMode = E_NOLOCK;
 188                                         }
 189                                         break;
 190                 case E_WRITELOCK    :   {
 191                                             m_pLock->releaseWriteAccess();
 192                                             m_eMode = E_NOLOCK;
 193                                         }
 194                                         break;
 195                 default:                break; // nothing to do
 196             }
 197         }
 198
 199         /*-****************************************************************************************************//**
 200             @short      downgrade write access to read access without new blocking!
 201             @descr      If this write lock is set you can change it to a "read lock".
 202                         An "upgrade" is the same like new calling "lock()"!
 203
 204             @seealso    -
 205
 206             @param      -
 207             @return     -
 208
 209             @onerror    -
 210         *//*-*****************************************************************************************************/
 211         inline void downgrade()
 212         {
 213             if( m_eMode == E_WRITELOCK )
 214             {
 215                 m_pLock->downgradeWriteAccess();
 216                 m_eMode = E_READLOCK;
 217             }
 218         }
 219
 220         /*-****************************************************************************************************//**
 221             @short      return internal states
 222             @descr      For user they dont know what they are doing ...
 223
 224             @seealso    -
 225
 226             @param      -
 227             @return     Current set lock mode.
 228
 229             @onerror    No error should occure.
 230         *//*-*****************************************************************************************************/
 231         inline ELockMode getMode() const
 232         {
 233             return m_eMode;
 234         }
 235
 236     //-------------------------------------------------------------------------------------------------------------
 237     //  private methods
 238     //-------------------------------------------------------------------------------------------------------------
 239     private:
 240
 241         /*-****************************************************************************************************//**
 242             @short              disable using of these functions!
 243             @descr              It's not allowed to use this methods. Different problem can occure otherwise.
 244                         Thats why we disable it by make it private.
 245
 246             @seealso    other ctor
 247
 248             @param              -
 249             @return             -
 250
 251             @onerror    -
 252         *//*-*****************************************************************************************************/
 253         WriteGuard();
 254
 255     //-------------------------------------------------------------------------------------------------------------
 256     //  private member
 257     //-------------------------------------------------------------------------------------------------------------
 258     private:
 259
 260         IRWLock*    m_pLock ;   /// reference to lock-member of protected object
 261         ELockMode       m_eMode ;       /// protection against multiple lock calls without unlock and difference between supported lock modi
 262
 263 };              //      class WriteGuard
 264
 265 }       //  namespace framework
 266
 267 #endif  //      #ifndef __FRAMEWORK_THREADHELP_WRITEGUARD_HXX_