storage/mozStorageConnection.h

   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/. */
   6
   7 #ifndef mozilla_storage_Connection_h
   8 #define mozilla_storage_Connection_h
   9
  10 #include "nsCOMPtr.h"
  11 #include "mozilla/Atomics.h"
  12 #include "mozilla/Mutex.h"
  13 #include "nsProxyRelease.h"
  14 #include "nsThreadUtils.h"
  15 #include "nsIInterfaceRequestor.h"
  16
  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"
  24
  25 #include "mozilla/Attributes.h"
  26
  27 #include "sqlite3.h"
  28
  29 class nsIFile;
  30 class nsIFileURL;
  31 class nsIEventTarget;
  32 class nsIThread;
  33
  34 namespace mozilla {
  35 namespace storage {
  36
  37 class Connection final : public mozIStorageConnection,
  38                          public nsIInterfaceRequestor {
  39  public:
  40   NS_DECL_THREADSAFE_ISUPPORTS
  41   NS_DECL_MOZISTORAGEASYNCCONNECTION
  42   NS_DECL_MOZISTORAGECONNECTION
  43   NS_DECL_NSIINTERFACEREQUESTOR
  44
  45   /**
  46    * Indicates if a database operation is synchronous or asynchronous.
  47    *
  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.
  51    */
  52   enum ConnectionOperation { ASYNCHRONOUS, SYNCHRONOUS };
  53
  54   /**
  55    * Structure used to describe user functions on the database connection.
  56    */
  57   struct FunctionInfo {
  58     nsCOMPtr<mozIStorageFunction> function;
  59     int32_t numArgs;
  60   };
  61
  62   /**
  63    * @param aService
  64    *        Pointer to the storage service.  Held onto for the lifetime of the
  65    *        connection.
  66    * @param aFlags
  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 aIgnoreLockingMode
  74    *        If |true|, ignore locks in force on the file. Only usable with
  75    *        read-only connections. Defaults to false.
  76    *        Use with extreme caution. If sqlite ignores locks, reads may fail
  77    *        indicating database corruption (the database won't actually be
  78    *        corrupt) or produce wrong results without any indication that has
  79    *        happened.
  80    */
  81   Connection(Service* aService, int aFlags,
  82              ConnectionOperation aSupportedOperations,
  83              bool aIgnoreLockingMode = false);
  84
  85   /**
  86    * Creates the connection to an in-memory database.
  87    */
  88   nsresult initialize(const nsACString& aStorageKey, const nsACString& aName);
  89
  90   /**
  91    * Creates the connection to the database.
  92    *
  93    * @param aDatabaseFile
  94    *        The nsIFile of the location of the database to open, or create if it
  95    *        does not exist.
  96    */
  97   nsresult initialize(nsIFile* aDatabaseFile);
  98
  99   /**
 100    * Creates the connection to the database.
 101    *
 102    * @param aFileURL
 103    *        The nsIFileURL of the location of the database to open, or create if
 104    * it does not exist.
 105    */
 106   nsresult initialize(nsIFileURL* aFileURL,
 107                       const nsACString& aTelemetryFilename);
 108
 109   /**
 110    * Same as initialize, but to be used on the async thread.
 111    */
 112   nsresult initializeOnAsyncThread(nsIFile* aStorageFile);
 113
 114   /**
 115    * Fetches runtime status information for this connection.
 116    *
 117    * @param aStatusOption One of the SQLITE_DBSTATUS options defined at
 118    *        http://www.sqlite.org/c3ref/c_dbstatus_options.html
 119    * @param [optional] aMaxValue if provided, will be set to the highest
 120    *        istantaneous value.
 121    * @return the current value for the specified option.
 122    */
 123   int32_t getSqliteRuntimeStatus(int32_t aStatusOption,
 124                                  int32_t* aMaxValue = nullptr);
 125   /**
 126    * Registers/unregisters a commit hook callback.
 127    *
 128    * @param aCallbackFn a callback function to be invoked on transactions
 129    *        commit.  Pass nullptr to unregister the current callback.
 130    * @param [optional] aData if provided, will be passed to the callback.
 131    * @see http://sqlite.org/c3ref/commit_hook.html
 132    */
 133   void setCommitHook(int (*aCallbackFn)(void*), void* aData = nullptr) {
 134     MOZ_ASSERT(mDBConn, "A connection must exist at this point");
 135     ::sqlite3_commit_hook(mDBConn, aCallbackFn, aData);
 136   };
 137
 138   /**
 139    * Gets autocommit status.
 140    */
 141   bool getAutocommit() {
 142     return mDBConn && static_cast<bool>(::sqlite3_get_autocommit(mDBConn));
 143   };
 144
 145   /**
 146    * Lazily creates and returns a background execution thread.  In the future,
 147    * the thread may be re-claimed if left idle, so you should call this
 148    * method just before you dispatch and not save the reference.
 149    *
 150    * This must be called from the opener thread.
 151    *
 152    * @return an event target suitable for asynchronous statement execution.
 153    * @note This method will return null once AsyncClose() has been called.
 154    */
 155   nsIEventTarget* getAsyncExecutionTarget();
 156
 157   /**
 158    * Mutex used by asynchronous statements to protect state.  The mutex is
 159    * declared on the connection object because there is no contention between
 160    * asynchronous statements (they are serialized on mAsyncExecutionThread).
 161    * Currently protects:
 162    *  - Connection.mAsyncExecutionThreadShuttingDown
 163    *  - Connection.mConnectionClosed
 164    *  - AsyncExecuteStatements.mCancelRequested
 165    */
 166   Mutex sharedAsyncExecutionMutex;
 167
 168   /**
 169    * Wraps the mutex that SQLite gives us from sqlite3_db_mutex.  This is public
 170    * because we already expose the sqlite3* native connection and proper
 171    * operation of the deadlock detector requires everyone to use the same single
 172    * SQLiteMutex instance for correctness.
 173    */
 174   SQLiteMutex sharedDBMutex;
 175
 176   /**
 177    * References the thread this database was opened on.  This MUST be thread it
 178    * is closed on.
 179    */
 180   const nsCOMPtr<nsIThread> threadOpenedOn;
 181
 182   /**
 183    * Closes the SQLite database, and warns about any non-finalized statements.
 184    */
 185   nsresult internalClose(sqlite3* aDBConn);
 186
 187   /**
 188    * Shuts down the passed-in async thread.
 189    */
 190   void shutdownAsyncThread();
 191
 192   /**
 193    * Obtains the filename of the connection.  Useful for logging.
 194    */
 195   nsCString getFilename();
 196
 197   /**
 198    * Creates an sqlite3 prepared statement object from an SQL string.
 199    *
 200    * @param aNativeConnection
 201    *        The underlying Sqlite connection to prepare the statement with.
 202    * @param aSQL
 203    *        The SQL statement string to compile.
 204    * @param _stmt
 205    *        New sqlite3_stmt object.
 206    * @return the result from sqlite3_prepare_v2.
 207    */
 208   int prepareStatement(sqlite3* aNativeConnection, const nsCString& aSQL,
 209                        sqlite3_stmt** _stmt);
 210
 211   /**
 212    * Performs a sqlite3_step on aStatement, while properly handling
 213    * SQLITE_LOCKED when not on the main thread by waiting until we are notified.
 214    *
 215    * @param aNativeConnection
 216    *        The underlying Sqlite connection to step the statement with.
 217    * @param aStatement
 218    *        A pointer to a sqlite3_stmt object.
 219    * @return the result from sqlite3_step.
 220    */
 221   int stepStatement(sqlite3* aNativeConnection, sqlite3_stmt* aStatement);
 222
 223   /**
 224    * Raw connection transaction management.
 225    *
 226    * @see BeginTransactionAs, CommitTransaction, RollbackTransaction.
 227    */
 228   nsresult beginTransactionInternal(
 229       const SQLiteMutexAutoLock& aProofOfLock, sqlite3* aNativeConnection,
 230       int32_t aTransactionType = TRANSACTION_DEFERRED);
 231   nsresult commitTransactionInternal(const SQLiteMutexAutoLock& aProofOfLock,
 232                                      sqlite3* aNativeConnection);
 233   nsresult rollbackTransactionInternal(const SQLiteMutexAutoLock& aProofOfLock,
 234                                        sqlite3* aNativeConnection);
 235
 236   /**
 237    * Indicates if this database connection is open.
 238    */
 239   inline bool connectionReady() { return mDBConn != nullptr; }
 240
 241   /**
 242    * Indicates if this database connection has an open transaction. Because
 243    * multiple threads can execute statements on the same connection, this method
 244    * requires proof that the caller is holding `sharedDBMutex`.
 245    *
 246    * Per the SQLite docs, `sqlite3_get_autocommit` returns 0 if autocommit mode
 247    * is disabled. `BEGIN` disables autocommit mode, and `COMMIT`, `ROLLBACK`, or
 248    * an automatic rollback re-enables it.
 249    */
 250   inline bool transactionInProgress(const SQLiteMutexAutoLock& aProofOfLock) {
 251     return !getAutocommit();
 252   }
 253
 254   /**
 255    * Indicates if this database connection supports the given operation.
 256    *
 257    * @param  aOperationType
 258    *         The operation type, sync or async.
 259    * @return `true` if the operation is supported, `false` otherwise.
 260    */
 261   bool operationSupported(ConnectionOperation aOperationType);
 262
 263   /**
 264    * Thread-aware version of connectionReady, results per caller's thread are:
 265    *  - owner thread: Same as connectionReady().  True means we have a valid,
 266    *    un-closed database connection and it's not going away until you invoke
 267    *    Close() or AsyncClose().
 268    *  - async thread: Returns true at all times because you can't schedule
 269    *    runnables against the async thread after AsyncClose() has been called.
 270    *    Therefore, the connection is still around if your code is running.
 271    *  - any other thread: Race-prone Lies!  If you are main-thread code in
 272    *    mozStorageService iterating over the list of connections, you need to
 273    *    acquire the sharedAsyncExecutionMutex for the connection, invoke
 274    *    connectionReady() while holding it, and then continue to hold it while
 275    *    you do whatever you need to do.  This is because of off-main-thread
 276    *    consumers like dom/cache and IndexedDB and other QuotaManager clients.
 277    */
 278   bool isConnectionReadyOnThisThread();
 279
 280   /**
 281    * True if this connection has inited shutdown.
 282    */
 283   bool isClosing();
 284
 285   /**
 286    * True if the underlying connection is closed.
 287    * Any sqlite resources may be lost when this returns true, so nothing should
 288    * try to use them.
 289    * This locks on sharedAsyncExecutionMutex.
 290    */
 291   bool isClosed();
 292
 293   /**
 294    * Same as isClosed(), but takes a proof-of-lock instead of locking
 295    * internally.
 296    */
 297   bool isClosed(MutexAutoLock& lock);
 298
 299   /**
 300    * True if the async execution thread is alive and able to be used (i.e., it
 301    * is not in the process of shutting down.)
 302    *
 303    * This must be called from the opener thread.
 304    */
 305   bool isAsyncExecutionThreadAvailable();
 306
 307   nsresult initializeClone(Connection* aClone, bool aReadOnly);
 308
 309   /**
 310    * Records a status from a sqlite statement.
 311    *
 312    * @param srv The sqlite result for the failure or SQLITE_OK.
 313    */
 314   void RecordQueryStatus(int srv);
 315
 316  private:
 317   ~Connection();
 318   nsresult initializeInternal();
 319   void initializeFailed();
 320
 321   /**
 322    * Records the status of an attempt to load a sqlite database to telemetry.
 323    *
 324    * @param rv The state of the load, success or failure.
 325    */
 326   void RecordOpenStatus(nsresult rv);
 327
 328   /**
 329    * Sets the database into a closed state so no further actions can be
 330    * performed.
 331    *
 332    * @note mDBConn is set to nullptr in this method.
 333    */
 334   nsresult setClosedState();
 335
 336   /**
 337    * Helper for calls to sqlite3_exec. Reports long delays to Telemetry.
 338    *
 339    * @param aNativeConnection
 340    *        The underlying Sqlite connection to execute the query with.
 341    * @param aSqlString
 342    *        SQL string to execute
 343    * @return the result from sqlite3_exec.
 344    */
 345   int executeSql(sqlite3* aNativeConnection, const char* aSqlString);
 346
 347   /**
 348    * Describes a certain primitive type in the database.
 349    *
 350    * Possible Values Are:
 351    *  INDEX - To check for the existence of an index
 352    *  TABLE - To check for the existence of a table
 353    */
 354   enum DatabaseElementType { INDEX, TABLE };
 355
 356   /**
 357    * Determines if the specified primitive exists.
 358    *
 359    * @param aElementType
 360    *        The type of element to check the existence of
 361    * @param aElementName
 362    *        The name of the element to check for
 363    * @returns true if element exists, false otherwise
 364    */
 365   nsresult databaseElementExists(enum DatabaseElementType aElementType,
 366                                  const nsACString& aElementName, bool* _exists);
 367
 368   bool findFunctionByInstance(mozIStorageFunction* aInstance);
 369
 370   static int sProgressHelper(void* aArg);
 371   // Generic progress handler
 372   // Dispatch call to registered progress handler,
 373   // if there is one. Do nothing in other cases.
 374   int progressHandler();
 375
 376   /**
 377    * Like `operationSupported`, but throws (and, in a debug build, asserts) if
 378    * the operation is unsupported.
 379    */
 380   nsresult ensureOperationSupported(ConnectionOperation aOperationType);
 381
 382   sqlite3* mDBConn;
 383   nsCString mStorageKey;
 384   nsCString mName;
 385   nsCOMPtr<nsIFileURL> mFileURL;
 386   nsCOMPtr<nsIFile> mDatabaseFile;
 387
 388   /**
 389    * The filename that will be reported to telemetry for this connection. By
 390    * default this will be the leaf of the path to the database file.
 391    */
 392   nsCString mTelemetryFilename;
 393
 394   /**
 395    * Lazily created thread for asynchronous statement execution.  Consumers
 396    * should use getAsyncExecutionTarget rather than directly accessing this
 397    * field.
 398    *
 399    * This must be modified only on the opener thread.
 400    */
 401   nsCOMPtr<nsIThread> mAsyncExecutionThread;
 402
 403   /**
 404    * Set to true by Close() or AsyncClose() prior to shutdown.
 405    *
 406    * If false, we guarantee both that the underlying sqlite3 database
 407    * connection is still open and that getAsyncExecutionTarget() can
 408    * return a thread. Once true, either the sqlite3 database
 409    * connection is being shutdown or it has been
 410    * shutdown. Additionally, once true, getAsyncExecutionTarget()
 411    * returns null.
 412    *
 413    * This variable should be accessed while holding the
 414    * sharedAsyncExecutionMutex.
 415    */
 416   bool mAsyncExecutionThreadShuttingDown;
 417
 418   /**
 419    * Set to true just prior to calling sqlite3_close on the
 420    * connection.
 421    *
 422    * This variable should be accessed while holding the
 423    * sharedAsyncExecutionMutex.
 424    */
 425   bool mConnectionClosed;
 426
 427   /**
 428    * Stores the default behavior for all transactions run on this connection.
 429    */
 430   mozilla::Atomic<int32_t> mDefaultTransactionType;
 431
 432   /**
 433    * Used to trigger cleanup logic only the first time our refcount hits 1.  We
 434    * may trigger a failsafe Close() that invokes SpinningSynchronousClose()
 435    * which invokes AsyncClose() which may bump our refcount back up to 2 (and
 436    * which will then fall back down to 1 again).  It's also possible that the
 437    * Service may bump our refcount back above 1 if getConnections() runs before
 438    * we invoke unregisterConnection().
 439    */
 440   mozilla::Atomic<bool> mDestroying;
 441
 442   /**
 443    * Stores the mapping of a given function by name to its instance.  Access is
 444    * protected by sharedDBMutex.
 445    */
 446   nsTHashMap<nsCStringHashKey, FunctionInfo> mFunctions;
 447
 448   /**
 449    * Stores the registered progress handler for the database connection.  Access
 450    * is protected by sharedDBMutex.
 451    */
 452   nsCOMPtr<mozIStorageProgressHandler> mProgressHandler;
 453
 454   /**
 455    * Stores the flags we passed to sqlite3_open_v2.
 456    */
 457   const int mFlags;
 458
 459   /**
 460    * Stores whether we should ask sqlite3_open_v2 to ignore locking.
 461    */
 462   const bool mIgnoreLockingMode;
 463
 464   // This is here for two reasons: 1) It's used to make sure that the
 465   // connections do not outlive the service.  2) Our custom collating functions
 466   // call its localeCompareStrings() method.
 467   RefPtr<Service> mStorageService;
 468
 469   /**
 470    * Indicates which operations are supported on this connection.
 471    */
 472   const ConnectionOperation mSupportedOperations;
 473
 474   nsresult synchronousClose();
 475
 476   uint32_t mTransactionNestingLevel;
 477 };
 478
 479 /**
 480  * A Runnable designed to call a mozIStorageCompletionCallback on
 481  * the appropriate thread.
 482  */
 483 class CallbackComplete final : public Runnable {
 484  public:
 485   /**
 486    * @param aValue The result to pass to the callback. It must
 487    *               already be owned by the main thread.
 488    * @param aCallback The callback. It must already be owned by the
 489    *                  main thread.
 490    */
 491   CallbackComplete(nsresult aStatus, nsISupports* aValue,
 492                    already_AddRefed<mozIStorageCompletionCallback> aCallback)
 493       : Runnable("storage::CallbackComplete"),
 494         mStatus(aStatus),
 495         mValue(aValue),
 496         mCallback(aCallback) {}
 497
 498   NS_IMETHOD Run() override {
 499     MOZ_ASSERT(NS_IsMainThread());
 500     nsresult rv = mCallback->Complete(mStatus, mValue);
 501
 502     // Ensure that we release on the main thread
 503     mValue = nullptr;
 504     mCallback = nullptr;
 505     return rv;
 506   }
 507
 508  private:
 509   nsresult mStatus;
 510   nsCOMPtr<nsISupports> mValue;
 511   // This is a RefPtr<T> and not a nsCOMPtr<T> because
 512   // nsCOMP<T> would cause an off-main thread QI, which
 513   // is not a good idea (and crashes XPConnect).
 514   RefPtr<mozIStorageCompletionCallback> mCallback;
 515 };
 516
 517 }  // namespace storage
 518 }  // namespace mozilla
 519
 520 /**
 521  * Casting Connection to nsISupports is ambiguous.
 522  * This method handles that.
 523  */
 524 inline nsISupports* ToSupports(mozilla::storage::Connection* p) {
 525   return NS_ISUPPORTS_CAST(mozIStorageAsyncConnection*, p);
 526 }
 527
 528 #endif  // mozilla_storage_Connection_h