tor-browser

mozStorageConnection.h (19257B)

---

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
* vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ :
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef mozilla_storage_Connection_h
#define mozilla_storage_Connection_h

#include "nsCOMPtr.h"
#include "mozilla/Atomics.h"
#include "mozilla/Mutex.h"
#include "nsProxyRelease.h"
#include "nsThreadUtils.h"
#include "nsIInterfaceRequestor.h"

#include "nsTHashMap.h"
#include "nsTHashSet.h"
#include "mozIStorageProgressHandler.h"
#include "SQLiteMutex.h"
#include "mozIStorageConnection.h"
#include "mozStorageService.h"
#include "mozIStorageAsyncConnection.h"
#include "mozIStorageCompletionCallback.h"

#include "mozilla/Attributes.h"

#include "sqlite3.h"

class nsIFile;
class nsIFileURL;
class nsIEventTarget;
class nsISerialEventTarget;
class nsIThread;

namespace mozilla::storage {

class Connection final : public mozIStorageConnection,
                        public nsIInterfaceRequestor {
public:
 NS_DECL_THREADSAFE_ISUPPORTS
 NS_DECL_MOZISTORAGEASYNCCONNECTION
 NS_DECL_MOZISTORAGECONNECTION
 NS_DECL_NSIINTERFACEREQUESTOR

 /**
  * Indicates if a database operation is synchronous or asynchronous.
  *
  * - Async operations may be called from any thread for all connections.
  * - Sync operations may be called from any thread for sync connections, and
  *   from background threads for async connections.
  */
 enum ConnectionOperation { ASYNCHRONOUS, SYNCHRONOUS };

 /**
  * Structure used to describe user functions on the database connection.
  */
 struct FunctionInfo {
   nsCOMPtr<mozIStorageFunction> function;
   int32_t numArgs;
 };

 /**
  * @param aService
  *        Pointer to the storage service.  Held onto for the lifetime of the
  *        connection.
  * @param aFlags
  *        The flags to pass to sqlite3_open_v2.
  * @param aSupportedOperations
  *        The operation types supported on this connection. All connections
  *        implement both the async (`mozIStorageAsyncConnection`) and sync
  *        (`mozIStorageConnection`) interfaces, but async connections may not
  *        call sync operations from the main thread.
  * @param aInterruptible
  *        If |true|, the pending operations can be interrupted by invokind the
  *        Interrupt() method.
  *        If |false|, method Interrupt() must not be used.
  * @param aIgnoreLockingMode
  *        If |true|, ignore locks in force on the file. Only usable with
  *        read-only connections. Defaults to false.
  *        Use with extreme caution. If sqlite ignores locks, reads may fail
  *        indicating database corruption (the database won't actually be
  *        corrupt) or produce wrong results without any indication that has
  *        happened.
  */
 Connection(Service* aService, int aFlags,
            ConnectionOperation aSupportedOperations,
            const nsCString& aTelemetryFilename, bool aInterruptible = false,
            bool aIgnoreLockingMode = false, bool aOpenNotExclusive = false);

 /**
  * Creates the connection to an in-memory database.
  */
 nsresult initialize(const nsACString& aStorageKey, const nsACString& aName);

 /**
  * Creates the connection to the database.
  *
  * @param aDatabaseFile
  *        The nsIFile of the location of the database to open, or create if it
  *        does not exist.
  */
 nsresult initialize(nsIFile* aDatabaseFile);

 /**
  * Creates the connection to the database.
  *
  * @param aFileURL
  *        The nsIFileURL of the location of the database to open, or create if
  * it does not exist.
  */
 nsresult initialize(nsIFileURL* aFileURL);

 /**
  * Same as initialize, but to be used on the async thread.
  */
 nsresult initializeOnAsyncThread(nsIFile* aStorageFile);

 /**
  * Fetches runtime status information for this connection.
  *
  * @param aStatusOption One of the SQLITE_DBSTATUS options defined at
  *        http://www.sqlite.org/c3ref/c_dbstatus_options.html
  * @param [optional] aMaxValue if provided, will be set to the highest
  *        istantaneous value.
  * @return the current value for the specified option.
  */
 int32_t getSqliteRuntimeStatus(int32_t aStatusOption,
                                int32_t* aMaxValue = nullptr);
 /**
  * Registers/unregisters a commit hook callback.
  *
  * @param aCallbackFn a callback function to be invoked on transactions
  *        commit.  Pass nullptr to unregister the current callback.
  * @param [optional] aData if provided, will be passed to the callback.
  * @see http://sqlite.org/c3ref/commit_hook.html
  */
 void setCommitHook(int (*aCallbackFn)(void*), void* aData = nullptr) {
   MOZ_ASSERT(mDBConn, "A connection must exist at this point");
   ::sqlite3_commit_hook(mDBConn, aCallbackFn, aData);
 };

 /**
  * Gets autocommit status.
  */
 bool getAutocommit() {
   return mDBConn && static_cast<bool>(::sqlite3_get_autocommit(mDBConn));
 };

 /**
  * Lazily creates and returns a background execution thread.  In the future,
  * the thread may be re-claimed if left idle, so you should call this
  * method just before you dispatch and not save the reference.
  *
  * This must be called from the opener thread.
  *
  * @return an event target suitable for asynchronous statement execution.
  * @note This method will return null once AsyncClose() has been called.
  */
 nsIEventTarget* getAsyncExecutionTarget();

 /**
  * Mutex used by asynchronous statements to protect state.  The mutex is
  * declared on the connection object because there is no contention between
  * asynchronous statements (they are serialized on mAsyncExecutionThread).
  * Currently protects:
  *  - Connection.mAsyncExecutionThreadShuttingDown
  *  - Connection.mConnectionClosed
  *  - AsyncExecuteStatements.mCancelRequested
  *  - Connection.mLoadedExtensions
  */
 Mutex sharedAsyncExecutionMutex MOZ_UNANNOTATED;

 /**
  * Wraps the mutex that SQLite gives us from sqlite3_db_mutex.  This is public
  * because we already expose the sqlite3* native connection and proper
  * operation of the deadlock detector requires everyone to use the same single
  * SQLiteMutex instance for correctness.
  */
 SQLiteMutex sharedDBMutex;

 /**
  * References the event target this database was opened on.
  */
 const nsCOMPtr<nsISerialEventTarget> eventTargetOpenedOn;

 /**
  * Closes the SQLite database, and warns about any non-finalized statements.
  */
 nsresult internalClose(sqlite3* aNativeconnection);

 /**
  * Shuts down the passed-in async thread.
  */
 void shutdownAsyncThread();

 /**
  * Obtains the filename of the connection.  Useful for logging.
  */
 nsCString getFilename();

 /**
  * Creates an sqlite3 prepared statement object from an SQL string.
  *
  * @param aNativeConnection
  *        The underlying Sqlite connection to prepare the statement with.
  * @param aSQL
  *        The SQL statement string to compile.
  * @param _stmt
  *        New sqlite3_stmt object.
  * @return the result from sqlite3_prepare_v2.
  */
 int prepareStatement(sqlite3* aNativeConnection, const nsCString& aSQL,
                      sqlite3_stmt** _stmt);

 /**
  * Performs a sqlite3_step on aStatement, while properly handling
  * SQLITE_LOCKED when not on the main thread by waiting until we are notified.
  *
  * @param aNativeConnection
  *        The underlying Sqlite connection to step the statement with.
  * @param aStatement
  *        A pointer to a sqlite3_stmt object.
  * @return the result from sqlite3_step.
  */
 int stepStatement(sqlite3* aNativeConnection, sqlite3_stmt* aStatement);

 /**
  * Raw connection transaction management.
  *
  * @see BeginTransactionAs, CommitTransaction, RollbackTransaction.
  */
 nsresult beginTransactionInternal(
     const SQLiteMutexAutoLock& aProofOfLock, sqlite3* aNativeConnection,
     int32_t aTransactionType = TRANSACTION_DEFERRED);
 nsresult commitTransactionInternal(const SQLiteMutexAutoLock& aProofOfLock,
                                    sqlite3* aNativeConnection);
 nsresult rollbackTransactionInternal(const SQLiteMutexAutoLock& aProofOfLock,
                                      sqlite3* aNativeConnection);

 /**
  * Indicates if this database connection is open.
  */
 inline bool connectionReady() { return mDBConn != nullptr; }

 /**
  * Indicates if this database connection has an open transaction. Because
  * multiple threads can execute statements on the same connection, this method
  * requires proof that the caller is holding `sharedDBMutex`.
  *
  * Per the SQLite docs, `sqlite3_get_autocommit` returns 0 if autocommit mode
  * is disabled. `BEGIN` disables autocommit mode, and `COMMIT`, `ROLLBACK`, or
  * an automatic rollback re-enables it.
  */
 inline bool transactionInProgress(const SQLiteMutexAutoLock& aProofOfLock) {
   return !getAutocommit();
 }

 /**
  * Indicates if this database connection supports the given operation.
  *
  * @param  aOperationType
  *         The operation type, sync or async.
  * @return `true` if the operation is supported, `false` otherwise.
  */
 bool operationSupported(ConnectionOperation aOperationType);

 /**
  * Thread-aware version of connectionReady, results per caller's thread are:
  *  - owner thread: Same as connectionReady().  True means we have a valid,
  *    un-closed database connection and it's not going away until you invoke
  *    Close() or AsyncClose().
  *  - async thread: Returns true at all times because you can't schedule
  *    runnables against the async thread after AsyncClose() has been called.
  *    Therefore, the connection is still around if your code is running.
  *  - any other thread: Race-prone Lies!  If you are main-thread code in
  *    mozStorageService iterating over the list of connections, you need to
  *    acquire the sharedAsyncExecutionMutex for the connection, invoke
  *    connectionReady() while holding it, and then continue to hold it while
  *    you do whatever you need to do.  This is because of off-main-thread
  *    consumers like dom/cache and IndexedDB and other QuotaManager clients.
  */
 bool isConnectionReadyOnThisThread();

 /**
  * True if this connection has inited shutdown.
  */
 bool isClosing();

 /**
  * True if the underlying connection is closed.
  * Any sqlite resources may be lost when this returns true, so nothing should
  * try to use them.
  * This locks on sharedAsyncExecutionMutex.
  */
 bool isClosed();

 /**
  * Same as isClosed(), but takes a proof-of-lock instead of locking
  * internally.
  */
 bool isClosed(MutexAutoLock& lock);

 /**
  * True if the async execution thread is alive and able to be used (i.e., it
  * is not in the process of shutting down.)
  *
  * This must be called from the opener thread.
  */
 bool isAsyncExecutionThreadAvailable();

 nsresult initializeClone(Connection* aClone, bool aReadOnly);

 /**
  * Records a status from a sqlite statement.
  *
  * @param srv The sqlite result for the failure or SQLITE_OK.
  */
 void RecordQueryStatus(int srv);

 /**
  * Returns the number of pages in the free list that can be removed.
  *
  * A database may use chunked growth to reduce filesystem fragmentation, then
  * Sqlite will allocate and release multiple pages in chunks. We want to
  * preserve the chunked space to reduce the likelihood of fragmentation,
  * releasing free pages only when there's a large amount of them. This can be
  * used to decide if it's worth vacuuming the database and how many pages can
  * be vacuumed in case of incremental vacuum.
  * Note this returns 0, and asserts, in case of errors.
  */
 int32_t RemovablePagesInFreeList(const nsACString& aSchemaName);

 /**
  * Whether the statement currently running on the helper thread can be
  * interrupted.
  */
 Atomic<bool> mIsStatementOnHelperThreadInterruptible;

private:
 ~Connection();
 nsresult initializeInternal();
 void initializeFailed();

 /**
  * Records the status of an attempt to load a sqlite database to telemetry.
  *
  * @param rv The state of the load, success or failure.
  */
 void RecordOpenStatus(nsresult rv);

 /**
  * Sets the database into a closed state so no further actions can be
  * performed.
  *
  * @note mDBConn is set to nullptr in this method.
  */
 nsresult setClosedState();

 /**
  * Helper for calls to sqlite3_exec. Reports long delays to Telemetry.
  *
  * @param aNativeConnection
  *        The underlying Sqlite connection to execute the query with.
  * @param aSqlString
  *        SQL string to execute
  * @return the result from sqlite3_exec.
  */
 int executeSql(sqlite3* aNativeConnection, const char* aSqlString);

 /**
  * Describes a certain primitive type in the database.
  *
  * Possible Values Are:
  *  INDEX - To check for the existence of an index
  *  TABLE - To check for the existence of a table
  */
 enum DatabaseElementType { INDEX, TABLE };

 /**
  * Determines if the specified primitive exists.
  *
  * @param aElementType
  *        The type of element to check the existence of
  * @param aElementName
  *        The name of the element to check for
  * @returns true if element exists, false otherwise
  */
 nsresult databaseElementExists(enum DatabaseElementType aElementType,
                                const nsACString& aElementName, bool* _exists);

 bool findFunctionByInstance(mozIStorageFunction* aInstance);

 static int sProgressHelper(void* aArg);
 // Generic progress handler
 // Dispatch call to registered progress handler,
 // if there is one. Do nothing in other cases.
 int progressHandler();

 /**
  * Like `operationSupported`, but throws (and, in a debug build, asserts) if
  * the operation is unsupported.
  */
 nsresult ensureOperationSupported(ConnectionOperation aOperationType);

 sqlite3* mDBConn;
 nsCString mStorageKey;
 nsCString mName;
 nsCOMPtr<nsIFileURL> mFileURL;
 nsCOMPtr<nsIFile> mDatabaseFile;

 /**
  * Lazily created thread for asynchronous statement execution.  Consumers
  * should use getAsyncExecutionTarget rather than directly accessing this
  * field.
  *
  * This must be modified only on the opener thread.
  */
 nsCOMPtr<nsIThread> mAsyncExecutionThread;

 /**
  * The filename that will be reported to telemetry for this connection. By
  * default this will be the leaf of the path to the database file.
  */
 nsCString mTelemetryFilename;

 /**
  * Stores the default behavior for all transactions run on this connection.
  */
 mozilla::Atomic<int32_t> mDefaultTransactionType;

 /**
  * Used to trigger cleanup logic only the first time our refcount hits 1.  We
  * may trigger a failsafe Close() that invokes SpinningSynchronousClose()
  * which invokes AsyncClose() which may bump our refcount back up to 2 (and
  * which will then fall back down to 1 again).  It's also possible that the
  * Service may bump our refcount back above 1 if getConnections() runs before
  * we invoke unregisterConnection().
  */
 mozilla::Atomic<bool> mDestroying;

 /**
  * Stores the mapping of a given function by name to its instance.  Access is
  * protected by sharedDBMutex.
  */
 nsTHashMap<nsCStringHashKey, FunctionInfo> mFunctions;

 /**
  * Stores the registered progress handler for the database connection.  Access
  * is protected by sharedDBMutex.
  */
 nsCOMPtr<mozIStorageProgressHandler> mProgressHandler;

 // This is here for two reasons: 1) It's used to make sure that the
 // connections do not outlive the service.  2) Our custom collating functions
 // call its localeCompareStrings() method.
 RefPtr<Service> mStorageService;

 nsresult synchronousClose();

 /**
  * Stores the flags we passed to sqlite3_open_v2.
  */
 const int mFlags;

 uint32_t mTransactionNestingLevel;

 /**
  * Indicates which operations are supported on this connection.
  */
 const ConnectionOperation mSupportedOperations;

 /**
  * Stores whether this connection is interruptible.
  */
 const bool mInterruptible;

 /**
  * Stores whether we should ask sqlite3_open_v2 to ignore locking.
  */
 const bool mIgnoreLockingMode;

 /**
  * Stores whether we should ask sqlite3_open_v2 to open without an exclusive
  * lock.
  */
 const bool mOpenNotExclusive;

 /**
  * Set to true by Close() or AsyncClose() prior to shutdown.
  *
  * If false, we guarantee both that the underlying sqlite3 database
  * connection is still open and that getAsyncExecutionTarget() can
  * return a thread. Once true, either the sqlite3 database
  * connection is being shutdown or it has been
  * shutdown. Additionally, once true, getAsyncExecutionTarget()
  * returns null.
  *
  * This variable should be accessed while holding the
  * sharedAsyncExecutionMutex.
  */
 bool mAsyncExecutionThreadShuttingDown;

 /**
  * Set to true just prior to calling sqlite3_close on the
  * connection.
  *
  * This variable should be accessed while holding the
  * sharedAsyncExecutionMutex.
  */
 bool mConnectionClosed;

 /**
  * Stores the growth increment chunk size, set through SetGrowthIncrement().
  */
 Atomic<int32_t> mGrowthChunkSize;

 /**
  * Stores a list of the SQLite extensions loaded for this connections.
  * This is used to properly clone the connection.
  * @note Hold sharedAsyncExecutionMutex while using this.
  */
 nsTHashSet<nsCString> mLoadedExtensions
     MOZ_GUARDED_BY(sharedAsyncExecutionMutex);
};

/**
* A Runnable designed to call a mozIStorageCompletionCallback on
* the appropriate thread.
*/
class CallbackComplete final : public Runnable {
public:
 /**
  * @param aValue The result to pass to the callback. It must
  *               already be owned by the main thread.
  * @param aCallback The callback. It must already be owned by the
  *                  main thread.
  */
 CallbackComplete(nsresult aStatus, nsISupports* aValue,
                  already_AddRefed<mozIStorageCompletionCallback> aCallback)
     : Runnable("storage::CallbackComplete"),
       mStatus(aStatus),
       mValue(aValue),
       mCallback(aCallback) {}

 NS_IMETHOD Run() override {
   MOZ_ASSERT(NS_IsMainThread());
   nsresult rv = mCallback->Complete(mStatus, mValue);

   // Ensure that we release on the main thread
   mValue = nullptr;
   mCallback = nullptr;
   return rv;
 }

private:
 nsresult mStatus;
 nsCOMPtr<nsISupports> mValue;
 // This is a RefPtr<T> and not a nsCOMPtr<T> because
 // nsCOMP<T> would cause an off-main thread QI, which
 // is not a good idea (and crashes XPConnect).
 RefPtr<mozIStorageCompletionCallback> mCallback;
};

}  // namespace mozilla::storage

/**
* Casting Connection to nsISupports is ambiguous.
* This method handles that.
*/
inline nsISupports* ToSupports(mozilla::storage::Connection* p) {
 return NS_ISUPPORTS_CAST(mozIStorageAsyncConnection*, p);
}

#endif  // mozilla_storage_Connection_h