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