framework/inc/threadhelp/transactionmanager.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 INCLUDED_FRAMEWORK_INC_THREADHELP_TRANSACTIONMANAGER_HXX
  21 #define INCLUDED_FRAMEWORK_INC_THREADHELP_TRANSACTIONMANAGER_HXX
  22
  23 #include <boost/noncopyable.hpp>
  24 #include <threadhelp/gate.hxx>
  25
  26 #include <com/sun/star/uno/Reference.hxx>
  27 #include <com/sun/star/uno/XInterface.hpp>
  28 #include <com/sun/star/uno/RuntimeException.hpp>
  29 #include <com/sun/star/lang/DisposedException.hpp>
  30
  31 #include <osl/mutex.hxx>
  32 #include <fwidllapi.h>
  33
  34 namespace framework{
  35
  36 /*-************************************************************************************************************
  37     @descr          Describe different states of a feature of following implementation.
  38                     During lifetime of an object different working states occur:
  39                         initialization - working - closing - closed
  40                     If you wish to implement thread safe classes you should use this feature to protect
  41                     your code against calls at wrong time. e.g. you are not full initialized but somewhere
  42                     call an interface method (initialize phase means startup time from creating object till
  43                     calling specified first method e.g. XInitialization::initialze()!) then you should refuse
  44                     this call. The same for closing/disposing the object!
  45 *//*-*************************************************************************************************************/
  46 enum EWorkingMode
  47 {
  48     E_INIT       ,   // We stand in a init method   -> some calls are accepted - some one are rejected
  49     E_WORK       ,   // Object is ready for working -> all calls are accepted
  50     E_BEFORECLOSE,   // We stand in a close method  -> some calls are accepted - some one are rejected
  51     E_CLOSE          // Object is dead!             -> all calls are rejected!
  52 };
  53
  54 /*-************************************************************************************************************
  55     @descr          If a request was refused by a transaction manager (internal state different E_WORK ...)
  56                     user can check the reason by using this enum values.
  57 *//*-*************************************************************************************************************/
  58 enum ERejectReason
  59 {
  60     E_UNINITIALIZED ,
  61     E_NOREASON      ,
  62     E_INCLOSE       ,
  63     E_CLOSED
  64 };
  65
  66 /*-************************************************************************************************************
  67     @descr          A transaction object should support throwing exceptions if user used it at wrong working mode.
  68                     e.g. We can throw a DisposedException if user try to work and our mode is E_CLOSE!
  69                     But sometimes he dont need this feature - will handle it by himself.
  70                     Then we must differ between some exception-modi:
  71                         E_HARDEXCEPTIONS        We throw exceptions for all working modes different from E_WORK!
  72                         E_SOFTEXCEPTIONS        We throw exceptions for all working modes different from E_WORK AND E_INCLOSE!
  73                                                 This mode is useful for impl-methods which should be callable from dispose() method!
  74
  75                                                 e.g.    void dispose()
  76                                                         {
  77                                                             m_aTransactionManager.setWorkingMode( E_BEFORECLOSE );
  78                                                             ...
  79                                                             impl_setA( 0 );
  80                                                             ...
  81                                                             m_aTransactionManager.setWorkingMode( E_CLOSE );
  82                                                         }
  83
  84                                                         void impl_setA( int nA )
  85                                                         {
  86                                                             ERejectReason       EReason;
  87                                                             TransactionGuard    aTransactionGuard( m_aTransactionManager, E_SOFTEXCEPTIONS, eReason );
  88
  89                                                             m_nA = nA;
  90                                                         }
  91
  92                                                 Normally (if E_HARDEXCEPTIONS was used!) creation of guard
  93                                                 will throw an exception ... but using of E_SOFTEXCEPTIONS suppress it
  94                                                 and member "A" can be set.
  95 *//*-*************************************************************************************************************/
  96 enum EExceptionMode
  97 {
  98     E_HARDEXCEPTIONS,
  99     E_SOFTEXCEPTIONS
 100 };
 101
 102 /*-************************************************************************************************************
 103     @short          implement a transaction manager to support non breakable interface methods
 104     @descr          Use it to support non breakable interface methods without using any thread
 105                     synchronization like e.g. mutex, rw-lock!
 106                     That protect your code against wrong calls at wrong time ... e.g. calls after disposing an object!
 107                     Use combination of EExceptionMode and ERejectReason to detect rejected requests
 108                     and react for it. You can enable automatically throwing of exceptions too.
 109
 110     @devstatus      draft
 111 *//*-*************************************************************************************************************/
 112 class FWI_DLLPUBLIC TransactionManager: private boost::noncopyable
 113 {
 114
 115     //  public methods
 116
 117     public:
 118
 119                                    TransactionManager           (                                              );
 120                                    ~TransactionManager          (                                              );
 121         void               setWorkingMode               ( EWorkingMode eMode                           );
 122         EWorkingMode       getWorkingMode               (                                              ) const;
 123         bool               isCallRejected               ( ERejectReason& eReason                       ) const;
 124         void               registerTransaction          ( EExceptionMode eMode, ERejectReason& eReason ) throw( css::uno::RuntimeException, css::lang::DisposedException );
 125         void               unregisterTransaction        (                                              ) throw( css::uno::RuntimeException, css::lang::DisposedException );
 126
 127     //  private methods
 128
 129     private:
 130
 131         void impl_throwExceptions( EExceptionMode eMode, ERejectReason eReason ) const throw( css::uno::RuntimeException, css::lang::DisposedException );
 132
 133     //  private member
 134
 135     private:
 136
 137         mutable ::osl::Mutex    m_aAccessLock;   /// regulate access on internal member of this instance
 138         Gate                    m_aBarrier;   /// used to block transactions requests during change or work mode
 139         EWorkingMode            m_eWorkingMode;   /// current working mode of object which use this manager (used to reject calls at wrong time)
 140         sal_Int32               m_nTransactionCount;   /// every transaction request is registered by this counter
 141
 142 };      //  class TransactionManager
 143
 144 }       //  namespace framework
 145
 146 #endif // INCLUDED_FRAMEWORK_INC_THREADHELP_TRANSACTIONMANAGER_HXX
 147
 148 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */