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