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