storage/src/mozStorageAsyncStatementExecution.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  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is mozilla.org code.
  17  *
  18  * The Initial Developer of the Original Code is
  19  * Mozilla Corporation.
  20  * Portions created by the Initial Developer are Copyright (C) 2008
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *   Shawn Wilsher <me@shawnwilsher.com> (Original Author)
  25  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either the GNU General Public License Version 2 or later (the "GPL"), or
  28  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 #ifndef mozStorageAsyncStatementExecution_h
  41 #define mozStorageAsyncStatementExecution_h
  42
  43 #include "nscore.h"
  44 #include "nsTArray.h"
  45 #include "nsAutoPtr.h"
  46 #include "nsThreadUtils.h"
  47 #include "mozilla/Mutex.h"
  48 #include "mozilla/TimeStamp.h"
  49
  50 #include "SQLiteMutex.h"
  51 #include "mozIStoragePendingStatement.h"
  52 #include "mozIStorageStatementCallback.h"
  53
  54 struct sqlite3_stmt;
  55 class mozStorageTransaction;
  56
  57 namespace mozilla {
  58 namespace storage {
  59
  60 class Connection;
  61 class ResultSet;
  62 class StatementData;
  63
  64 class AsyncExecuteStatements : public nsIRunnable
  65                              , public mozIStoragePendingStatement
  66 {
  67 public:
  68   NS_DECL_ISUPPORTS
  69   NS_DECL_NSIRUNNABLE
  70   NS_DECL_MOZISTORAGEPENDINGSTATEMENT
  71
  72   /**
  73    * Describes the state of execution.
  74    */
  75   enum ExecutionState {
  76     PENDING = -1,
  77     COMPLETED = mozIStorageStatementCallback::REASON_FINISHED,
  78     CANCELED = mozIStorageStatementCallback::REASON_CANCELED,
  79     ERROR = mozIStorageStatementCallback::REASON_ERROR
  80   };
  81
  82   typedef nsTArray<StatementData> StatementDataArray;
  83
  84   /**
  85    * Executes a statement in the background, and passes results back to the
  86    * caller.
  87    *
  88    * @param aStatements
  89    *        The statements to execute and possibly bind in the background.
  90    *        Ownership is transfered from the caller.
  91    * @param aConnection
  92    *        The connection that created the statements to execute.
  93    * @param aCallback
  94    *        The callback that is notified of results, completion, and errors.
  95    * @param _stmt
  96    *        The handle to control the execution of the statements.
  97    */
  98   static nsresult execute(StatementDataArray &aStatements,
  99                           Connection *aConnection,
 100                           mozIStorageStatementCallback *aCallback,
 101                           mozIStoragePendingStatement **_stmt);
 102
 103   /**
 104    * Indicates when events on the calling thread should run or not.  Certain
 105    * events posted back to the calling thread should call this see if they
 106    * should run or not.
 107    *
 108    * @pre mMutex is not held
 109    *
 110    * @returns true if the event should notify still, false otherwise.
 111    */
 112   bool shouldNotify();
 113
 114 private:
 115   AsyncExecuteStatements(StatementDataArray &aStatements,
 116                          Connection *aConnection,
 117                          mozIStorageStatementCallback *aCallback);
 118
 119   /**
 120    * Binds and then executes a given statement until completion, an error
 121    * occurs, or we are canceled.  If aLastStatement is true, we should set
 122    * mState accordingly.
 123    *
 124    * @pre mMutex is not held
 125    *
 126    * @param aData
 127    *        The StatementData to bind, execute, and then process.
 128    * @param aLastStatement
 129    *        Indicates if this is the last statement or not.  If it is, we have
 130    *        to set the proper state.
 131    * @returns true if we should continue to process statements, false otherwise.
 132    */
 133   bool bindExecuteAndProcessStatement(StatementData &aData,
 134                                       bool aLastStatement);
 135
 136   /**
 137    * Executes a given statement until completion, an error occurs, or we are
 138    * canceled.  If aLastStatement is true, we should set mState accordingly.
 139    *
 140    * @pre mMutex is not held
 141    *
 142    * @param aStatement
 143    *        The statement to execute and then process.
 144    * @param aLastStatement
 145    *        Indicates if this is the last statement or not.  If it is, we have
 146    *        to set the proper state.
 147    * @returns true if we should continue to process statements, false otherwise.
 148    */
 149   bool executeAndProcessStatement(sqlite3_stmt *aStatement,
 150                                   bool aLastStatement);
 151
 152   /**
 153    * Executes a statement to completion, properly handling any error conditions.
 154    *
 155    * @pre mMutex is not held
 156    *
 157    * @param aStatement
 158    *        The statement to execute to completion.
 159    * @returns true if results were obtained, false otherwise.
 160    */
 161   bool executeStatement(sqlite3_stmt *aStatement);
 162
 163   /**
 164    * Builds a result set up with a row from a given statement.  If we meet the
 165    * right criteria, go ahead and notify about this results too.
 166    *
 167    * @pre mMutex is not held
 168    *
 169    * @param aStatement
 170    *        The statement to get the row data from.
 171    */
 172   nsresult buildAndNotifyResults(sqlite3_stmt *aStatement);
 173
 174   /**
 175    * Notifies callback about completion, and does any necessary cleanup.
 176    *
 177    * @pre mMutex is not held
 178    */
 179   nsresult notifyComplete();
 180
 181   /**
 182    * Notifies callback about an error.
 183    *
 184    * @pre mMutex is not held
 185    * @pre mDBMutex is not held
 186    *
 187    * @param aErrorCode
 188    *        The error code defined in mozIStorageError for the error.
 189    * @param aMessage
 190    *        The error string, if any.
 191    * @param aError
 192    *        The error object to notify the caller with.
 193    */
 194   nsresult notifyError(PRInt32 aErrorCode, const char *aMessage);
 195   nsresult notifyError(mozIStorageError *aError);
 196
 197   /**
 198    * Notifies the callback about a result set.
 199    *
 200    * @pre mMutex is not held
 201    */
 202   nsresult notifyResults();
 203
 204   StatementDataArray mStatements;
 205   nsRefPtr<Connection> mConnection;
 206   mozStorageTransaction *mTransactionManager;
 207   mozIStorageStatementCallback *mCallback;
 208   nsCOMPtr<nsIThread> mCallingThread;
 209   nsRefPtr<ResultSet> mResultSet;
 210
 211   /**
 212    * The maximum amount of time we want to wait between results.  Defined by
 213    * MAX_MILLISECONDS_BETWEEN_RESULTS and set at construction.
 214    */
 215   const TimeDuration mMaxWait;
 216
 217   /**
 218    * The start time since our last set of results.
 219    */
 220   TimeStamp mIntervalStart;
 221
 222   /**
 223    * Indicates our state of execution.
 224    */
 225   ExecutionState mState;
 226
 227   /**
 228    * Indicates if we should try to cancel at a cancelation point.
 229    */
 230   bool mCancelRequested;
 231
 232   /**
 233    * This is the mutex that protects our state from changing between threads.
 234    * This includes the following variables:
 235    *   - mCancelRequested is only set on the calling thread while the lock is
 236    *     held.  It is always read from within the lock on the background thread,
 237    *     but not on the calling thread (see shouldNotify for why).
 238    */
 239   Mutex &mMutex;
 240
 241   /**
 242    * The wrapped SQLite recursive connection mutex.  We use it whenever we call
 243    * sqlite3_step and care about having reliable error messages.  By taking it
 244    * prior to the call and holding it until the point where we no longer care
 245    * about the error message, the user gets reliable error messages.
 246    */
 247   SQLiteMutex &mDBMutex;
 248 };
 249
 250 } // namespace storage
 251 } // namespace mozilla
 252
 253 #endif // mozStorageAsyncStatementExecution_h