framework/inc/threadhelp/fairrwlock.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_FAIRRWLOCK_HXX_
  21 #define __FRAMEWORK_THREADHELP_FAIRRWLOCK_HXX_
  22
  23 #include <threadhelp/inoncopyable.h>
  24 #include <threadhelp/irwlock.h>
  25 #include <macros/debug.hxx>
  26
  27 #include <com/sun/star/uno/XInterface.hpp>
  28
  29 #include <osl/mutex.hxx>
  30 #include <osl/conditn.hxx>
  31
  32 namespace framework{
  33
  34 /*-************************************************************************************************************//**
  35     @short          implement a read/write lock with fairness between read/write accessors
  36     @descr          These implementation never should used as base class! Use it as a member every time.
  37                     Use ReadGuard and/or WriteGuard in your methods (which work with these lock)
  38                     to make your code threadsafe.
  39                     Fair means: All reading or writing threads are synchronized AND serialzed by using one
  40                     mutex. For reader this mutex is used to access internal variables of this lock only;
  41                     for writer this mutex is used to have an exclusiv access on your class member!
  42                     => It's a multi-reader/single-writer lock, which no preferred accessor.
  43
  44     @implements     IRWlock
  45     @base           INonCopyable
  46                     IRWLock
  47
  48     @devstatus      ready to use
  49 *//*-*************************************************************************************************************/
  50 class FairRWLock : public  IRWLock
  51                  , private INonCopyable
  52 {
  53     //-------------------------------------------------------------------------------------------------------------
  54     //  public methods
  55     //-------------------------------------------------------------------------------------------------------------
  56     public:
  57
  58         /*-****************************************************************************************************//**
  59             @short      standard ctor
  60             @descr      Initialize instance with right start values for correct working.
  61                         no reader could exist               =>  m_nReadCount   = 0
  62                         don't block first coming writer    =>  m_aWriteCondition.set()
  63
  64             @seealso    -
  65
  66             @param      -
  67             @return     -
  68
  69             @onerror    -
  70         *//*-*****************************************************************************************************/
  71         inline FairRWLock()
  72             : m_nReadCount( 0 )
  73         {
  74             m_aWriteCondition.set();
  75         }
  76
  77         inline virtual ~FairRWLock()
  78         {
  79         }
  80
  81         /*-****************************************************************************************************//**
  82             @interface  IRWLock
  83             @short      set lock for reading
  84             @descr      A guard should call this method to acquire read access on your member.
  85                         Writing isn't allowed then - but nobody could check it for you!
  86
  87             @seealso    method releaseReadAccess()
  88
  89             @param      -
  90             @return     -
  91
  92             @onerror    -
  93         *//*-*****************************************************************************************************/
  94         inline virtual void acquireReadAccess()
  95         {
  96             // Put call in "SERIALIZE"-queue!
  97             // After successfully acquiring this mutex we are alone ...
  98             ::osl::MutexGuard aSerializeGuard( m_aSerializer );
  99
 100             // ... but we should synchronize us with other reader!
 101             // May be - they will unregister himself by using releaseReadAccess()!
 102             ::osl::MutexGuard aAccessGuard( m_aAccessLock );
 103
 104             // Now we must register us as reader by increasing counter.
 105             // If this the first writer we must close door for possible writer.
 106             // Other reader don't look for this barrier - they work parallel to us!
 107             if( m_nReadCount == 0 )
 108             {
 109                 m_aWriteCondition.reset();
 110             }
 111             ++m_nReadCount;
 112         }
 113
 114         /*-****************************************************************************************************//**
 115             @interface  IRWLock
 116             @short      reset lock for reading
 117             @descr      A guard should call this method to release read access on your member.
 118
 119             @seealso    method acquireReadAccess()
 120
 121             @param      -
 122             @return     -
 123
 124             @onerror    -
 125         *//*-*****************************************************************************************************/
 126         inline virtual void releaseReadAccess()
 127         {
 128             // The access lock is enough at this point
 129             // because it's not allowed to wait for all reader or writer here!
 130             // That will cause a deadlock!
 131             ::osl::MutexGuard aAccessGuard( m_aAccessLock );
 132
 133             // Unregister as reader first!
 134             // Open writer barrier then if it was the last reader.
 135             --m_nReadCount;
 136             if( m_nReadCount == 0 )
 137             {
 138                 m_aWriteCondition.set();
 139             }
 140         }
 141
 142         /*-****************************************************************************************************//**
 143             @interface  IRWLock
 144             @short      set lock for writing
 145             @descr      A guard should call this method to acquire write access on your member.
 146                         Reading is allowed too - of course.
 147                         After successfully calling of this method you are the only writer.
 148
 149             @seealso    method releaseWriteAccess()
 150
 151             @param      -
 152             @return     -
 153
 154             @onerror    -
 155         *//*-*****************************************************************************************************/
 156         inline virtual void acquireWriteAccess()
 157         {
 158             // You have to stand in our serialize-queue till all reader
 159             // are registered (not for releasing them!) or writer finished their work!
 160             // Don't use a guard to do so - because you must hold the mutex till
 161             // you call releaseWriteAccess()!
 162             // After successfully acquiring you have to wait for current working reader.
 163             // Used condition will open by last gone reader object.
 164             m_aSerializer.acquire();
 165             m_aWriteCondition.wait();
 166         }
 167
 168         /*-****************************************************************************************************//**
 169             @interface  IRWLock
 170             @short      reset lock for writing
 171             @descr      A guard should call this method to release write access on your member.
 172
 173             @seealso    method acquireWriteAccess()
 174
 175             @param      -
 176             @return     -
 177
 178             @onerror    -
 179         *//*-*****************************************************************************************************/
 180         inline virtual void releaseWriteAccess()
 181         {
 182             // The only one you have to do here is to release
 183             // hold seriliaze-mutex. All other user of these instance are blocked
 184             // by these mutex!
 185             // You don't need any other mutex here - you are the only one in the moment!
 186
 187             m_aSerializer.release();
 188         }
 189
 190         /*-****************************************************************************************************//**
 191             @interface  IRWLock
 192             @short      downgrade a write access to a read access
 193             @descr      A guard should call this method to change a write to a read access.
 194                         New readers can work too - new writer are blocked!
 195
 196             @attention  Don't call this method if you are not a writer!
 197                         Results are not defined then ...
 198                         An upgrade can't be implemented realy ... because acquiring new access
 199                         will be the same - there no differences!
 200
 201             @seealso    -
 202
 203             @param      -
 204             @return     -
 205
 206             @onerror    -
 207         *//*-*****************************************************************************************************/
 208         inline virtual void downgradeWriteAccess()
 209         {
 210             // You must be a writer to call this method!
 211             // We can't check it - but otherwise it's your problem ...
 212             // Thats why you don't need any mutex here.
 213
 214             // Register himself as "new" reader.
 215             // This value must be 0 before - because we support single writer access only!
 216             ++m_nReadCount;
 217             // Close barrier for other writer!
 218             // Why?
 219             // You hold the serializer mutex - next one can be a reader OR a writer.
 220             // They must blocked then - because you will be a reader after this call
 221             // and writer use this condition to wait for current reader!
 222             m_aWriteCondition.reset();
 223             // Open door for next waiting thread in serialize queue!
 224             m_aSerializer.release();
 225         }
 226
 227     //-------------------------------------------------------------------------------------------------------------
 228     //  private member
 229     //-------------------------------------------------------------------------------------------------------------
 230     private:
 231
 232         ::osl::Mutex        m_aAccessLock       ;   /// regulate access on internal member of this instance
 233         ::osl::Mutex        m_aSerializer       ;   /// serialze incoming read/write access threads
 234         ::osl::Condition    m_aWriteCondition   ;   /// a writer must wait till current working reader are gone
 235         sal_Int32           m_nReadCount        ;   /// every reader is registered - the last one open the door for waiting writer
 236
 237 };      //  class FairRWLock
 238
 239 }       //  namespace framework
 240
 241 #endif  //  #ifndef __FRAMEWORK_THREADHELP_FAIRRWLOCK_HXX_
 242
 243 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */