storage/mozStorageHelper.h
author Emilio Cobos Álvarez <emilio@crisal.io>
Tue, 20 Jun 2017 23:21:27 +0200
changeset 414257 fdde73cf429c62cd1e712afcc196110f8601cb2a
parent 413775 73edd4e1acef4e708346600b81a337022e450475
child 422619 46153627ee5fa17c8cc67a76a9a468b36cfd1b52
permissions -rw-r--r--
Bug 1374752: Pack together the StyleSet, ChangeList and handled change hints, and use the latter with anonymous boxes while we're at it. r=heycam MozReview-Commit-ID: DiWcUwD9po5

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* 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 MOZSTORAGEHELPER_H
#define MOZSTORAGEHELPER_H

#include "nsAutoPtr.h"
#include "nsStringGlue.h"
#include "mozilla/DebugOnly.h"
#include "nsIConsoleService.h"
#include "nsIScriptError.h"

#include "mozIStorageAsyncConnection.h"
#include "mozIStorageConnection.h"
#include "mozIStorageStatement.h"
#include "mozIStoragePendingStatement.h"
#include "nsError.h"
#include "nsIXPConnect.h"

/**
 * This class wraps a transaction inside a given C++ scope, guaranteeing that
 * the transaction will be completed even if you have an exception or
 * return early.
 *
 * A common use is to create an instance with aCommitOnComplete = false (rollback),
 * then call Commit() on this object manually when your function completes
 * successfully.
 *
 * @note nested transactions are not supported by Sqlite, so if a transaction
 * is already in progress, this object does nothing.  Note that in this case,
 * you may not get the transaction type you asked for, and you won't be able
 * to rollback.
 *
 * @param aConnection
 *        The connection to create the transaction on.
 * @param aCommitOnComplete
 *        Controls whether the transaction is committed or rolled back when
 *        this object goes out of scope.
 * @param aType [optional]
 *        The transaction type, as defined in mozIStorageConnection.  Defaults
 *        to TRANSACTION_DEFERRED.
 * @param aAsyncCommit [optional]
 *        Whether commit should be executed asynchronously on the helper thread.
 *        This is a special option introduced as an interim solution to reduce
 *        main-thread fsyncs in Places.  Can only be used on main-thread.
 *
 *        WARNING: YOU SHOULD _NOT_ WRITE NEW MAIN-THREAD CODE USING THIS!
 *
 *        Notice that async commit might cause synchronous statements to fail
 *        with SQLITE_BUSY.  A possible mitigation strategy is to use
 *        PRAGMA busy_timeout, but notice that might cause main-thread jank.
 *        Finally, if the database is using WAL journaling mode, other
 *        connections won't see the changes done in async committed transactions
 *        until commit is complete.
 *
 *        For all of the above reasons, this should only be used as an interim
 *        solution and avoided completely if possible.
 */
class mozStorageTransaction
{
public:
  mozStorageTransaction(mozIStorageConnection* aConnection,
                        bool aCommitOnComplete,
                        int32_t aType = mozIStorageConnection::TRANSACTION_DEFERRED,
                        bool aAsyncCommit = false)
    : mConnection(aConnection),
      mHasTransaction(false),
      mCommitOnComplete(aCommitOnComplete),
      mCompleted(false),
      mAsyncCommit(aAsyncCommit)
  {
    if (mConnection) {
      nsAutoCString query("BEGIN");
      switch(aType) {
        case mozIStorageConnection::TRANSACTION_IMMEDIATE:
          query.AppendLiteral(" IMMEDIATE");
          break;
        case mozIStorageConnection::TRANSACTION_EXCLUSIVE:
          query.AppendLiteral(" EXCLUSIVE");
          break;
        case mozIStorageConnection::TRANSACTION_DEFERRED:
          query.AppendLiteral(" DEFERRED");
          break;
        default:
          MOZ_ASSERT(false, "Unknown transaction type");
      }
      // If a transaction is already in progress, this will fail, since Sqlite
      // doesn't support nested transactions.
      mHasTransaction = NS_SUCCEEDED(mConnection->ExecuteSimpleSQL(query));
    }
  }

  ~mozStorageTransaction()
  {
    if (mConnection && mHasTransaction && !mCompleted) {
      if (mCommitOnComplete) {
        mozilla::DebugOnly<nsresult> rv = Commit();
        NS_WARNING_ASSERTION(NS_SUCCEEDED(rv),
                             "A transaction didn't commit correctly");
      }
      else {
        mozilla::DebugOnly<nsresult> rv = Rollback();
        NS_WARNING_ASSERTION(NS_SUCCEEDED(rv),
                             "A transaction didn't rollback correctly");
      }
    }
  }

  /**
   * Commits the transaction if one is in progress. If one is not in progress,
   * this is a NOP since the actual owner of the transaction outside of our
   * scope is in charge of finally committing or rolling back the transaction.
   */
  nsresult Commit()
  {
    if (!mConnection || mCompleted || !mHasTransaction)
      return NS_OK;
    mCompleted = true;

    // TODO (bug 559659): this might fail with SQLITE_BUSY, but we don't handle
    // it, thus the transaction might stay open until the next COMMIT.
    nsresult rv;
    if (mAsyncCommit) {
      nsCOMPtr<mozIStoragePendingStatement> ps;
      rv = mConnection->ExecuteSimpleSQLAsync(NS_LITERAL_CSTRING("COMMIT"),
                                              nullptr, getter_AddRefs(ps));
    }
    else {
      rv = mConnection->ExecuteSimpleSQL(NS_LITERAL_CSTRING("COMMIT"));
    }

    if (NS_SUCCEEDED(rv))
      mHasTransaction = false;

    return rv;
  }

  /**
   * Rolls back the transaction if one is in progress. If one is not in progress,
   * this is a NOP since the actual owner of the transaction outside of our
   * scope is in charge of finally rolling back the transaction.
   */
  nsresult Rollback()
  {
    if (!mConnection || mCompleted || !mHasTransaction)
      return NS_OK;
    mCompleted = true;

    // TODO (bug 1062823): from Sqlite 3.7.11 on, rollback won't ever return
    // a busy error, so this handling can be removed.
    nsresult rv = NS_OK;
    do {
      rv = mConnection->ExecuteSimpleSQL(NS_LITERAL_CSTRING("ROLLBACK"));
      if (rv == NS_ERROR_STORAGE_BUSY)
        (void)PR_Sleep(PR_INTERVAL_NO_WAIT);
    } while (rv == NS_ERROR_STORAGE_BUSY);

    if (NS_SUCCEEDED(rv))
      mHasTransaction = false;

    return rv;
  }

protected:
  nsCOMPtr<mozIStorageConnection> mConnection;
  bool mHasTransaction;
  bool mCommitOnComplete;
  bool mCompleted;
  bool mAsyncCommit;
};

/**
 * This class wraps a statement so that it is guaraneed to be reset when
 * this object goes out of scope.
 *
 * Note that this always just resets the statement. If the statement doesn't
 * need resetting, the reset operation is inexpensive.
 */
class MOZ_STACK_CLASS mozStorageStatementScoper
{
public:
  explicit mozStorageStatementScoper(mozIStorageStatement* aStatement)
      : mStatement(aStatement)
  {
  }
  ~mozStorageStatementScoper()
  {
    if (mStatement)
      mStatement->Reset();
  }

  /**
   * Call this to make the statement not reset. You might do this if you know
   * that the statement has been reset.
   */
  void Abandon()
  {
    mStatement = nullptr;
  }

protected:
  nsCOMPtr<mozIStorageStatement> mStatement;
};

// Use this to make queries uniquely identifiable in telemetry
// statistics, especially PRAGMAs.  We don't include __LINE__ so that
// queries are stable in the face of source code changes.
#define MOZ_STORAGE_UNIQUIFY_QUERY_STR "/* " __FILE__ " */ "

// Use this to show a console warning when using deprecated methods.
#define WARN_DEPRECATED()                                                          \
  PR_BEGIN_MACRO                                                                   \
                                                                                   \
  if (NS_IsMainThread()) {                                                         \
    nsCOMPtr<nsIConsoleService> cs = do_GetService(NS_CONSOLESERVICE_CONTRACTID);  \
                                                                                   \
    if (cs) {                                                                      \
      nsCString msg(__FUNCTION__);                                                 \
      msg.AppendLiteral(" is deprecated and will be removed soon.");               \
                                                                                   \
      nsCOMPtr<nsIScriptError> e = do_CreateInstance(NS_SCRIPTERROR_CONTRACTID);   \
      if (e && NS_SUCCEEDED(e->Init(NS_ConvertUTF8toUTF16(msg), EmptyString(),     \
                                    EmptyString(), 0, 0,                           \
                                    nsIScriptError::errorFlag, "Storage"))) {      \
        cs->LogMessage(e);                                                         \
      }                                                                            \
    }                                                                              \
  }                                                                                \
  if (NS_IsMainThread()) {                                                         \
    nsCOMPtr<nsIXPConnect> xpc = do_GetService(nsIXPConnect::GetCID());            \
    if (xpc) {                                                                     \
      mozilla::Unused << xpc->DebugDumpJSStack(false, false, false);               \
    }                                                                              \
  }                                                                                \
  MOZ_ASSERT(false, "You are trying to use a deprecated mozStorage method. "       \
                    "Check error message in console to identify the method name.");\
  PR_END_MACRO

#endif /* MOZSTORAGEHELPER_H */