storage/mozStorageService.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  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef MOZSTORAGESERVICE_H
   8 #define MOZSTORAGESERVICE_H
   9
  10 #include "nsCOMPtr.h"
  11 #include "nsICollation.h"
  12 #include "nsIFile.h"
  13 #include "nsIMemoryReporter.h"
  14 #include "nsIObserver.h"
  15 #include "nsTArray.h"
  16 #include "mozilla/Mutex.h"
  17
  18 #include "mozIStorageService.h"
  19
  20 class nsIMemoryReporter;
  21 struct sqlite3_vfs;
  22
  23 namespace mozilla {
  24 namespace storage {
  25
  26 class Connection;
  27 class Service : public mozIStorageService
  28               , public nsIObserver
  29               , public nsIMemoryReporter
  30 {
  31 public:
  32   /**
  33    * Initializes the service.  This must be called before any other function!
  34    */
  35   nsresult initialize();
  36
  37   /**
  38    * Compares two strings using the Service's locale-aware collation.
  39    *
  40    * @param  aStr1
  41    *         The string to be compared against aStr2.
  42    * @param  aStr2
  43    *         The string to be compared against aStr1.
  44    * @param  aComparisonStrength
  45    *         The sorting strength, one of the nsICollation constants.
  46    * @return aStr1 - aStr2.  That is, if aStr1 < aStr2, returns a negative
  47    *         number.  If aStr1 > aStr2, returns a positive number.  If
  48    *         aStr1 == aStr2, returns 0.
  49    */
  50   int localeCompareStrings(const nsAString &aStr1,
  51                            const nsAString &aStr2,
  52                            int32_t aComparisonStrength);
  53
  54   static already_AddRefed<Service> getSingleton();
  55
  56   NS_DECL_THREADSAFE_ISUPPORTS
  57   NS_DECL_MOZISTORAGESERVICE
  58   NS_DECL_NSIOBSERVER
  59   NS_DECL_NSIMEMORYREPORTER
  60
  61   /**
  62    * Obtains the cached data for the toolkit.storage.synchronous preference.
  63    */
  64   static int32_t getSynchronousPref();
  65
  66   /**
  67    * Obtains the default page size for this platform. The default value is
  68    * specified in the SQLite makefile (SQLITE_DEFAULT_PAGE_SIZE) but it may be
  69    * overriden with the PREF_TS_PAGESIZE hidden preference.
  70    */
  71   static int32_t getDefaultPageSize()
  72   {
  73     return sDefaultPageSize;
  74   }
  75
  76   /**
  77    * Returns a boolean value indicating whether or not the given page size is
  78    * valid (currently understood as a power of 2 between 512 and 65536).
  79    */
  80   static bool pageSizeIsValid(int32_t aPageSize)
  81   {
  82     return aPageSize == 512 || aPageSize == 1024 || aPageSize == 2048 ||
  83            aPageSize == 4096 || aPageSize == 8192 || aPageSize == 16384 ||
  84            aPageSize == 32768 || aPageSize == 65536;
  85   }
  86
  87   /**
  88    * Registers the connection with the storage service.  Connections are
  89    * registered so they can be iterated over.
  90    *
  91    * @pre mRegistrationMutex is not held
  92    *
  93    * @param  aConnection
  94    *         The connection to register.
  95    */
  96   void registerConnection(Connection *aConnection);
  97
  98   /**
  99    * Unregisters the connection with the storage service.
 100    *
 101    * @pre mRegistrationMutex is not held
 102    *
 103    * @param  aConnection
 104    *         The connection to unregister.
 105    */
 106   void unregisterConnection(Connection *aConnection);
 107
 108   /**
 109    * Gets the list of open connections.  Note that you must test each
 110    * connection with mozIStorageConnection::connectionReady before doing
 111    * anything with it, and skip it if it's not ready.
 112    *
 113    * @pre mRegistrationMutex is not held
 114    *
 115    * @param  aConnections
 116    *         An inout param;  it is cleared and the connections are appended to
 117    *         it.
 118    * @return The open connections.
 119    */
 120   void getConnections(nsTArray<RefPtr<Connection> >& aConnections);
 121
 122 private:
 123   Service();
 124   virtual ~Service();
 125
 126   /**
 127    * Used for 1) locking around calls when initializing connections so that we
 128    * can ensure that the state of sqlite3_enable_shared_cache is sane and 2)
 129    * synchronizing access to mLocaleCollation.
 130    */
 131   Mutex mMutex;
 132
 133   sqlite3_vfs *mSqliteVFS;
 134
 135   /**
 136    * Protects mConnections.
 137    */
 138   Mutex mRegistrationMutex;
 139
 140   /**
 141    * The list of connections we have created.  Modifications to it are
 142    * protected by |mRegistrationMutex|.
 143    */
 144   nsTArray<RefPtr<Connection> > mConnections;
 145
 146   /**
 147    * Frees as much heap memory as possible from all of the known open
 148    * connections.
 149    */
 150   void minimizeMemory();
 151
 152   /**
 153    * Lazily creates and returns a collation created from the application's
 154    * locale that all statements of all Connections of this Service may use.
 155    * Since the collation's lifetime is that of the Service and no statement may
 156    * execute outside the lifetime of the Service, this method returns a raw
 157    * pointer.
 158    */
 159   nsICollation *getLocaleCollation();
 160
 161   /**
 162    * Lazily created collation that all statements of all Connections of this
 163    * Service may use.  The collation is created from the application's locale.
 164    *
 165    * @note Collation implementations are platform-dependent and in general not
 166    *       thread-safe.  Access to this collation should be synchronized.
 167    */
 168   nsCOMPtr<nsICollation> mLocaleCollation;
 169
 170   nsCOMPtr<nsIFile> mProfileStorageFile;
 171
 172   nsCOMPtr<nsIMemoryReporter> mStorageSQLiteReporter;
 173
 174   static Service *gService;
 175
 176   static int32_t sSynchronousPref;
 177   static int32_t sDefaultPageSize;
 178 };
 179
 180 } // namespace storage
 181 } // namespace mozilla
 182
 183 #endif /* MOZSTORAGESERVICE_H */