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