/* -*- 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 mozStorageAsyncStatementExecution_h #define mozStorageAsyncStatementExecution_h #include "nscore.h" #include "nsTArray.h" #include "nsAutoPtr.h" #include "mozilla/Mutex.h" #include "mozilla/TimeStamp.h" #include "mozilla/Attributes.h" #include "nsIRunnable.h" #include "SQLiteMutex.h" #include "mozIStoragePendingStatement.h" #include "mozIStorageStatementCallback.h" #include "mozStorageHelper.h" struct sqlite3_stmt; namespace mozilla { namespace storage { class Connection; class ResultSet; class StatementData; class AsyncExecuteStatements final : public nsIRunnable , public mozIStoragePendingStatement { public: NS_DECL_THREADSAFE_ISUPPORTS NS_DECL_NSIRUNNABLE NS_DECL_MOZISTORAGEPENDINGSTATEMENT /** * Describes the state of execution. */ enum ExecutionState { PENDING = -1, COMPLETED = mozIStorageStatementCallback::REASON_FINISHED, CANCELED = mozIStorageStatementCallback::REASON_CANCELED, ERROR = mozIStorageStatementCallback::REASON_ERROR }; typedef nsTArray<StatementData> StatementDataArray; /** * Executes a statement in the background, and passes results back to the * caller. * * @param aStatements * The statements to execute and possibly bind in the background. * Ownership is transfered from the caller. * @param aConnection * The connection that created the statements to execute. * @param aNativeConnection * The native Sqlite connection that created the statements to execute. * @param aCallback * The callback that is notified of results, completion, and errors. * @param _stmt * The handle to control the execution of the statements. */ static nsresult execute(StatementDataArray &aStatements, Connection *aConnection, sqlite3 *aNativeConnection, mozIStorageStatementCallback *aCallback, mozIStoragePendingStatement **_stmt); /** * Indicates when events on the calling thread should run or not. Certain * events posted back to the calling thread should call this see if they * should run or not. * * @pre mMutex is not held * * @returns true if the event should notify still, false otherwise. */ bool shouldNotify(); /** * Used by notifyComplete(), notifyError() and notifyResults() to notify on * the calling thread. */ nsresult notifyCompleteOnCallingThread(); nsresult notifyErrorOnCallingThread(mozIStorageError *aError); nsresult notifyResultsOnCallingThread(ResultSet *aResultSet); private: AsyncExecuteStatements(StatementDataArray &aStatements, Connection *aConnection, sqlite3 *aNativeConnection, mozIStorageStatementCallback *aCallback); ~AsyncExecuteStatements(); /** * Binds and then executes a given statement until completion, an error * occurs, or we are canceled. If aLastStatement is true, we should set * mState accordingly. * * @pre mMutex is not held * * @param aData * The StatementData to bind, execute, and then process. * @param aLastStatement * Indicates if this is the last statement or not. If it is, we have * to set the proper state. * @returns true if we should continue to process statements, false otherwise. */ bool bindExecuteAndProcessStatement(StatementData &aData, bool aLastStatement); /** * Executes a given statement until completion, an error occurs, or we are * canceled. If aLastStatement is true, we should set mState accordingly. * * @pre mMutex is not held * * @param aStatement * The statement to execute and then process. * @param aLastStatement * Indicates if this is the last statement or not. If it is, we have * to set the proper state. * @returns true if we should continue to process statements, false otherwise. */ bool executeAndProcessStatement(sqlite3_stmt *aStatement, bool aLastStatement); /** * Executes a statement to completion, properly handling any error conditions. * * @pre mMutex is not held * * @param aStatement * The statement to execute to completion. * @returns true if results were obtained, false otherwise. */ bool executeStatement(sqlite3_stmt *aStatement); /** * Builds a result set up with a row from a given statement. If we meet the * right criteria, go ahead and notify about this results too. * * @pre mMutex is not held * * @param aStatement * The statement to get the row data from. */ nsresult buildAndNotifyResults(sqlite3_stmt *aStatement); /** * Notifies callback about completion, and does any necessary cleanup. * * @pre mMutex is not held */ nsresult notifyComplete(); /** * Notifies callback about an error. * * @pre mMutex is not held * @pre mDBMutex is not held * * @param aErrorCode * The error code defined in mozIStorageError for the error. * @param aMessage * The error string, if any. * @param aError * The error object to notify the caller with. */ nsresult notifyError(int32_t aErrorCode, const char *aMessage); nsresult notifyError(mozIStorageError *aError); /** * Notifies the callback about a result set. * * @pre mMutex is not held */ nsresult notifyResults(); /** * Tests whether the current statements should be wrapped in an explicit * transaction. * * @return true if an explicit transaction is needed, false otherwise. */ bool statementsNeedTransaction(); StatementDataArray mStatements; RefPtr<Connection> mConnection; sqlite3 *mNativeConnection; bool mHasTransaction; // Note, this may not be a threadsafe object - never addref/release off // the calling thread. We take a reference when this is created, and // release it in the CompletionNotifier::Run() call back to this thread. nsCOMPtr<mozIStorageStatementCallback> mCallback; nsCOMPtr<nsIThread> mCallingThread; RefPtr<ResultSet> mResultSet; /** * The maximum amount of time we want to wait between results. Defined by * MAX_MILLISECONDS_BETWEEN_RESULTS and set at construction. */ const TimeDuration mMaxWait; /** * The start time since our last set of results. */ TimeStamp mIntervalStart; /** * Indicates our state of execution. */ ExecutionState mState; /** * Indicates if we should try to cancel at a cancelation point. */ bool mCancelRequested; /** * This is the mutex that protects our state from changing between threads. * This includes the following variables: * - mCancelRequested is only set on the calling thread while the lock is * held. It is always read from within the lock on the background thread, * but not on the calling thread (see shouldNotify for why). */ Mutex &mMutex; /** * The wrapped SQLite recursive connection mutex. We use it whenever we call * sqlite3_step and care about having reliable error messages. By taking it * prior to the call and holding it until the point where we no longer care * about the error message, the user gets reliable error messages. */ SQLiteMutex &mDBMutex; /** * The instant at which the request was started. * * Used by telemetry. */ TimeStamp mRequestStartDate; }; } // namespace storage } // namespace mozilla #endif // mozStorageAsyncStatementExecution_h