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