startupcache/StartupCache.h

   1 /* -*-  Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2; -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is Startup Cache.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * The Mozilla Foundation <http://www.mozilla.org/>.
  19  * Portions created by the Initial Developer are Copyright (C) 2009
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *  Benedict Hsieh <bhsieh@mozilla.com>
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either the GNU General Public License Version 2 or later (the "GPL"), or
  27  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28  * in which case the provisions of the GPL or the LGPL are applicable instead
  29  * of those above. If you wish to allow use of your version of this file only
  30  * under the terms of either the GPL or the LGPL, and not to allow others to
  31  * use your version of this file under the terms of the MPL, indicate your
  32  * decision by deleting the provisions above and replace them with the notice
  33  * and other provisions required by the GPL or the LGPL. If you do not delete
  34  * the provisions above, a recipient may use your version of this file under
  35  * the terms of any one of the MPL, the GPL or the LGPL.
  36  *
  37  * ***** END LICENSE BLOCK ***** */
  38
  39 #ifndef StartupCache_h_
  40 #define StartupCache_h_
  41
  42 #include "prio.h"
  43 #include "prtypes.h"
  44
  45 #include "nsClassHashtable.h"
  46 #include "nsIZipWriter.h"
  47 #include "nsIZipReader.h"
  48 #include "nsComponentManagerUtils.h"
  49 #include "nsZipArchive.h"
  50 #include "nsIStartupCache.h"
  51 #include "nsIStorageStream.h"
  52 #include "nsITimer.h"
  53 #include "nsIObserverService.h"
  54 #include "nsIObserver.h"
  55 #include "nsIOutputStream.h"
  56 #include "nsIFile.h"
  57
  58 /**
  59  * The StartupCache is a persistent cache of simple key-value pairs,
  60  * where the keys are null-terminated c-strings and the values are
  61  * arbitrary data, passed as a (char*, size) tuple.
  62  *
  63  * Clients should use the GetSingleton() static method to access the cache. It
  64  * will be available from the end of XPCOM init (NS_InitXPCOM3 in nsXPComInit.cpp),
  65  * until XPCOM shutdown begins. The GetSingleton() method will return null if the cache
  66  * is unavailable. The cache is only provided for libxul builds --
  67  * it will fail to link in non-libxul builds. The XPCOM interface is provided
  68  * only to allow compiled-code tests; clients should avoid using it.
  69  *
  70  * The API provided is very simple: GetBuffer() returns a buffer that was previously
  71  * stored in the cache (if any), and PutBuffer() inserts a buffer into the cache.
  72  * GetBuffer returns a new buffer, and the caller must take ownership of it.
  73  * PutBuffer will assert if the client attempts to insert a buffer with the same name as
  74  * an existing entry. The cache makes a copy of the passed-in buffer, so client
  75  * retains ownership.
  76  *
  77  * InvalidateCache() may be called if a client suspects data corruption
  78  * or wishes to invalidate for any other reason. This will remove all existing cache data.
  79  * Finally, getDebugObjectOutputStream() allows debug code to wrap an objectstream
  80  * with a debug objectstream, to check for multiply-referenced objects. These will
  81  * generally fail to deserialize correctly, unless they are stateless singletons or the
  82  * client maintains their own object data map for deserialization.
  83  *
  84  * Writes before the final-ui-startup notification are placed in an intermediate
  85  * cache in memory, then written out to disk at a later time, to get writes off the
  86  * startup path. In any case, clients should not rely on being able to GetBuffer()
  87  * data that is written to the cache, since it may not have been written to disk or
  88  * another client may have invalidated the cache. In other words, it should be used as
  89  * a cache only, and not a reliable persistent store.
  90  *
  91  * Some utility functions are provided in StartupCacheUtils. These functions wrap the
  92  * buffers into object streams, which may be useful for serializing objects. Note
  93  * the above caution about multiply-referenced objects, though -- the streams are just
  94  * as 'dumb' as the underlying buffers about multiply-referenced objects. They just
  95  * provide some convenience in writing out data.
  96  */
  97
  98 namespace mozilla {
  99 namespace scache {
 100
 101 struct CacheEntry
 102 {
 103   nsAutoArrayPtr<char> data;
 104   PRUint32 size;
 105
 106   CacheEntry() : data(nsnull), size(0) { }
 107
 108   // Takes possession of buf
 109   CacheEntry(char* buf, PRUint32 len) : data(buf), size(len) { }
 110
 111   ~CacheEntry()
 112   {
 113   }
 114 };
 115
 116 // We don't want to refcount StartupCache, and ObserverService wants to
 117 // refcount its listeners, so we'll let it refcount this instead.
 118 class StartupCacheListener : public nsIObserver
 119 {
 120   NS_DECL_ISUPPORTS
 121   NS_DECL_NSIOBSERVER
 122 };
 123
 124 class StartupCache
 125 {
 126
 127 friend class StartupCacheListener;
 128 friend class StartupCacheWrapper;
 129
 130 public:
 131
 132   // StartupCache methods. See above comments for a more detailed description.
 133
 134   // Returns a buffer that was previously stored, caller takes ownership.
 135   nsresult GetBuffer(const char* id, char** outbuf, PRUint32* length);
 136
 137   // Stores a buffer. Caller keeps ownership, we make a copy.
 138   nsresult PutBuffer(const char* id, const char* inbuf, PRUint32 length);
 139
 140   // Removes the cache file.
 141   void InvalidateCache();
 142
 143   // In DEBUG builds, returns a stream that will attempt to check for
 144   // and disallow multiple writes of the same object.
 145   nsresult GetDebugObjectOutputStream(nsIObjectOutputStream* aStream,
 146                                       nsIObjectOutputStream** outStream);
 147
 148   static StartupCache* GetSingleton();
 149   static void DeleteSingleton();
 150
 151 private:
 152   StartupCache();
 153   ~StartupCache();
 154
 155   nsresult LoadArchive();
 156   nsresult Init();
 157   void WriteToDisk();
 158   nsresult ResetStartupWriteTimer();
 159   void WaitOnWriteThread();
 160
 161   static nsresult InitSingleton();
 162   static void WriteTimeout(nsITimer *aTimer, void *aClosure);
 163   static void ThreadedWrite(void *aClosure);
 164
 165   nsClassHashtable<nsCStringHashKey, CacheEntry> mTable;
 166   nsAutoPtr<nsZipArchive> mArchive;
 167   nsCOMPtr<nsILocalFile> mFile;
 168
 169   nsCOMPtr<nsIObserverService> mObserverService;
 170   nsRefPtr<StartupCacheListener> mListener;
 171   nsCOMPtr<nsITimer> mTimer;
 172
 173   PRBool mStartupWriteInitiated;
 174
 175   static StartupCache *gStartupCache;
 176   static PRBool gShutdownInitiated;
 177   PRThread *mWriteThread;
 178 #ifdef DEBUG
 179   nsTHashtable<nsISupportsHashKey> mWriteObjectMap;
 180 #endif
 181 };
 182
 183 // This debug outputstream attempts to detect if clients are writing multiple
 184 // references to the same object. We only support that if that object
 185 // is a singleton.
 186 #ifdef DEBUG
 187 class StartupCacheDebugOutputStream
 188   : public nsIObjectOutputStream
 189 {
 190   NS_DECL_ISUPPORTS
 191   NS_DECL_NSIOBJECTOUTPUTSTREAM
 192
 193   StartupCacheDebugOutputStream (nsIObjectOutputStream* binaryStream,
 194                                    nsTHashtable<nsISupportsHashKey>* objectMap)
 195   : mBinaryStream(binaryStream), mObjectMap(objectMap) { }
 196
 197   NS_FORWARD_SAFE_NSIBINARYOUTPUTSTREAM(mBinaryStream)
 198   NS_FORWARD_SAFE_NSIOUTPUTSTREAM(mBinaryStream)
 199
 200   PRBool CheckReferences(nsISupports* aObject);
 201
 202   nsCOMPtr<nsIObjectOutputStream> mBinaryStream;
 203   nsTHashtable<nsISupportsHashKey> *mObjectMap;
 204 };
 205 #endif // DEBUG
 206
 207 // XPCOM wrapper interface provided for tests only.
 208 #define NS_STARTUPCACHE_CID \
 209       {0xae4505a9, 0x87ab, 0x477c, \
 210       {0xb5, 0x77, 0xf9, 0x23, 0x57, 0xed, 0xa8, 0x84}}
 211 // contract id: "@mozilla.org/startupcache/cache;1"
 212
 213 class StartupCacheWrapper
 214   : public nsIStartupCache
 215 {
 216   NS_DECL_ISUPPORTS
 217   NS_DECL_NSISTARTUPCACHE
 218
 219   static StartupCacheWrapper* GetSingleton();
 220   static StartupCacheWrapper *gStartupCacheWrapper;
 221 };
 222
 223 } // namespace scache
 224 } // namespace mozilla
 225 #endif //StartupCache_h_