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