framework/source/threadhelp/transactionmanager.cxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2000, 2010 Oracle and/or its affiliates.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * This file is part of OpenOffice.org.
  10  *
  11  * OpenOffice.org is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU Lesser General Public License version 3
  13  * only, as published by the Free Software Foundation.
  14  *
  15  * OpenOffice.org is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU Lesser General Public License version 3 for more details
  19  * (a copy is included in the LICENSE file that accompanied this code).
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * version 3 along with OpenOffice.org.  If not, see
  23  * <http://www.openoffice.org/license.html>
  24  * for a copy of the LGPLv3 License.
  25  *
  26  ************************************************************************/
  27
  28 // MARKER(update_precomp.py): autogen include statement, do not remove
  29 #include "precompiled_framework.hxx"
  30
  31 //_________________________________________________________________________________________________________________
  32 //  my own includes
  33 //_________________________________________________________________________________________________________________
  34 #include <threadhelp/transactionmanager.hxx>
  35 #include <threadhelp/resetableguard.hxx>
  36 #include <macros/debug.hxx>
  37
  38 #include <macros/generic.hxx>
  39
  40 //_________________________________________________________________________________________________________________
  41 //  interface includes
  42 //_________________________________________________________________________________________________________________
  43 #include <com/sun/star/lang/DisposedException.hpp>
  44 //_________________________________________________________________________________________________________________
  45 //  other includes
  46 //_________________________________________________________________________________________________________________
  47
  48 //_________________________________________________________________________________________________________________
  49 //  const
  50 //_________________________________________________________________________________________________________________
  51
  52 //_________________________________________________________________________________________________________________
  53 //  namespace
  54 //_________________________________________________________________________________________________________________
  55
  56 namespace framework{
  57
  58 //_________________________________________________________________________________________________________________
  59 //  non exported const
  60 //_________________________________________________________________________________________________________________
  61
  62 //_________________________________________________________________________________________________________________
  63 //  non exported declarations
  64 //_________________________________________________________________________________________________________________
  65
  66 //_________________________________________________________________________________________________________________
  67 //  definitions
  68 //_________________________________________________________________________________________________________________
  69
  70 /*-************************************************************************************************************//**
  71     @short      standard ctor
  72     @descr      Initialize instance with right start values for correct working.
  73
  74     @seealso    -
  75
  76     @param      -
  77     @return     -
  78
  79     @onerror    -
  80 *//*-*************************************************************************************************************/
  81 TransactionManager::TransactionManager()
  82     : m_eWorkingMode      ( E_INIT )
  83     , m_nTransactionCount ( 0      )
  84 {
  85     m_aBarrier.open();
  86 }
  87
  88 /*-************************************************************************************************************//**
  89     @short      standard dtor
  90     @descr      -
  91
  92     @seealso    -
  93
  94     @param      -
  95     @return     -
  96
  97     @onerror    -
  98 *//*-*************************************************************************************************************/
  99 TransactionManager::~TransactionManager()
 100 {
 101 }
 102
 103 /*-****************************************************************************************************//**
 104     @interface  ITransactionManager
 105     @short      set new working mode
 106     @descr      These implementation knows for states of working: E_INIT, E_WORK, E_CLOSING, E_CLOSE
 107                 You can step during this ones only from the left to the right side and start at left side again!
 108                 (This is neccessary e.g. for refcounted objects!)
 109                 This call will block till all current existing transactions was finished.
 110                 Follow results occure:
 111                     E_INIT        :  All requests on this implementation are refused.
 112                                         It's your decision to react in a right way.
 113
 114                     E_WORK        :  The object can work now. The full functionality is available.
 115
 116                     E_BEFORECLOSE :  The object start the closing mechanism ... but sometimes
 117                                         e.g. the dispose() method need to call some private methods.
 118                                         These some special methods should use E_SOFTEXCEPTIONS or ignore
 119                                         E_INCLOSE as returned reason for E_NOEXCEPTIONS to detect this special case!
 120
 121                     E_CLOSE       :  Object is already dead! All further requests will be refused.
 122                                         It's your decision to react in a right way.
 123
 124     @seealso    -
 125
 126     @param      "eMode", is the new mode - but we don't accept setting mode in wrong order!
 127     @return     -
 128
 129     @onerror    We do nothing.
 130 *//*-*****************************************************************************************************/
 131 void  TransactionManager::setWorkingMode( EWorkingMode eMode )
 132 {
 133     // Safe member access.
 134     ::osl::ClearableMutexGuard  aAccessGuard( m_aAccessLock );
 135     sal_Bool                    bWaitFor    = sal_False      ;
 136     // Change working mode first!
 137     if  (
 138             ( m_eWorkingMode == E_INIT        && eMode == E_WORK        ) ||
 139             ( m_eWorkingMode == E_WORK        && eMode == E_BEFORECLOSE ) ||
 140             ( m_eWorkingMode == E_BEFORECLOSE && eMode == E_CLOSE       ) ||
 141             ( m_eWorkingMode == E_CLOSE       && eMode == E_INIT        )
 142         )
 143     {
 144         m_eWorkingMode = eMode;
 145         if( m_eWorkingMode == E_BEFORECLOSE || m_eWorkingMode == E_CLOSE )
 146         {
 147             bWaitFor = sal_True;
 148         }
 149     }
 150
 151     // Wait for current existing transactions then!
 152     // (Only neccessary for changing to E_BEFORECLOSE or E_CLOSE! ...
 153     // otherwise; if you wait at setting E_WORK another thrad could finish a acquire-call during our unlock() and wait() call
 154     // ... and we will wait forever here!!!)
 155     // Don't forget to release access mutex before.
 156     aAccessGuard.clear();
 157     if( bWaitFor == sal_True )
 158     {
 159         m_aBarrier.wait();
 160     }
 161 }
 162
 163 /*-****************************************************************************************************//**
 164     @interface  ITransactionManager
 165     @short      get current working mode
 166     @descr      If you stand in your close() or init() method ... but don't know
 167                 if you called more then ones(!) ... you can use this function to get
 168                 right information.
 169                 e.g:    You have a method init() which is used to change working mode from
 170                         E_INIT to E_WORK and should be used to initialize some member too ...
 171                         What should you do:
 172
 173                             void init( sal_Int32 nValue )
 174                             {
 175                                 // Reject this call if our transaction manager say: "Object already initialized!"
 176                                 // Otherwise initialize your member.
 177                                 if( m_aTransactionManager.getWorkingMode() == E_INIT )
 178                                 {
 179                                     // Object is uninitialized ...
 180                                     // Make member access threadsafe!
 181                                     ResetableGuard aGuard( m_aMutex );
 182
 183                                     // Check working mode again .. because anoz�ther instance could be faster.
 184                                     // (It's possible to set this guard at first of this method too!)
 185                                     if( m_aTransactionManager.getWorkingMode() == E_INIT )
 186                                     {
 187                                         m_aMember = nValue;
 188
 189                                         // Object is initialized now ... set working mode to E_WORK!
 190                                         m_aTransactionManager.setWorkingMode( E_WORK );
 191                                     }
 192                                 }
 193                             }
 194
 195     @seealso    method setWorkingMode()
 196
 197     @param      -
 198     @return     Current set mode.
 199
 200     @onerror    No error should occure.
 201 *//*-*****************************************************************************************************/
 202 EWorkingMode TransactionManager::getWorkingMode() const
 203 {
 204     // Synchronize access to internal member!
 205     ::osl::MutexGuard aAccessLock( m_aAccessLock );
 206     return m_eWorkingMode;
 207 }
 208
 209 /*-****************************************************************************************************//**
 210     @interface  ITransactionManager
 211     @short      start new transaction
 212     @descr      A guard should use this method to start a new transaction. He should looks for rejected
 213                 calls to by using parameter eMode and eReason.
 214                 If call was not rejected your transaction will be non breakable during releasing your transaction
 215                 guard! BUT ... your code isn't threadsafe then! It's a transaction manager only ....
 216
 217     @seealso    method unregisterTransaction()
 218
 219     @param      "eMode"     ,used to enable/disable throwing exceptions automaticly for rejected calls
 220     @param      "eReason"   ,reason for rejected calls if eMode=E_NOEXCEPTIONS
 221     @return     -
 222
 223     @onerror    -
 224 *//*-*****************************************************************************************************/
 225 void  TransactionManager::registerTransaction( EExceptionMode eMode, ERejectReason& eReason ) throw( css::uno::RuntimeException, css::lang::DisposedException )
 226 {
 227     // Look for rejected calls first.
 228     // If call was refused we throw some exceptions or do nothing!
 229     // It depends from given parameter eMode.
 230     if( isCallRejected( eReason ) == sal_True )
 231     {
 232         impl_throwExceptions( eMode, eReason );
 233     }
 234
 235     // BUT if no exception was thrown ... (may be eMode = E_SOFTEXCEPTIONS!)
 236     // we must register this transaction too!
 237     // Don't use "else" or a new scope here!!!
 238
 239     // Safe access to internal member.
 240     ::osl::MutexGuard aAccessGuard( m_aAccessLock );
 241
 242     #ifdef ENABLE_MUTEXDEBUG
 243     LOG_ASSERT2( m_nTransactionCount<0, "TransactionManager::acquire()", "Wrong ref count detected!" )
 244     #endif
 245
 246     // Register this new transaction.
 247     // If it is the first one .. close gate to disable changing of working mode.
 248     ++m_nTransactionCount;
 249     if( m_nTransactionCount == 1 )
 250     {
 251         m_aBarrier.close();
 252     }
 253 }
 254
 255 /*-****************************************************************************************************//**
 256     @interface  ITransactionManager
 257     @short      finish transaction
 258     @descr      A guard should call this method to release current transaction.
 259
 260     @seealso    method registerTransaction()
 261
 262     @param      -
 263     @return     -
 264
 265     @onerror    -
 266 *//*-*****************************************************************************************************/
 267 void  TransactionManager::unregisterTransaction() throw( css::uno::RuntimeException, css::lang::DisposedException )
 268 {
 269     // This call could not rejected!
 270     // Safe access to internal member.
 271     ::osl::MutexGuard aAccessGuard( m_aAccessLock );
 272
 273     #ifdef ENABLE_MUTEXDEBUG
 274     LOG_ASSERT2( m_nTransactionCount<=0, "TransactionManager::release()", "Wrong ref count detected!" )
 275     #endif
 276
 277     // Deregister this transaction.
 278     // If it was the last one ... open gate to enable changing of working mode!
 279     // (see setWorkingMode())
 280
 281     --m_nTransactionCount;
 282     if( m_nTransactionCount == 0 )
 283     {
 284         m_aBarrier.open();
 285     }
 286 }
 287
 288 /*-****************************************************************************************************//**
 289     @interface  ITransactionManager
 290     @short      look for rejected calls
 291     @descr      Sometimes user need a possibility to get information about rejected calls
 292                 without starting a transaction!
 293
 294     @seealso    -
 295
 296     @param      "eReason" returns reason of a rejected call
 297     @return     true if call was rejected, false otherwise
 298
 299     @onerror    We return false.
 300 *//*-*****************************************************************************************************/
 301 sal_Bool  TransactionManager::isCallRejected( ERejectReason& eReason ) const
 302 {
 303     // This call must safe access to internal member only.
 304     // Set "possible reason" for return and check reject-state then!
 305     // User should look for return value first - reason then ...
 306     ::osl::MutexGuard aAccessGuard( m_aAccessLock );
 307     switch( m_eWorkingMode )
 308     {
 309         case E_INIT        : eReason = E_UNINITIALIZED ;
 310                                 break;
 311         case E_WORK        : eReason = E_NOREASON      ;
 312                                 break;
 313         case E_BEFORECLOSE : eReason = E_INCLOSE       ;
 314                                 break;
 315         case E_CLOSE       : eReason = E_CLOSED        ;
 316                                 break;
 317     }
 318     return( eReason!=E_NOREASON );
 319 }
 320
 321 /*-****************************************************************************************************//**
 322     @short      throw any exceptions for rejected calls
 323     @descr      If user whish to use our automaticly exception mode we use this impl-method.
 324                 We check all combinations of eReason and eExceptionMode and throw right exception with some
 325                 descriptions for recipient of it.
 326
 327     @seealso    method registerTransaction()
 328     @seealso    enum ERejectReason
 329     @seealso    enum EExceptionMode
 330
 331     @param      "eReason" , reason for rejected call
 332     @param      "eMode"   , exception mode - set by user
 333     @return     -
 334
 335     @onerror    -
 336 *//*-*****************************************************************************************************/
 337 void TransactionManager::impl_throwExceptions( EExceptionMode eMode, ERejectReason eReason ) const throw( css::uno::RuntimeException, css::lang::DisposedException )
 338 {
 339     if( eMode != E_NOEXCEPTIONS )
 340     {
 341         switch( eReason )
 342         {
 343             case E_UNINITIALIZED   :    if( eMode == E_HARDEXCEPTIONS )
 344                                         {
 345                                             // Help programmer to find out, why this exception is thrown!
 346                                             LOG_ERROR( "TransactionManager...", "Owner instance not right initialized yet. Call was rejected! Normaly it's an algorithm error ... wrong usin of class!" )
 347                                             //ATTENTION: temp. disabled - till all bad code positions are detected and changed! */
 348                                             // throw css::uno::RuntimeException( DECLARE_ASCII("TransactionManager...\nOwner instance not right initialized yet. Call was rejected! Normaly it's an algorithm error ... wrong usin of class!\n" ), css::uno::Reference< css::uno::XInterface >() );
 349                                         }
 350                                         break;
 351             case E_INCLOSE         :    if( eMode == E_HARDEXCEPTIONS )
 352                                         {
 353                                             // Help programmer to find out, why this exception is thrown!
 354                                             LOG_ERROR( "TransactionManager...", "Owner instance stand in close method. Call was rejected!" )
 355                                             throw css::lang::DisposedException( DECLARE_ASCII("TransactionManager...\nOwner instance stand in close method. Call was rejected!\n" ), css::uno::Reference< css::uno::XInterface >() );
 356                                         }
 357                                         break;
 358             case E_CLOSED           :   {
 359                                             // Help programmer to find out, why this exception is thrown!
 360                                             LOG_ERROR( "TransactionManager...", "Owner instance already closed. Call was rejected!" )
 361                                             throw css::lang::DisposedException( DECLARE_ASCII("TransactionManager...\nOwner instance already closed. Call was rejected!\n" ), css::uno::Reference< css::uno::XInterface >() );
 362                                         }
 363             case E_NOREASON         :   {
 364                                             // Help programmer to find out
 365                                             LOG_ERROR( "TransactionManager...", "Impossible case E_NOREASON!" )
 366                                         }
 367                                         break;
 368             default:                    break; // nothing to do
 369         }
 370     }
 371 }
 372
 373 }   //  namespace framework