storage/mozStorageConnection.h
author Chris H-C <chutten@mozilla.com>
Mon, 04 Jul 2016 11:16:05 -0400
changeset 312997 df28918fe2361f0b54ca9ce4773a29c4c0675d06
parent 308876 b09d90288666fb3afb11877fc45527b904ef23db
child 314149 ef7939c0332eb73be104210509dd45488f03dc3e
permissions -rw-r--r--
bug 1218576 - Support remote accumulation via JS histograms. r=gfritzsche The JS histograms, too, need to dispatch their accumulations from child to parent. JSHistograms_Add now only supports histograms that are in gHistogramsMap or that were created in the parent process. After bug 1288745, maybe we'll be able to change this to be less convoluted. MozReview-Commit-ID: 3qTH89YKbGP

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 * vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ :
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef mozilla_storage_Connection_h
#define mozilla_storage_Connection_h

#include "nsAutoPtr.h"
#include "nsCOMPtr.h"
#include "mozilla/Mutex.h"
#include "nsProxyRelease.h"
#include "nsThreadUtils.h"
#include "nsIInterfaceRequestor.h"

#include "nsDataHashtable.h"
#include "mozIStorageProgressHandler.h"
#include "SQLiteMutex.h"
#include "mozIStorageConnection.h"
#include "mozStorageService.h"
#include "mozIStorageAsyncConnection.h"
#include "mozIStorageCompletionCallback.h"

#include "nsIMutableArray.h"
#include "mozilla/Attributes.h"

#include "sqlite3.h"

class nsIFile;
class nsIFileURL;
class nsIEventTarget;
class nsIThread;

namespace mozilla {
namespace storage {

class Connection final : public mozIStorageConnection
                       , public nsIInterfaceRequestor
{
public:
  NS_DECL_THREADSAFE_ISUPPORTS
  NS_DECL_MOZISTORAGEASYNCCONNECTION
  NS_DECL_MOZISTORAGECONNECTION
  NS_DECL_NSIINTERFACEREQUESTOR

  /**
   * Structure used to describe user functions on the database connection.
   */
  struct FunctionInfo {
    enum FunctionType {
      SIMPLE,
      AGGREGATE
    };

    nsCOMPtr<nsISupports> function;
    FunctionType type;
    int32_t numArgs;
  };

  /**
   * @param aService
   *        Pointer to the storage service.  Held onto for the lifetime of the
   *        connection.
   * @param aFlags
   *        The flags to pass to sqlite3_open_v2.
   * @param aAsyncOnly
   *        If |true|, the Connection only implements asynchronous interface:
   *        - |mozIStorageAsyncConnection|;
   *        If |false|, the result also implements synchronous interface:
   *        - |mozIStorageConnection|.
   */
  Connection(Service *aService, int aFlags, bool aAsyncOnly);

  /**
   * Creates the connection to an in-memory database.
   */
  nsresult initialize();

  /**
   * Creates the connection to the database.
   *
   * @param aDatabaseFile
   *        The nsIFile of the location of the database to open, or create if it
   *        does not exist.
   */
  nsresult initialize(nsIFile *aDatabaseFile);

  /**
   * Creates the connection to the database.
   *
   * @param aFileURL
   *        The nsIFileURL of the location of the database to open, or create if it
   *        does not exist.
   */
  nsresult initialize(nsIFileURL *aFileURL);

  /**
   * Fetches runtime status information for this connection.
   *
   * @param aStatusOption One of the SQLITE_DBSTATUS options defined at
   *        http://www.sqlite.org/c3ref/c_dbstatus_options.html
   * @param [optional] aMaxValue if provided, will be set to the highest
   *        istantaneous value.
   * @return the current value for the specified option.
   */
  int32_t getSqliteRuntimeStatus(int32_t aStatusOption,
                                 int32_t* aMaxValue=nullptr);
  /**
   * Registers/unregisters a commit hook callback.
   *
   * @param aCallbackFn a callback function to be invoked on transactions
   *        commit.  Pass nullptr to unregister the current callback.
   * @param [optional] aData if provided, will be passed to the callback.
   * @see http://sqlite.org/c3ref/commit_hook.html
   */
  void setCommitHook(int (*aCallbackFn)(void *) , void *aData=nullptr) {
    MOZ_ASSERT(mDBConn, "A connection must exist at this point");
    ::sqlite3_commit_hook(mDBConn, aCallbackFn, aData);
  };

  /**
   * Gets autocommit status.
   */
  bool getAutocommit() {
    return mDBConn && static_cast<bool>(::sqlite3_get_autocommit(mDBConn));
  };

  /**
   * Lazily creates and returns a background execution thread.  In the future,
   * the thread may be re-claimed if left idle, so you should call this
   * method just before you dispatch and not save the reference.
   *
   * @returns an event target suitable for asynchronous statement execution.
   */
  nsIEventTarget *getAsyncExecutionTarget();

  /**
   * Mutex used by asynchronous statements to protect state.  The mutex is
   * declared on the connection object because there is no contention between
   * asynchronous statements (they are serialized on mAsyncExecutionThread).
   * Currently protects:
   *  - Connection.mAsyncExecutionThreadShuttingDown
   *  - Connection.mAsyncExecutionThread
   *  - Connection.mConnectionClosed
   *  - AsyncExecuteStatements.mCancelRequested
   */
  Mutex sharedAsyncExecutionMutex;

  /**
   * Wraps the mutex that SQLite gives us from sqlite3_db_mutex.  This is public
   * because we already expose the sqlite3* native connection and proper
   * operation of the deadlock detector requires everyone to use the same single
   * SQLiteMutex instance for correctness.
   */
  SQLiteMutex sharedDBMutex;

  /**
   * References the thread this database was opened on.  This MUST be thread it is
   * closed on.
   */
  const nsCOMPtr<nsIThread> threadOpenedOn;

  /**
   * Closes the SQLite database, and warns about any non-finalized statements.
   */
  nsresult internalClose(sqlite3 *aDBConn);

  /**
   * Shuts down the passed-in async thread.
   */
  void shutdownAsyncThread(nsIThread *aAsyncThread);

  /**
   * Obtains the filename of the connection.  Useful for logging.
   */
  nsCString getFilename();

  /**
   * Creates an sqlite3 prepared statement object from an SQL string.
   *
   * @param aNativeConnection
   *        The underlying Sqlite connection to prepare the statement with.
   * @param aSQL
   *        The SQL statement string to compile.
   * @param _stmt
   *        New sqlite3_stmt object.
   * @return the result from sqlite3_prepare_v2.
   */
  int prepareStatement(sqlite3* aNativeConnection,
                       const nsCString &aSQL, sqlite3_stmt **_stmt);

  /**
   * Performs a sqlite3_step on aStatement, while properly handling SQLITE_LOCKED
   * when not on the main thread by waiting until we are notified.
   *
   * @param aNativeConnection
   *        The underlying Sqlite connection to step the statement with.
   * @param aStatement
   *        A pointer to a sqlite3_stmt object.
   * @return the result from sqlite3_step.
   */
  int stepStatement(sqlite3* aNativeConnection, sqlite3_stmt* aStatement);

  /**
   * Raw connection transaction management.
   *
   * @see BeginTransactionAs, CommitTransaction, RollbackTransaction.
   */
  nsresult beginTransactionInternal(sqlite3 *aNativeConnection,
                                    int32_t aTransactionType=TRANSACTION_DEFERRED);
  nsresult commitTransactionInternal(sqlite3 *aNativeConnection);
  nsresult rollbackTransactionInternal(sqlite3 *aNativeConnection);

  bool connectionReady();

  /**
   * True if this connection is shutting down but not yet closed.
   */
  bool isClosing();

  /**
   * True if the underlying connection is closed.
   * Any sqlite resources may be lost when this returns true, so nothing should
   * try to use them.
   */
  bool isClosed();

  nsresult initializeClone(Connection *aClone, bool aReadOnly);

private:
  ~Connection();
  nsresult initializeInternal();

  /**
   * Sets the database into a closed state so no further actions can be
   * performed.
   *
   * @note mDBConn is set to nullptr in this method.
   */
  nsresult setClosedState();

  /**
   * Helper for calls to sqlite3_exec. Reports long delays to Telemetry.
   *
   * @param aNativeConnection
   *        The underlying Sqlite connection to execute the query with.
   * @param aSqlString
   *        SQL string to execute
   * @return the result from sqlite3_exec.
   */
  int executeSql(sqlite3 *aNativeConnection, const char *aSqlString);

  /**
   * Describes a certain primitive type in the database.
   *
   * Possible Values Are:
   *  INDEX - To check for the existence of an index
   *  TABLE - To check for the existence of a table
   */
  enum DatabaseElementType {
    INDEX,
    TABLE
  };

  /**
   * Determines if the specified primitive exists.
   *
   * @param aElementType
   *        The type of element to check the existence of
   * @param aElementName
   *        The name of the element to check for
   * @returns true if element exists, false otherwise
   */
  nsresult databaseElementExists(enum DatabaseElementType aElementType,
                                 const nsACString& aElementName,
                                 bool *_exists);

  bool findFunctionByInstance(nsISupports *aInstance);

  static int sProgressHelper(void *aArg);
  // Generic progress handler
  // Dispatch call to registered progress handler,
  // if there is one. Do nothing in other cases.
  int progressHandler();

  sqlite3 *mDBConn;
  nsCOMPtr<nsIFileURL> mFileURL;
  nsCOMPtr<nsIFile> mDatabaseFile;

  /**
   * The filename that will be reported to telemetry for this connection. By
   * default this will be the leaf of the path to the database file.
  */
  nsCString mTelemetryFilename;

  /**
   * Lazily created thread for asynchronous statement execution.  Consumers
   * should use getAsyncExecutionTarget rather than directly accessing this
   * field.
   */
  nsCOMPtr<nsIThread> mAsyncExecutionThread;

  /**
   * Set to true by Close() or AsyncClose() prior to shutdown.
   *
   * If false, we guarantee both that the underlying sqlite3 database
   * connection is still open and that getAsyncExecutionTarget() can
   * return a thread. Once true, either the sqlite3 database
   * connection is being shutdown or it has been
   * shutdown. Additionally, once true, getAsyncExecutionTarget()
   * returns null.
   *
   * This variable should be accessed while holding the
   * sharedAsyncExecutionMutex.
   */
  bool mAsyncExecutionThreadShuttingDown;

  /**
   * Tracks whether the async thread has been initialized and Shutdown() has
   * not yet been invoked on it.
   */
#ifdef DEBUG
  bool mAsyncExecutionThreadIsAlive;
#endif

  /**
   * Set to true just prior to calling sqlite3_close on the
   * connection.
   *
   * This variable should be accessed while holding the
   * sharedAsyncExecutionMutex.
   */
  bool mConnectionClosed;

  /**
   * Tracks if we have a transaction in progress or not.  Access protected by
   * sharedDBMutex.
   */
  bool mTransactionInProgress;

  /**
   * Stores the mapping of a given function by name to its instance.  Access is
   * protected by sharedDBMutex.
   */
  nsDataHashtable<nsCStringHashKey, FunctionInfo> mFunctions;

  /**
   * Stores the registered progress handler for the database connection.  Access
   * is protected by sharedDBMutex.
   */
  nsCOMPtr<mozIStorageProgressHandler> mProgressHandler;

  /**
   * Stores the flags we passed to sqlite3_open_v2.
   */
  const int mFlags;

  // This is here for two reasons: 1) It's used to make sure that the
  // connections do not outlive the service.  2) Our custom collating functions
  // call its localeCompareStrings() method.
  RefPtr<Service> mStorageService;

  /**
   * If |false|, this instance supports synchronous operations
   * and it can be cast to |mozIStorageConnection|.
   */
  const bool mAsyncOnly;
};


/**
 * A Runnable designed to call a mozIStorageCompletionCallback on
 * the appropriate thread.
 */
class CallbackComplete final : public Runnable
{
public:
  /**
   * @param aValue The result to pass to the callback. It must
   *               already be owned by the main thread.
   * @param aCallback The callback. It must already be owned by the
   *                  main thread.
   */
  CallbackComplete(nsresult aStatus,
                   nsISupports* aValue,
                   already_AddRefed<mozIStorageCompletionCallback> aCallback)
    : mStatus(aStatus)
    , mValue(aValue)
    , mCallback(aCallback)
  {
  }

  NS_IMETHOD Run() override {
    MOZ_ASSERT(NS_IsMainThread());
    nsresult rv = mCallback->Complete(mStatus, mValue);

    // Ensure that we release on the main thread
    mValue = nullptr;
    mCallback = nullptr;
    return rv;
  }

private:
  nsresult mStatus;
  nsCOMPtr<nsISupports> mValue;
  // This is a RefPtr<T> and not a nsCOMPtr<T> because
  // nsCOMP<T> would cause an off-main thread QI, which
  // is not a good idea (and crashes XPConnect).
  RefPtr<mozIStorageCompletionCallback> mCallback;
};

} // namespace storage
} // namespace mozilla

/**
 * Casting Connection to nsISupports is ambiguous.
 * This method handles that.
 */
inline nsISupports*
ToSupports(mozilla::storage::Connection* p)
{
  return NS_ISUPPORTS_CAST(mozIStorageAsyncConnection*, p);
}

#endif // mozilla_storage_Connection_h