framework/source/threadhelp/transactionmanager.cxx

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