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 "nsTHashMap.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 nsCOMPtr
<mozIStorageFunction
> function
;
64 * Pointer to the storage service. Held onto for the lifetime of the
67 * The flags to pass to sqlite3_open_v2.
68 * @param aSupportedOperations
69 * The operation types supported on this connection. All connections
70 * implement both the async (`mozIStorageAsyncConnection`) and sync
71 * (`mozIStorageConnection`) interfaces, but async connections may not
72 * call sync operations from the main thread.
73 * @param aInterruptible
74 * If |true|, the pending operations can be interrupted by invokind the
76 * If |false|, method Interrupt() must not be used.
77 * @param aIgnoreLockingMode
78 * If |true|, ignore locks in force on the file. Only usable with
79 * read-only connections. Defaults to false.
80 * Use with extreme caution. If sqlite ignores locks, reads may fail
81 * indicating database corruption (the database won't actually be
82 * corrupt) or produce wrong results without any indication that has
85 Connection(Service
* aService
, int aFlags
,
86 ConnectionOperation aSupportedOperations
,
87 bool aInterruptible
= false, bool aIgnoreLockingMode
= false);
90 * Creates the connection to an in-memory database.
92 nsresult
initialize(const nsACString
& aStorageKey
, const nsACString
& aName
);
95 * Creates the connection to the database.
97 * @param aDatabaseFile
98 * The nsIFile of the location of the database to open, or create if it
101 nsresult
initialize(nsIFile
* aDatabaseFile
);
104 * Creates the connection to the database.
107 * The nsIFileURL of the location of the database to open, or create if
110 nsresult
initialize(nsIFileURL
* aFileURL
,
111 const nsACString
& aTelemetryFilename
);
114 * Same as initialize, but to be used on the async thread.
116 nsresult
initializeOnAsyncThread(nsIFile
* aStorageFile
);
119 * Fetches runtime status information for this connection.
121 * @param aStatusOption One of the SQLITE_DBSTATUS options defined at
122 * http://www.sqlite.org/c3ref/c_dbstatus_options.html
123 * @param [optional] aMaxValue if provided, will be set to the highest
124 * istantaneous value.
125 * @return the current value for the specified option.
127 int32_t getSqliteRuntimeStatus(int32_t aStatusOption
,
128 int32_t* aMaxValue
= nullptr);
130 * Registers/unregisters a commit hook callback.
132 * @param aCallbackFn a callback function to be invoked on transactions
133 * commit. Pass nullptr to unregister the current callback.
134 * @param [optional] aData if provided, will be passed to the callback.
135 * @see http://sqlite.org/c3ref/commit_hook.html
137 void setCommitHook(int (*aCallbackFn
)(void*), void* aData
= nullptr) {
138 MOZ_ASSERT(mDBConn
, "A connection must exist at this point");
139 ::sqlite3_commit_hook(mDBConn
, aCallbackFn
, aData
);
143 * Gets autocommit status.
145 bool getAutocommit() {
146 return mDBConn
&& static_cast<bool>(::sqlite3_get_autocommit(mDBConn
));
150 * Lazily creates and returns a background execution thread. In the future,
151 * the thread may be re-claimed if left idle, so you should call this
152 * method just before you dispatch and not save the reference.
154 * This must be called from the opener thread.
156 * @return an event target suitable for asynchronous statement execution.
157 * @note This method will return null once AsyncClose() has been called.
159 nsIEventTarget
* getAsyncExecutionTarget();
162 * Mutex used by asynchronous statements to protect state. The mutex is
163 * declared on the connection object because there is no contention between
164 * asynchronous statements (they are serialized on mAsyncExecutionThread).
165 * Currently protects:
166 * - Connection.mAsyncExecutionThreadShuttingDown
167 * - Connection.mConnectionClosed
168 * - AsyncExecuteStatements.mCancelRequested
170 Mutex sharedAsyncExecutionMutex
;
173 * Wraps the mutex that SQLite gives us from sqlite3_db_mutex. This is public
174 * because we already expose the sqlite3* native connection and proper
175 * operation of the deadlock detector requires everyone to use the same single
176 * SQLiteMutex instance for correctness.
178 SQLiteMutex sharedDBMutex
;
181 * References the thread this database was opened on. This MUST be thread it
184 const nsCOMPtr
<nsIThread
> threadOpenedOn
;
187 * Closes the SQLite database, and warns about any non-finalized statements.
189 nsresult
internalClose(sqlite3
* aDBConn
);
192 * Shuts down the passed-in async thread.
194 void shutdownAsyncThread();
197 * Obtains the filename of the connection. Useful for logging.
199 nsCString
getFilename();
202 * Creates an sqlite3 prepared statement object from an SQL string.
204 * @param aNativeConnection
205 * The underlying Sqlite connection to prepare the statement with.
207 * The SQL statement string to compile.
209 * New sqlite3_stmt object.
210 * @return the result from sqlite3_prepare_v2.
212 int prepareStatement(sqlite3
* aNativeConnection
, const nsCString
& aSQL
,
213 sqlite3_stmt
** _stmt
);
216 * Performs a sqlite3_step on aStatement, while properly handling
217 * SQLITE_LOCKED when not on the main thread by waiting until we are notified.
219 * @param aNativeConnection
220 * The underlying Sqlite connection to step the statement with.
222 * A pointer to a sqlite3_stmt object.
223 * @return the result from sqlite3_step.
225 int stepStatement(sqlite3
* aNativeConnection
, sqlite3_stmt
* aStatement
);
228 * Raw connection transaction management.
230 * @see BeginTransactionAs, CommitTransaction, RollbackTransaction.
232 nsresult
beginTransactionInternal(
233 const SQLiteMutexAutoLock
& aProofOfLock
, sqlite3
* aNativeConnection
,
234 int32_t aTransactionType
= TRANSACTION_DEFERRED
);
235 nsresult
commitTransactionInternal(const SQLiteMutexAutoLock
& aProofOfLock
,
236 sqlite3
* aNativeConnection
);
237 nsresult
rollbackTransactionInternal(const SQLiteMutexAutoLock
& aProofOfLock
,
238 sqlite3
* aNativeConnection
);
241 * Indicates if this database connection is open.
243 inline bool connectionReady() { return mDBConn
!= nullptr; }
246 * Indicates if this database connection has an open transaction. Because
247 * multiple threads can execute statements on the same connection, this method
248 * requires proof that the caller is holding `sharedDBMutex`.
250 * Per the SQLite docs, `sqlite3_get_autocommit` returns 0 if autocommit mode
251 * is disabled. `BEGIN` disables autocommit mode, and `COMMIT`, `ROLLBACK`, or
252 * an automatic rollback re-enables it.
254 inline bool transactionInProgress(const SQLiteMutexAutoLock
& aProofOfLock
) {
255 return !getAutocommit();
259 * Indicates if this database connection supports the given operation.
261 * @param aOperationType
262 * The operation type, sync or async.
263 * @return `true` if the operation is supported, `false` otherwise.
265 bool operationSupported(ConnectionOperation aOperationType
);
268 * Thread-aware version of connectionReady, results per caller's thread are:
269 * - owner thread: Same as connectionReady(). True means we have a valid,
270 * un-closed database connection and it's not going away until you invoke
271 * Close() or AsyncClose().
272 * - async thread: Returns true at all times because you can't schedule
273 * runnables against the async thread after AsyncClose() has been called.
274 * Therefore, the connection is still around if your code is running.
275 * - any other thread: Race-prone Lies! If you are main-thread code in
276 * mozStorageService iterating over the list of connections, you need to
277 * acquire the sharedAsyncExecutionMutex for the connection, invoke
278 * connectionReady() while holding it, and then continue to hold it while
279 * you do whatever you need to do. This is because of off-main-thread
280 * consumers like dom/cache and IndexedDB and other QuotaManager clients.
282 bool isConnectionReadyOnThisThread();
285 * True if this connection has inited shutdown.
290 * True if the underlying connection is closed.
291 * Any sqlite resources may be lost when this returns true, so nothing should
293 * This locks on sharedAsyncExecutionMutex.
298 * Same as isClosed(), but takes a proof-of-lock instead of locking
301 bool isClosed(MutexAutoLock
& lock
);
304 * True if the async execution thread is alive and able to be used (i.e., it
305 * is not in the process of shutting down.)
307 * This must be called from the opener thread.
309 bool isAsyncExecutionThreadAvailable();
311 nsresult
initializeClone(Connection
* aClone
, bool aReadOnly
);
314 * Records a status from a sqlite statement.
316 * @param srv The sqlite result for the failure or SQLITE_OK.
318 void RecordQueryStatus(int srv
);
322 nsresult
initializeInternal();
323 void initializeFailed();
326 * Records the status of an attempt to load a sqlite database to telemetry.
328 * @param rv The state of the load, success or failure.
330 void RecordOpenStatus(nsresult rv
);
333 * Sets the database into a closed state so no further actions can be
336 * @note mDBConn is set to nullptr in this method.
338 nsresult
setClosedState();
341 * Helper for calls to sqlite3_exec. Reports long delays to Telemetry.
343 * @param aNativeConnection
344 * The underlying Sqlite connection to execute the query with.
346 * SQL string to execute
347 * @return the result from sqlite3_exec.
349 int executeSql(sqlite3
* aNativeConnection
, const char* aSqlString
);
352 * Describes a certain primitive type in the database.
354 * Possible Values Are:
355 * INDEX - To check for the existence of an index
356 * TABLE - To check for the existence of a table
358 enum DatabaseElementType
{ INDEX
, TABLE
};
361 * Determines if the specified primitive exists.
363 * @param aElementType
364 * The type of element to check the existence of
365 * @param aElementName
366 * The name of the element to check for
367 * @returns true if element exists, false otherwise
369 nsresult
databaseElementExists(enum DatabaseElementType aElementType
,
370 const nsACString
& aElementName
, bool* _exists
);
372 bool findFunctionByInstance(mozIStorageFunction
* aInstance
);
374 static int sProgressHelper(void* aArg
);
375 // Generic progress handler
376 // Dispatch call to registered progress handler,
377 // if there is one. Do nothing in other cases.
378 int progressHandler();
381 * Like `operationSupported`, but throws (and, in a debug build, asserts) if
382 * the operation is unsupported.
384 nsresult
ensureOperationSupported(ConnectionOperation aOperationType
);
387 nsCString mStorageKey
;
389 nsCOMPtr
<nsIFileURL
> mFileURL
;
390 nsCOMPtr
<nsIFile
> mDatabaseFile
;
393 * Lazily created thread for asynchronous statement execution. Consumers
394 * should use getAsyncExecutionTarget rather than directly accessing this
397 * This must be modified only on the opener thread.
399 nsCOMPtr
<nsIThread
> mAsyncExecutionThread
;
402 * The filename that will be reported to telemetry for this connection. By
403 * default this will be the leaf of the path to the database file.
405 nsCString mTelemetryFilename
;
408 * Stores the default behavior for all transactions run on this connection.
410 mozilla::Atomic
<int32_t> mDefaultTransactionType
;
413 * Used to trigger cleanup logic only the first time our refcount hits 1. We
414 * may trigger a failsafe Close() that invokes SpinningSynchronousClose()
415 * which invokes AsyncClose() which may bump our refcount back up to 2 (and
416 * which will then fall back down to 1 again). It's also possible that the
417 * Service may bump our refcount back above 1 if getConnections() runs before
418 * we invoke unregisterConnection().
420 mozilla::Atomic
<bool> mDestroying
;
423 * Stores the mapping of a given function by name to its instance. Access is
424 * protected by sharedDBMutex.
426 nsTHashMap
<nsCStringHashKey
, FunctionInfo
> mFunctions
;
429 * Stores the registered progress handler for the database connection. Access
430 * is protected by sharedDBMutex.
432 nsCOMPtr
<mozIStorageProgressHandler
> mProgressHandler
;
434 // This is here for two reasons: 1) It's used to make sure that the
435 // connections do not outlive the service. 2) Our custom collating functions
436 // call its localeCompareStrings() method.
437 RefPtr
<Service
> mStorageService
;
439 nsresult
synchronousClose();
442 * Stores the flags we passed to sqlite3_open_v2.
446 uint32_t mTransactionNestingLevel
;
449 * Indicates which operations are supported on this connection.
451 const ConnectionOperation mSupportedOperations
;
454 * Stores whether this connection is interruptible.
456 const bool mInterruptible
;
459 * Stores whether we should ask sqlite3_open_v2 to ignore locking.
461 const bool mIgnoreLockingMode
;
464 * Set to true by Close() or AsyncClose() prior to shutdown.
466 * If false, we guarantee both that the underlying sqlite3 database
467 * connection is still open and that getAsyncExecutionTarget() can
468 * return a thread. Once true, either the sqlite3 database
469 * connection is being shutdown or it has been
470 * shutdown. Additionally, once true, getAsyncExecutionTarget()
473 * This variable should be accessed while holding the
474 * sharedAsyncExecutionMutex.
476 bool mAsyncExecutionThreadShuttingDown
;
479 * Set to true just prior to calling sqlite3_close on the
482 * This variable should be accessed while holding the
483 * sharedAsyncExecutionMutex.
485 bool mConnectionClosed
;
489 * A Runnable designed to call a mozIStorageCompletionCallback on
490 * the appropriate thread.
492 class CallbackComplete final
: public Runnable
{
495 * @param aValue The result to pass to the callback. It must
496 * already be owned by the main thread.
497 * @param aCallback The callback. It must already be owned by the
500 CallbackComplete(nsresult aStatus
, nsISupports
* aValue
,
501 already_AddRefed
<mozIStorageCompletionCallback
> aCallback
)
502 : Runnable("storage::CallbackComplete"),
505 mCallback(aCallback
) {}
507 NS_IMETHOD
Run() override
{
508 MOZ_ASSERT(NS_IsMainThread());
509 nsresult rv
= mCallback
->Complete(mStatus
, mValue
);
511 // Ensure that we release on the main thread
519 nsCOMPtr
<nsISupports
> mValue
;
520 // This is a RefPtr<T> and not a nsCOMPtr<T> because
521 // nsCOMP<T> would cause an off-main thread QI, which
522 // is not a good idea (and crashes XPConnect).
523 RefPtr
<mozIStorageCompletionCallback
> mCallback
;
526 } // namespace storage
527 } // namespace mozilla
530 * Casting Connection to nsISupports is ambiguous.
531 * This method handles that.
533 inline nsISupports
* ToSupports(mozilla::storage::Connection
* p
) {
534 return NS_ISUPPORTS_CAST(mozIStorageAsyncConnection
*, p
);
537 #endif // mozilla_storage_Connection_h