framework/inc/threadhelp/resetableguard.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef __FRAMEWORK_THREADHELP_RESETABLEGUARD_HXX_
  21 #define __FRAMEWORK_THREADHELP_RESETABLEGUARD_HXX_
  22
  23 #include <threadhelp/inoncopyable.h>
  24 #include <framework/imutex.hxx>
  25
  26 #include <sal/types.h>
  27
  28
  29 namespace framework{
  30
  31 /*-************************************************************************************************************//**
  32     @short          implement a guard for implementing save thread access
  33     @descr          These guard has an additional feature to well known one ::osl::Guard.
  34                     You can lock() and unlock() it very often!
  35                     A set bool flag inside protect this implementation against multiple lock() calls
  36                     without any unlock()! So the increasing of guarded mutex couldn't be greater then 1 ...
  37
  38     @attention      a) To prevent us against wrong using, the default ctor, copy ctor and the =operator are maked private!
  39                     b) Use interface "IMutex" of set LockHelper only - because we must support an exclusiv locking.
  40                        Interface "IRWLock" should be used by special guard implementations ... like "ReadGuard" or "WriteGuard"!
  41
  42     @implements     -
  43     @base           INonCopyable
  44
  45     @devstatus      ready to use
  46 *//*-*************************************************************************************************************/
  47 class ResetableGuard : private INonCopyable
  48 {
  49     //-------------------------------------------------------------------------------------------------------------
  50     //  public methods
  51     //-------------------------------------------------------------------------------------------------------------
  52     public:
  53
  54         /*-****************************************************************************************************//**
  55             @short      ctors
  56             @descr      Use these ctor methods to initialize the guard right.
  57                         Given lock reference must be valid - otherwise crashes could occure!
  58
  59             @seealso    -
  60
  61             @param      "pLock", pointer to lock helper of user
  62             @param      "rLock", reference to lock helper of user
  63             @return     -
  64
  65             @onerror    -
  66         *//*-*****************************************************************************************************/
  67         inline ResetableGuard( IMutex* pLock )
  68             :   m_pLock    ( pLock     )
  69             ,   m_bLocked  ( sal_False )
  70         {
  71             lock();
  72         }
  73
  74         //*********************************************************************************************************
  75         inline ResetableGuard( IMutex& rLock )
  76             :   m_pLock    ( &rLock    )
  77             ,   m_bLocked  ( sal_False )
  78         {
  79             lock();
  80         }
  81
  82         /*-****************************************************************************************************//**
  83             @short      dtor
  84             @descr      We must release set mutex if programmer forget it ...
  85
  86             @seealso    -
  87
  88             @param      -
  89             @return     -
  90
  91             @onerror    -
  92         *//*-*****************************************************************************************************/
  93         inline ~ResetableGuard()
  94         {
  95             unlock();
  96         }
  97
  98         /*-****************************************************************************************************//**
  99             @short      enable/disable the lock
 100             @descr      Use this methods to lock or unlock the mutex.
 101                         You can do it so often you wish to do that ...
 102
 103             @attention  We use another member to prevent us against multiple acquire calls of the same guard
 104                         without suitable release calls!
 105                         You don't must protect access at these bool member by using an own mutex ....
 106                         because nobody use the same guard instance from different threads!
 107                         It will be a function-local object every time.
 108
 109             @seealso    -
 110
 111             @param      -
 112             @return     -
 113
 114             @onerror    -
 115         *//*-*****************************************************************************************************/
 116         inline void lock()
 117         {
 118             if( m_bLocked == sal_False )
 119             {
 120                 m_pLock->acquire();
 121                 m_bLocked = sal_True;
 122             }
 123         }
 124
 125         //*********************************************************************************************************
 126         inline void unlock()
 127         {
 128             if( m_bLocked == sal_True )
 129             {
 130                 m_pLock->release();
 131                 m_bLocked = sal_False;
 132             }
 133         }
 134
 135     //-------------------------------------------------------------------------------------------------------------
 136     //  private methods
 137     //-------------------------------------------------------------------------------------------------------------
 138     private:
 139
 140         /*-****************************************************************************************************//**
 141             @short      disable using of these functions!
 142             @descr      It's not allowed to use this methods. Different problem can occure otherwise.
 143                         Thats why we disable it by make it private.
 144
 145             @seealso    other ctor
 146
 147             @param      -
 148             @return     -
 149
 150             @onerror    -
 151         *//*-*****************************************************************************************************/
 152         ResetableGuard();
 153
 154     //-------------------------------------------------------------------------------------------------------------
 155     //  private member
 156     //-------------------------------------------------------------------------------------------------------------
 157     private:
 158
 159         IMutex*         m_pLock     ;   /// pointer to safed lock member of user
 160         sal_Bool        m_bLocked   ;   /// protection against multiple lock() calls without unlock()
 161
 162 };      //  class ResetableGuard
 163
 164 }       //  namespace framework
 165
 166 #endif  //  #ifndef __FRAMEWORK_THREADHELP_RESETABLEGUARD_HXX_
 167
 168 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */