Audacity  3.0.3
DBConnection.h
Go to the documentation of this file.
1 /*!********************************************************************
2 
3 Audacity: A Digital Audio Editor
4 
5 @file DBConnection.h
6 @brief Declare DBConnection, which maintains database connection and associated status and background thread
7 
8 Paul Licameli -- split from ProjectFileIO.h
9 
10 **********************************************************************/
11 
12 #ifndef __AUDACITY_DB_CONNECTION__
13 #define __AUDACITY_DB_CONNECTION__
14 
15 #include <atomic>
16 #include <condition_variable>
17 #include <functional>
18 #include <map>
19 #include <memory>
20 #include <mutex>
21 #include <thread>
22 
23 #include "ClientData.h"
24 #include "Identifier.h"
25 
26 struct sqlite3;
27 struct sqlite3_stmt;
28 class wxString;
29 class AudacityProject;
30 
32 {
35  int mErrorCode { 0 };
36  wxString mLog;
37 };
38 
40 {
41 public:
42  // Type of function invoked in the main thread after detection of
43  // checkpoint failure, which might have been in a worker thread
44  using CheckpointFailureCallback = std::function<void()>;
45 
47  const std::weak_ptr<AudacityProject> &pProject,
48  const std::shared_ptr<DBConnectionErrors> &pErrors,
49  CheckpointFailureCallback callback);
50  ~DBConnection();
51 
52  int Open(const FilePath fileName);
53  bool Close();
54 
56  [[noreturn]] void ThrowException(
57  bool write
58  ) const;
59 
60  int SafeMode(const char *schema = "main");
61  int FastMode(const char *schema = "main");
62 
63  bool Assign(sqlite3 *handle);
64  sqlite3 *Detach();
65 
66  sqlite3 *DB();
67 
68  int GetLastRC() const ;
69  const wxString GetLastMessage() const;
70 
72  {
80  GetDBPage
81  };
82  sqlite3_stmt *Prepare(enum StatementID id, const char *sql);
83 
84  void SetBypass( bool bypass );
85  bool ShouldBypass();
86 
88  void SetError(
89  const TranslatableString &msg,
90  const TranslatableString &libraryError = {},
91  int errorCode = {});
92 
94  void SetDBError(
95  const TranslatableString &msg,
96  const TranslatableString& libraryError = {},
97  int errorCode = -1);
98 
99 private:
100  int OpenStepByStep(const FilePath fileName);
101  int ModeConfig(sqlite3 *db, const char *schema, const char *config);
102 
103  void CheckpointThread(sqlite3 *db, const FilePath &fileName);
104  static int CheckpointHook(void *data, sqlite3 *db, const char *schema, int pages);
105 
106 private:
107  std::weak_ptr<AudacityProject> mpProject;
108  sqlite3 *mDB;
109  sqlite3 *mCheckpointDB;
110 
111  std::thread mCheckpointThread;
112  std::condition_variable mCheckpointCondition;
113  std::mutex mCheckpointMutex;
114  std::atomic_bool mCheckpointStop{ false };
115  std::atomic_bool mCheckpointPending{ false };
116  std::atomic_bool mCheckpointActive{ false };
117 
118  std::mutex mStatementMutex;
119  using StatementIndex = std::pair<enum StatementID, std::thread::id>;
120  std::map<StatementIndex, sqlite3_stmt *> mStatements;
121 
122  std::shared_ptr<DBConnectionErrors> mpErrors;
124 
125  // Bypass transactions if database will be deleted after close
126  bool mBypass;
127 };
128 
130 
135 class AUDACITY_DLL_API TransactionScope
136 {
137 public:
138  TransactionScope(DBConnection &connection, const char *name);
139  ~TransactionScope();
140 
141  bool Commit();
142 
143 private:
144  bool TransactionStart(const wxString &name);
145  bool TransactionCommit(const wxString &name);
146  bool TransactionRollback(const wxString &name);
147 
149  bool mInTrans;
150  wxString mName;
151 };
152 
153 using Connection = std::unique_ptr<DBConnection>;
154 
155 // This object attached to the project simply holds the pointer to the
156 // project's current database connection, which is initialized on demand,
157 // and may be redirected, temporarily or permanently, to another connection
158 // when backing the project up or saving or saving-as.
159 class ConnectionPtr final
160  : public ClientData::Base
161  , public std::enable_shared_from_this< ConnectionPtr >
162 {
163 public:
164  static ConnectionPtr &Get( AudacityProject &project );
165  static const ConnectionPtr &Get( const AudacityProject &project );
166 
167  ~ConnectionPtr() override;
168 
170 };
171 
172 #endif
TranslatableString
Holds a msgid for the translation catalog; may also bind format arguments.
Definition: TranslatableString.h:32
DBConnection::Close
bool Close()
Definition: DBConnection.cpp:215
DBConnection::mCheckpointPending
std::atomic_bool mCheckpointPending
Definition: DBConnection.h:115
DBConnection::DeleteSampleBlock
@ DeleteSampleBlock
Definition: DBConnection.h:78
DBConnection::StatementID
StatementID
Definition: DBConnection.h:72
DBConnectionErrors::mLastError
TranslatableString mLastError
Definition: DBConnection.h:33
DBConnection::mDB
sqlite3 * mDB
Definition: DBConnection.h:108
DBConnection::SetDBError
void SetDBError(const TranslatableString &msg, const TranslatableString &libraryError={}, int errorCode=-1)
Set stored errors and write to log; and default libraryError to what database library reports.
Definition: DBConnection.cpp:101
DBConnection::CheckpointFailureCallback
std::function< void()> CheckpointFailureCallback
Definition: DBConnection.h:44
DBConnection::DBConnection
DBConnection(const std::weak_ptr< AudacityProject > &pProject, const std::shared_ptr< DBConnectionErrors > &pErrors, CheckpointFailureCallback callback)
Definition: DBConnection.cpp:42
Connection
std::unique_ptr< DBConnection > Connection
Definition: DBConnection.h:153
DBConnection::Open
int Open(const FilePath fileName)
Definition: DBConnection.cpp:133
ClientData::Base
A convenient default parameter for class template Site.
Definition: ClientData.h:28
DBConnection::GetLastRC
int GetLastRC() const
Definition: DBConnection.cpp:382
DBConnection::mCallback
CheckpointFailureCallback mCallback
Definition: DBConnection.h:123
ConnectionPtr::~ConnectionPtr
~ConnectionPtr() override
Definition: DBConnection.cpp:673
ClientData.h
Utility ClientData::Site to register hooks into a host class that attach client data.
DBConnectionErrors::mLibraryError
TranslatableString mLibraryError
Definition: DBConnection.h:34
DBConnection
Definition: DBConnection.h:40
DBConnection::GetSamples
@ GetSamples
Definition: DBConnection.h:73
DBConnection::GetLastMessage
const wxString GetLastMessage() const
Definition: DBConnection.cpp:387
DBConnection::SetBypass
void SetBypass(bool bypass)
Definition: DBConnection.cpp:65
DBConnection::DB
sqlite3 * DB()
Definition: DBConnection.cpp:375
TransactionScope::mConnection
DBConnection & mConnection
Definition: DBConnection.h:148
DBConnection::mCheckpointDB
sqlite3 * mCheckpointDB
Definition: DBConnection.h:109
DBConnection::GetDBPage
@ GetDBPage
Definition: DBConnection.h:80
DBConnectionErrors::mErrorCode
int mErrorCode
Definition: DBConnection.h:35
DBConnection::OpenStepByStep
int OpenStepByStep(const FilePath fileName)
Definition: DBConnection.cpp:160
DBConnection::mCheckpointCondition
std::condition_variable mCheckpointCondition
Definition: DBConnection.h:112
FilePath
wxString FilePath
Definition: Project.h:20
name
const TranslatableString name
Definition: Distortion.cpp:98
Identifier.h
ConnectionPtr
Definition: DBConnection.h:162
DBConnection::GetRootPage
@ GetRootPage
Definition: DBConnection.h:79
TransactionScope
RAII for a database transaction, possibly nested.
Definition: DBConnection.h:136
TransactionScope::mName
wxString mName
Definition: DBConnection.h:150
DBConnection::ThrowException
void ThrowException(bool write) const
throw and show appropriate message box
Definition: DBConnection.cpp:322
DBConnection::mpErrors
std::shared_ptr< DBConnectionErrors > mpErrors
Definition: DBConnection.h:122
DBConnection::CheckpointHook
static int CheckpointHook(void *data, sqlite3 *db, const char *schema, int pages)
Definition: DBConnection.cpp:541
DBConnection::SetError
void SetError(const TranslatableString &msg, const TranslatableString &libraryError={}, int errorCode={})
Just set stored errors.
Definition: DBConnection.cpp:75
DBConnection::GetSummary256
@ GetSummary256
Definition: DBConnection.h:74
DBConnection::mCheckpointThread
std::thread mCheckpointThread
Definition: DBConnection.h:111
DBConnection::GetSummary64k
@ GetSummary64k
Definition: DBConnection.h:75
DBConnection::InsertSampleBlock
@ InsertSampleBlock
Definition: DBConnection.h:77
DBConnection::mCheckpointActive
std::atomic_bool mCheckpointActive
Definition: DBConnection.h:116
ConnectionPtr::Get
static ConnectionPtr & Get(AudacityProject &project)
Definition: DBConnection.cpp:693
AudacityProject
The top-level handle to an Audacity project. It serves as a source of events that other objects can b...
Definition: Project.h:92
DBConnection::mBypass
bool mBypass
Definition: DBConnection.h:126
DBConnection::Assign
bool Assign(sqlite3 *handle)
DBConnection::LoadSampleBlock
@ LoadSampleBlock
Definition: DBConnection.h:76
DBConnection::ShouldBypass
bool ShouldBypass()
Definition: DBConnection.cpp:70
DBConnection::SafeMode
int SafeMode(const char *schema="main")
Definition: DBConnection.cpp:336
DBConnection::mCheckpointMutex
std::mutex mCheckpointMutex
Definition: DBConnection.h:113
DBConnectionErrors
Definition: DBConnection.h:32
DBConnection::ModeConfig
int ModeConfig(sqlite3 *db, const char *schema, const char *config)
Definition: DBConnection.cpp:346
ConnectionPtr::mpConnection
Connection mpConnection
Definition: DBConnection.h:169
DBConnectionErrors::mLog
wxString mLog
Definition: DBConnection.h:36
DBConnection::CheckpointThread
void CheckpointThread(sqlite3 *db, const FilePath &fileName)
Definition: DBConnection.cpp:446
DBConnection::Detach
sqlite3 * Detach()
DBConnection::~DBConnection
~DBConnection()
Definition: DBConnection.cpp:55
TransactionScope::mInTrans
bool mInTrans
Definition: DBConnection.h:149
DBConnection::mpProject
std::weak_ptr< AudacityProject > mpProject
Definition: DBConnection.h:107
DBConnection::mStatementMutex
std::mutex mStatementMutex
Definition: DBConnection.h:118
DBConnection::mCheckpointStop
std::atomic_bool mCheckpointStop
Definition: DBConnection.h:114
DBConnection::mStatements
std::map< StatementIndex, sqlite3_stmt * > mStatements
Definition: DBConnection.h:120
DBConnection::Prepare
sqlite3_stmt * Prepare(enum StatementID id, const char *sql)
Definition: DBConnection.cpp:392
DBConnection::StatementIndex
std::pair< enum StatementID, std::thread::id > StatementIndex
Definition: DBConnection.h:119
DBConnection::FastMode
int FastMode(const char *schema="main")
Definition: DBConnection.cpp:341