startupcache/StartupCache.h

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