1 #ifndef BDB_TRANS__HPP
2 #define BDB_TRANS__HPP
3 /* $Id: bdb_trans.hpp 163327 2009-06-15 15:40:12Z ivanovp $
4  * ===========================================================================
5  *
6  *                            PUBLIC DOMAIN NOTICE
7  *               National Center for Biotechnology Information
8  *
9  *  This software/database is a "United States Government Work" under the
10  *  terms of the United States Copyright Act.  It was written as part of
11  *  the author's official duties as a United States Government employee and
12  *  thus cannot be copyrighted.  This software/database is freely available
13  *  to the public for use. The National Library of Medicine and the U.S.
14  *  Government have not placed any restriction on its use or reproduction.
15  *
16  *  Although all reasonable efforts have been taken to ensure the accuracy
17  *  and reliability of the software and data, the NLM and the U.S.
18  *  Government do not and cannot warrant the performance or results that
19  *  may be obtained by using this software or data. The NLM and the U.S.
20  *  Government disclaim all warranties, express or implied, including
21  *  warranties of performance, merchantability or fitness for any particular
22  *  purpose.
23  *
24  *  Please cite the author in any work or product based on this material.
25  *
26  * ===========================================================================
27  *
28  * Author:  Anatoliy Kuznetsov
29  *
30  * File Description: Transaction support
31  *
32  */
33 
34 /// @file bdb_trans.hpp
35 /// Wrapper around Berkeley DB transaction structure
36 
37 #include <db/bdb/bdb_types.hpp>
38 #include <util/itransaction.hpp>
39 
40 #include <vector>
41 
42 BEGIN_NCBI_SCOPE
43 
44 class CBDB_Env;
45 
46 /** @addtogroup BDB
47  *
48  * @{
49  */
50 
51 class   CBDB_RawFile;
52 
53 /// BDB transaction object.
54 ///
55 /// Transaction is associated with files using CBDB_File::SetTransaction()
56 ///
57 /// @note
58 ///   Transaction is aborted upon the desctruction of a non-commited
59 ///   transaction object.
60 
61 class NCBI_BDB_EXPORT CBDB_Transaction : public ITransaction,
62                                          public ITransactionalRegistry
63 {
64 public:
65     /// Enum controls if transaction is synchronous or not.
66     /// see DB_TXN->commit for more details
67     enum ETransSync {
68         eEnvDefault, ///< Use default from CBDB_Env
69         eTransSync,  ///< Syncronous transaction
70         eTransASync  ///< Non-durable asyncronous transaction
71     };
72 
73     /// When file is connected to transaction using
74     /// CBDB_File::SetTransaction() class by default keeps track
75     /// of all associated files and then drops association on
76     /// Commit(), Abort() or destruction.
77     /// As an option we can create non associated transactions.
78     /// We want such if we plan to Commit transactions concurrently
79     /// or just looking for some performance optimization.
80     ///
81     enum EKeepFileAssociation
82     {
83         eFullAssociation,  ///< Transaction associated with files
84         eNoAssociation     ///< No association tracking
85     };
86 
87     /// Construct transaction
88     CBDB_Transaction(CBDB_Env&             env,
89                      ETransSync            tsync = eEnvDefault,
90                      EKeepFileAssociation  assoc = eFullAssociation);
91 
92 
93 
94     /// Non-commited transaction is aborted upon the destruction
95     ///
96     /// Destructor automatically detaches transaction from all
97     /// connected files (see CBDB_File::SetTransaction())
98     ///
99     ~CBDB_Transaction();
100 
101     // ITransaction:
102 
103     /// Commit transaction
104     virtual void Commit();
105     /// Rollback transaction (same as Abort)
Rollback()106     virtual void Rollback() { Abort(); }
107 
108 
109 
110 
111     /// Abort transaction
112     void Abort();
113 
114 
115     /// Get low level Berkeley DB transaction handle.
116     ///
117     /// Function uses lazy initialization paradigm, and actual
118     /// transaction is created "on demand". First call to GetTxn()
119     /// creates the handle which lives until commit or rollback point.
120     ///
121     /// @return Transaction handle
122     ///
123     DB_TXN*  GetTxn();
124 
125     /// Transaction file association mode
GetAssociationMode() const126     EKeepFileAssociation GetAssociationMode() const { return m_Assoc; }
127 
128     /// Downcast ITransaction
129     static
130     CBDB_Transaction* CastTransaction(ITransaction* trans);
131 
132     // -----------------------------------------------------
133     // ITransactionalRegistry
134     // -----------------------------------------------------
135 
136     /// Add file to the list of connected files
137     virtual void Add(ITransactional* dbfile);
138 
139     /// Remove file from the list of connected files.
140     /// Has no effect if file has not been added before by AddFile
141     virtual void Remove(ITransactional* dbfile);
142 
143 protected:
144 
145 
146     /// Return TRUE if transaction handle has been requested by some
147     /// client (File)
IsInProgress() const148     bool IsInProgress() const { return m_Txn != 0; }
149 
150 private:
151     /// Abort transaction with error checking or without
152     void x_Abort(bool ignore_errors);
153 
154     /// Forget all
155     void x_DetachFromFiles();
156 
157 private:
158     CBDB_Transaction(const CBDB_Transaction& trans);
159     CBDB_Transaction& operator=(const CBDB_Transaction& trans);
160 protected:
161     /// Transaction association list
162     typedef vector<ITransactional*>  TTransVector;
163 protected:
164     CBDB_Env&               m_Env;        ///< Associated environment
165     ETransSync              m_TSync;      ///< Sync. flag
166     EKeepFileAssociation    m_Assoc;      ///< Association flag
167     DB_TXN*                 m_Txn;        ///< Transaction handle
168     TTransVector            m_TransFiles; ///< Files connected to transaction
169 
170 private:
171     friend class CBDB_RawFile;
172 };
173 
174 /* @} */
175 
176 END_NCBI_SCOPE
177 
178 #endif  /* BDB_ENV__HPP */
179