LCOV - app.info - storage/src/mozStorageAsyncStatementExecution.h

LCOV - code coverage report
| Current view: | directory - storage/src - mozStorageAsyncStatementExecution.h (source / functions) |  | Found | Hit | Coverage |
| Test: | app.info | Lines: | 1 | 1 | 100.0 %
| Date: | 2012-06-02 | Functions: | 1 | 1 | 100.0 %

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

Generated by: LCOV version 1.7