framework/inc/threadhelp/transactionguard.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_TRANSACTIONGUARD_HXX
  21 #define INCLUDED_FRAMEWORK_INC_THREADHELP_TRANSACTIONGUARD_HXX
  22
  23 #include <boost/noncopyable.hpp>
  24 #include <threadhelp/transactionmanager.hxx>
  25
  26 namespace framework{
  27
  28 /*-************************************************************************************************************
  29     @short          implement a guard to support non breakable transactions
  30     @descr          If you wish to support non breakable method calls without lockingf any mutex, rw-lock or
  31                     something like that - you should use this guard implementation.
  32                     Initialize it at first in your method and don't release it till end of your function!
  33                     Your "transaction" is registered in ctor and automatically released in dtor.
  34                     Use set/get of working mode to enable/disable further transactions.
  35                     It's possible too, to enable automatically throwing of some exceptions for illegal
  36                     transaction requests ... e.g. interface call for already disposed objects.
  37
  38     @attention      To prevent us against wrong using, the default ctor, copy ctor and the =operator are marked private!
  39     @devstatus      draft
  40 *//*-*************************************************************************************************************/
  41 class TransactionGuard : private boost::noncopyable
  42 {
  43
  44     //  public methods
  45
  46     public:
  47
  48         /*-****************************************************************************************************
  49             @short      ctors
  50             @descr      Use these ctor methods to initialize the guard right.
  51                         Given reference must be valid - otherwise crashes could occur!
  52
  53             @attention  It's not necessary to lock any mutex here! Because a ctor should not be called
  54                         from different threads at the same time ... this class use no refcount mechanism!
  55             @param      "rManager"  reference to transaction manager for using to register a request
  56             @param      "eMode"     enable/disable throwing of exceptions for rejected calls
  57             @param      "eReason"   returns reason for rejected calls
  58         *//*-*****************************************************************************************************/
  59         inline TransactionGuard( TransactionManager& rManager, EExceptionMode eMode, ERejectReason* eReason = NULL )
  60             : m_pManager( &rManager )
  61         {
  62             // If exception mode is set to E_HARDEXCETIONS we don't need a buffer to return reason!
  63             // We handle it private. If a call is rejected, our manager throw some exceptions ... and the reason
  64             // could be ignorable ...
  65             if( eReason == NULL )
  66             {
  67                 ERejectReason eMyReason;
  68                 m_pManager->registerTransaction( eMode, eMyReason );
  69             }
  70             else
  71             {
  72                 m_pManager->registerTransaction( eMode, *eReason );
  73             }
  74         }
  75
  76         /*-************************************************************************************************************
  77             @short      dtor
  78             @descr      We must release the transaction manager and can forget his pointer.
  79         *//*-*************************************************************************************************************/
  80         inline ~TransactionGuard()
  81         {
  82             stop();
  83         }
  84
  85         /*-************************************************************************************************************
  86             @short      stop current transaction
  87             @descr      We must release the transaction manager and can forget his pointer.
  88
  89             @attention  We don't support any start() method here - because it is not easy to
  90                         detect if a transaction already started or not!
  91                         (combination of EExceptionMode and ERejectReason)
  92         *//*-*************************************************************************************************************/
  93         inline void stop()
  94         {
  95             if( m_pManager != NULL )
  96             {
  97                 m_pManager->unregisterTransaction();
  98                 m_pManager = NULL;
  99             }
 100         }
 101
 102
 103     private:
 104
 105         /*-****************************************************************************************************
 106             @short      disable using of these functions!
 107             @descr      It's not allowed to use this methods. Different problem can occur otherwise.
 108                         Thats why we disable it by make it private.
 109
 110             @seealso    other ctor
 111         *//*-*****************************************************************************************************/
 112         TransactionGuard();
 113
 114     //  private member
 115
 116     private:
 117
 118         TransactionManager*   m_pManager;   /// pointer to safed transaction manager
 119
 120 };      //  class TransactionGuard
 121
 122 }       //  namespace framework
 123
 124 #endif // INCLUDED_FRAMEWORK_INC_THREADHELP_TRANSACTIONGUARD_HXX
 125
 126 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */