framework/inc/threadhelp/readguard.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: readguard.hxx,v $
  10  * $Revision: 1.6 $
  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_READGUARD_HXX_
  32 #define __FRAMEWORK_THREADHELP_READGUARD_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 #include <sal/types.h>
  53
  54 //_________________________________________________________________________________________________________________
  55 //      namespace
  56 //_________________________________________________________________________________________________________________
  57
  58 namespace framework{
  59
  60 //_________________________________________________________________________________________________________________
  61 //      const
  62 //_________________________________________________________________________________________________________________
  63
  64 //_________________________________________________________________________________________________________________
  65 //      declarations
  66 //_________________________________________________________________________________________________________________
  67
  68 /*-************************************************************************************************************//**
  69     @short          implement a guard to set read locks
  70     @descr                      This guard should be used to set a lock for reading object internal member.
  71                     Nobody can control it but don't use member after successfuly locking for writing!
  72                     We never need a own mutex to safe our internal member access - because
  73                     a guard is used as function-local member only. There exist no multithreaded access to it realy ...
  74
  75     @attention      a) To prevent us against wrong using, the default ctor, copy ctor and the =operator are maked private!
  76                     b) Use interface "IRWLock" of set LockHelper only - because we must support a finer granularity of locking.
  77                        Interface "IMutex" should be used by easier guard implementations ... like "ResetableGuard"!
  78
  79     @implements         -
  80     @base           INonCopyable
  81
  82     @devstatus          ready to use
  83 *//*-*************************************************************************************************************/
  84 class ReadGuard : private INonCopyable
  85 {
  86     //-------------------------------------------------------------------------------------------------------------
  87     //  public methods
  88     //-------------------------------------------------------------------------------------------------------------
  89     public:
  90
  91         /*-****************************************************************************************************//**
  92             @short      ctor
  93             @descr      These ctors initialize the guard with a reference to used lock member of object to protect.
  94                         Null isn't allowed as value!
  95
  96             @seealso    -
  97
  98             @param      "pLock" ,reference to used lock member of object to protect
  99             @param      "rLock" ,reference to used lock member of object to protect
 100             @return     -
 101
 102             @onerror    -
 103         *//*-*****************************************************************************************************/
 104         inline ReadGuard( IRWLock* pLock )
 105             :   m_pLock     ( pLock     )
 106             ,   m_bLocked   ( sal_False )
 107         {
 108             lock();
 109         }
 110
 111         //*********************************************************************************************************
 112         inline ReadGuard( IRWLock& rLock )
 113             :   m_pLock     ( &rLock    )
 114             ,   m_bLocked   ( sal_False )
 115         {
 116             lock();
 117         }
 118
 119         /*-****************************************************************************************************//**
 120             @short      dtor
 121             @descr      We unlock the used lock member automaticly if user forget it.
 122
 123             @seealso    -
 124
 125             @param      -
 126             @return     -
 127
 128             @onerror    -
 129         *//*-*****************************************************************************************************/
 130         inline ~ReadGuard()
 131         {
 132             unlock();
 133         }
 134
 135         /*-****************************************************************************************************//**
 136             @short      set read lock
 137             @descr      Call this method to set the read lock. The call will block till all current threads are synchronized!
 138
 139             @seealso    method unlock()
 140
 141             @param      -
 142             @return     -
 143
 144             @onerror    -
 145         *//*-*****************************************************************************************************/
 146         inline void lock()
 147         {
 148             if( m_bLocked == sal_False )
 149             {
 150                 m_pLock->acquireReadAccess();
 151                 m_bLocked = sal_True;
 152             }
 153         }
 154
 155         /*-****************************************************************************************************//**
 156             @short      unset read lock
 157             @descr      Call this method to unlock the rw-lock temp.!
 158                         Normaly we do it at dtor automaticly for you ...
 159
 160             @seealso    method lock()
 161
 162             @param      -
 163             @return     -
 164
 165             @onerror    -
 166         *//*-*****************************************************************************************************/
 167         inline void unlock()
 168         {
 169             if( m_bLocked == sal_True )
 170             {
 171                 m_pLock->releaseReadAccess();
 172                 m_bLocked = sal_False;
 173             }
 174         }
 175
 176     //-------------------------------------------------------------------------------------------------------------
 177     //  private methods
 178     //-------------------------------------------------------------------------------------------------------------
 179     private:
 180
 181         /*-****************************************************************************************************//**
 182             @short              disable using of these functions!
 183             @descr              It's not allowed to use this methods. Different problem can occure otherwise.
 184                         Thats why we disable it by make it private.
 185
 186             @seealso    other ctor
 187
 188             @param              -
 189             @return             -
 190
 191             @onerror    -
 192         *//*-*****************************************************************************************************/
 193         ReadGuard();
 194
 195     //-------------------------------------------------------------------------------------------------------------
 196     //  private member
 197     //-------------------------------------------------------------------------------------------------------------
 198     private:
 199
 200         IRWLock*    m_pLock     ;   /// reference to lock-member of protected object
 201         sal_Bool        m_bLocked       ;       /// protection against multiple lock calls without unlock!
 202
 203 };              //      class ReadGuard
 204
 205 }               //      namespace framework
 206
 207 #endif  //      #ifndef __FRAMEWORK_THREADHELP_READGUARD_HXX_