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