1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 * vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ :
3 * This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7 #ifndef mozilla_storage_Connection_h
8 #define mozilla_storage_Connection_h
11 #include "mozilla/Atomics.h"
12 #include "mozilla/Mutex.h"
13 #include "nsProxyRelease.h"
14 #include "nsThreadUtils.h"
15 #include "nsIInterfaceRequestor.h"
17 #include "nsDataHashtable.h"
18 #include "mozIStorageProgressHandler.h"
19 #include "SQLiteMutex.h"
20 #include "mozIStorageConnection.h"
21 #include "mozStorageService.h"
22 #include "mozIStorageAsyncConnection.h"
23 #include "mozIStorageCompletionCallback.h"
25 #include "mozilla/Attributes.h"
37 class Connection final
: public mozIStorageConnection
,
38 public nsIInterfaceRequestor
{
40 NS_DECL_THREADSAFE_ISUPPORTS
41 NS_DECL_MOZISTORAGEASYNCCONNECTION
42 NS_DECL_MOZISTORAGECONNECTION
43 NS_DECL_NSIINTERFACEREQUESTOR
46 * Indicates if a database operation is synchronous or asynchronous.
48 * - Async operations may be called from any thread for all connections.
49 * - Sync operations may be called from any thread for sync connections, and
50 * from background threads for async connections.
52 enum ConnectionOperation
{ ASYNCHRONOUS
, SYNCHRONOUS
};
55 * Structure used to describe user functions on the database connection.
58 enum FunctionType
{ SIMPLE
, AGGREGATE
};
60 nsCOMPtr
<nsISupports
> function
;
67 * Pointer to the storage service. Held onto for the lifetime of the
70 * The flags to pass to sqlite3_open_v2.
71 * @param aSupportedOperations
72 * The operation types supported on this connection. All connections
73 * implement both the async (`mozIStorageAsyncConnection`) and sync
74 * (`mozIStorageConnection`) interfaces, but async connections may not
75 * call sync operations from the main thread.
76 * @param aIgnoreLockingMode
77 * If |true|, ignore locks in force on the file. Only usable with
78 * read-only connections. Defaults to false.
79 * Use with extreme caution. If sqlite ignores locks, reads may fail
80 * indicating database corruption (the database won't actually be
81 * corrupt) or produce wrong results without any indication that has
84 Connection(Service
* aService
, int aFlags
,
85 ConnectionOperation aSupportedOperations
,
86 bool aIgnoreLockingMode
= false);
89 * Creates the connection to an in-memory database.
91 nsresult
initialize();
94 * Creates the connection to the database.
96 * @param aDatabaseFile
97 * The nsIFile of the location of the database to open, or create if it
100 nsresult
initialize(nsIFile
* aDatabaseFile
);
103 * Creates the connection to the database.
106 * The nsIFileURL of the location of the database to open, or create if
109 nsresult
initialize(nsIFileURL
* aFileURL
);
112 * Same as initialize, but to be used on the async thread.
114 nsresult
initializeOnAsyncThread(nsIFile
* aStorageFile
);
117 * Fetches runtime status information for this connection.
119 * @param aStatusOption One of the SQLITE_DBSTATUS options defined at
120 * http://www.sqlite.org/c3ref/c_dbstatus_options.html
121 * @param [optional] aMaxValue if provided, will be set to the highest
122 * istantaneous value.
123 * @return the current value for the specified option.
125 int32_t getSqliteRuntimeStatus(int32_t aStatusOption
,
126 int32_t* aMaxValue
= nullptr);
128 * Registers/unregisters a commit hook callback.
130 * @param aCallbackFn a callback function to be invoked on transactions
131 * commit. Pass nullptr to unregister the current callback.
132 * @param [optional] aData if provided, will be passed to the callback.
133 * @see http://sqlite.org/c3ref/commit_hook.html
135 void setCommitHook(int (*aCallbackFn
)(void*), void* aData
= nullptr) {
136 MOZ_ASSERT(mDBConn
, "A connection must exist at this point");
137 ::sqlite3_commit_hook(mDBConn
, aCallbackFn
, aData
);
141 * Gets autocommit status.
143 bool getAutocommit() {
144 return mDBConn
&& static_cast<bool>(::sqlite3_get_autocommit(mDBConn
));
148 * Lazily creates and returns a background execution thread. In the future,
149 * the thread may be re-claimed if left idle, so you should call this
150 * method just before you dispatch and not save the reference.
152 * This must be called from the opener thread.
154 * @return an event target suitable for asynchronous statement execution.
155 * @note This method will return null once AsyncClose() has been called.
157 nsIEventTarget
* getAsyncExecutionTarget();
160 * Mutex used by asynchronous statements to protect state. The mutex is
161 * declared on the connection object because there is no contention between
162 * asynchronous statements (they are serialized on mAsyncExecutionThread).
163 * Currently protects:
164 * - Connection.mAsyncExecutionThreadShuttingDown
165 * - Connection.mConnectionClosed
166 * - AsyncExecuteStatements.mCancelRequested
168 Mutex sharedAsyncExecutionMutex
;
171 * Wraps the mutex that SQLite gives us from sqlite3_db_mutex. This is public
172 * because we already expose the sqlite3* native connection and proper
173 * operation of the deadlock detector requires everyone to use the same single
174 * SQLiteMutex instance for correctness.
176 SQLiteMutex sharedDBMutex
;
179 * References the thread this database was opened on. This MUST be thread it
182 const nsCOMPtr
<nsIThread
> threadOpenedOn
;
185 * Closes the SQLite database, and warns about any non-finalized statements.
187 nsresult
internalClose(sqlite3
* aDBConn
);
190 * Shuts down the passed-in async thread.
192 void shutdownAsyncThread();
195 * Obtains the filename of the connection. Useful for logging.
197 nsCString
getFilename();
200 * Creates an sqlite3 prepared statement object from an SQL string.
202 * @param aNativeConnection
203 * The underlying Sqlite connection to prepare the statement with.
205 * The SQL statement string to compile.
207 * New sqlite3_stmt object.
208 * @return the result from sqlite3_prepare_v2.
210 int prepareStatement(sqlite3
* aNativeConnection
, const nsCString
& aSQL
,
211 sqlite3_stmt
** _stmt
);
214 * Performs a sqlite3_step on aStatement, while properly handling
215 * SQLITE_LOCKED when not on the main thread by waiting until we are notified.
217 * @param aNativeConnection
218 * The underlying Sqlite connection to step the statement with.
220 * A pointer to a sqlite3_stmt object.
221 * @return the result from sqlite3_step.
223 int stepStatement(sqlite3
* aNativeConnection
, sqlite3_stmt
* aStatement
);
226 * Raw connection transaction management.
228 * @see BeginTransactionAs, CommitTransaction, RollbackTransaction.
230 nsresult
beginTransactionInternal(
231 const SQLiteMutexAutoLock
& aProofOfLock
, sqlite3
* aNativeConnection
,
232 int32_t aTransactionType
= TRANSACTION_DEFERRED
);
233 nsresult
commitTransactionInternal(const SQLiteMutexAutoLock
& aProofOfLock
,
234 sqlite3
* aNativeConnection
);
235 nsresult
rollbackTransactionInternal(const SQLiteMutexAutoLock
& aProofOfLock
,
236 sqlite3
* aNativeConnection
);
239 * Indicates if this database connection is open.
241 inline bool connectionReady() { return mDBConn
!= nullptr; }
244 * Indicates if this database connection has an open transaction. Because
245 * multiple threads can execute statements on the same connection, this method
246 * requires proof that the caller is holding `sharedDBMutex`.
248 * Per the SQLite docs, `sqlite3_get_autocommit` returns 0 if autocommit mode
249 * is disabled. `BEGIN` disables autocommit mode, and `COMMIT`, `ROLLBACK`, or
250 * an automatic rollback re-enables it.
252 inline bool transactionInProgress(const SQLiteMutexAutoLock
& aProofOfLock
) {
253 return !getAutocommit();
257 * Indicates if this database connection supports the given operation.
259 * @param aOperationType
260 * The operation type, sync or async.
261 * @return `true` if the operation is supported, `false` otherwise.
263 bool operationSupported(ConnectionOperation aOperationType
);
266 * Thread-aware version of connectionReady, results per caller's thread are:
267 * - owner thread: Same as connectionReady(). True means we have a valid,
268 * un-closed database connection and it's not going away until you invoke
269 * Close() or AsyncClose().
270 * - async thread: Returns true at all times because you can't schedule
271 * runnables against the async thread after AsyncClose() has been called.
272 * Therefore, the connection is still around if your code is running.
273 * - any other thread: Race-prone Lies! If you are main-thread code in
274 * mozStorageService iterating over the list of connections, you need to
275 * acquire the sharedAsyncExecutionMutex for the connection, invoke
276 * connectionReady() while holding it, and then continue to hold it while
277 * you do whatever you need to do. This is because of off-main-thread
278 * consumers like dom/cache and IndexedDB and other QuotaManager clients.
280 bool isConnectionReadyOnThisThread();
283 * True if this connection has inited shutdown.
288 * True if the underlying connection is closed.
289 * Any sqlite resources may be lost when this returns true, so nothing should
291 * This locks on sharedAsyncExecutionMutex.
296 * Same as isClosed(), but takes a proof-of-lock instead of locking
299 bool isClosed(MutexAutoLock
& lock
);
302 * True if the async execution thread is alive and able to be used (i.e., it
303 * is not in the process of shutting down.)
305 * This must be called from the opener thread.
307 bool isAsyncExecutionThreadAvailable();
309 nsresult
initializeClone(Connection
* aClone
, bool aReadOnly
);
313 nsresult
initializeInternal();
314 void initializeFailed();
317 * Sets the database into a closed state so no further actions can be
320 * @note mDBConn is set to nullptr in this method.
322 nsresult
setClosedState();
325 * Helper for calls to sqlite3_exec. Reports long delays to Telemetry.
327 * @param aNativeConnection
328 * The underlying Sqlite connection to execute the query with.
330 * SQL string to execute
331 * @return the result from sqlite3_exec.
333 int executeSql(sqlite3
* aNativeConnection
, const char* aSqlString
);
336 * Describes a certain primitive type in the database.
338 * Possible Values Are:
339 * INDEX - To check for the existence of an index
340 * TABLE - To check for the existence of a table
342 enum DatabaseElementType
{ INDEX
, TABLE
};
345 * Determines if the specified primitive exists.
347 * @param aElementType
348 * The type of element to check the existence of
349 * @param aElementName
350 * The name of the element to check for
351 * @returns true if element exists, false otherwise
353 nsresult
databaseElementExists(enum DatabaseElementType aElementType
,
354 const nsACString
& aElementName
, bool* _exists
);
356 bool findFunctionByInstance(nsISupports
* aInstance
);
358 static int sProgressHelper(void* aArg
);
359 // Generic progress handler
360 // Dispatch call to registered progress handler,
361 // if there is one. Do nothing in other cases.
362 int progressHandler();
365 * Like `operationSupported`, but throws (and, in a debug build, asserts) if
366 * the operation is unsupported.
368 nsresult
ensureOperationSupported(ConnectionOperation aOperationType
);
371 nsCOMPtr
<nsIFileURL
> mFileURL
;
372 nsCOMPtr
<nsIFile
> mDatabaseFile
;
375 * The filename that will be reported to telemetry for this connection. By
376 * default this will be the leaf of the path to the database file.
378 nsCString mTelemetryFilename
;
381 * Lazily created thread for asynchronous statement execution. Consumers
382 * should use getAsyncExecutionTarget rather than directly accessing this
385 * This must be modified only on the opener thread.
387 nsCOMPtr
<nsIThread
> mAsyncExecutionThread
;
390 * Set to true by Close() or AsyncClose() prior to shutdown.
392 * If false, we guarantee both that the underlying sqlite3 database
393 * connection is still open and that getAsyncExecutionTarget() can
394 * return a thread. Once true, either the sqlite3 database
395 * connection is being shutdown or it has been
396 * shutdown. Additionally, once true, getAsyncExecutionTarget()
399 * This variable should be accessed while holding the
400 * sharedAsyncExecutionMutex.
402 bool mAsyncExecutionThreadShuttingDown
;
405 * Set to true just prior to calling sqlite3_close on the
408 * This variable should be accessed while holding the
409 * sharedAsyncExecutionMutex.
411 bool mConnectionClosed
;
414 * Stores the default behavior for all transactions run on this connection.
416 mozilla::Atomic
<int32_t> mDefaultTransactionType
;
419 * Used to trigger cleanup logic only the first time our refcount hits 1. We
420 * may trigger a failsafe Close() that invokes SpinningSynchronousClose()
421 * which invokes AsyncClose() which may bump our refcount back up to 2 (and
422 * which will then fall back down to 1 again). It's also possible that the
423 * Service may bump our refcount back above 1 if getConnections() runs before
424 * we invoke unregisterConnection().
426 mozilla::Atomic
<bool> mDestroying
;
429 * Stores the mapping of a given function by name to its instance. Access is
430 * protected by sharedDBMutex.
432 nsDataHashtable
<nsCStringHashKey
, FunctionInfo
> mFunctions
;
435 * Stores the registered progress handler for the database connection. Access
436 * is protected by sharedDBMutex.
438 nsCOMPtr
<mozIStorageProgressHandler
> mProgressHandler
;
441 * Stores the flags we passed to sqlite3_open_v2.
446 * Stores whether we should ask sqlite3_open_v2 to ignore locking.
448 const bool mIgnoreLockingMode
;
450 // This is here for two reasons: 1) It's used to make sure that the
451 // connections do not outlive the service. 2) Our custom collating functions
452 // call its localeCompareStrings() method.
453 RefPtr
<Service
> mStorageService
;
456 * Indicates which operations are supported on this connection.
458 const ConnectionOperation mSupportedOperations
;
460 nsresult
synchronousClose();
464 * A Runnable designed to call a mozIStorageCompletionCallback on
465 * the appropriate thread.
467 class CallbackComplete final
: public Runnable
{
470 * @param aValue The result to pass to the callback. It must
471 * already be owned by the main thread.
472 * @param aCallback The callback. It must already be owned by the
475 CallbackComplete(nsresult aStatus
, nsISupports
* aValue
,
476 already_AddRefed
<mozIStorageCompletionCallback
> aCallback
)
477 : Runnable("storage::CallbackComplete"),
480 mCallback(aCallback
) {}
482 NS_IMETHOD
Run() override
{
483 MOZ_ASSERT(NS_IsMainThread());
484 nsresult rv
= mCallback
->Complete(mStatus
, mValue
);
486 // Ensure that we release on the main thread
494 nsCOMPtr
<nsISupports
> mValue
;
495 // This is a RefPtr<T> and not a nsCOMPtr<T> because
496 // nsCOMP<T> would cause an off-main thread QI, which
497 // is not a good idea (and crashes XPConnect).
498 RefPtr
<mozIStorageCompletionCallback
> mCallback
;
501 } // namespace storage
502 } // namespace mozilla
505 * Casting Connection to nsISupports is ambiguous.
506 * This method handles that.
508 inline nsISupports
* ToSupports(mozilla::storage::Connection
* p
) {
509 return NS_ISUPPORTS_CAST(mozIStorageAsyncConnection
*, p
);
512 #endif // mozilla_storage_Connection_h