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  * Additionally, the static method IgnoreDiskCache() can be called if it is
  48  * believed that the on-disk cache file is itself corrupt. This call implicitly
  49  * calls InvalidateCache (if the singleton has been initialized) to ensure any
  50  * data already read from disk is discarded. The cache will not load data from
  51  * the disk file until a successful write occurs.
  52  *
  53  * Finally, getDebugObjectOutputStream() allows debug code to wrap an objectstream
  54  * with a debug objectstream, to check for multiply-referenced objects. These will
  55  * generally fail to deserialize correctly, unless they are stateless singletons or the
  56  * client maintains their own object data map for deserialization.
  57  *
  58  * Writes before the final-ui-startup notification are placed in an intermediate
  59  * cache in memory, then written out to disk at a later time, to get writes off the
  60  * startup path. In any case, clients should not rely on being able to GetBuffer()
  61  * data that is written to the cache, since it may not have been written to disk or
  62  * another client may have invalidated the cache. In other words, it should be used as
  63  * a cache only, and not a reliable persistent store.
  64  *
  65  * Some utility functions are provided in StartupCacheUtils. These functions wrap the
  66  * buffers into object streams, which may be useful for serializing objects. Note
  67  * the above caution about multiply-referenced objects, though -- the streams are just
  68  * as 'dumb' as the underlying buffers about multiply-referenced objects. They just
  69  * provide some convenience in writing out data.
  70  */
  71
  72 class nsIMemoryReporter;
  73
  74 namespace mozilla {
  75 namespace scache {
  76
  77 struct CacheEntry
  78 {
  79   nsAutoArrayPtr<char> data;
  80   uint32_t size;
  81
  82   CacheEntry() : data(nullptr), size(0) { }
  83
  84   // Takes possession of buf
  85   CacheEntry(char* buf, uint32_t len) : data(buf), size(len) { }
  86
  87   ~CacheEntry()
  88   {
  89   }
  90
  91   size_t SizeOfExcludingThis(nsMallocSizeOfFun mallocSizeOf) {
  92     return mallocSizeOf(data);
  93   }
  94 };
  95
  96 // We don't want to refcount StartupCache, and ObserverService wants to
  97 // refcount its listeners, so we'll let it refcount this instead.
  98 class StartupCacheListener MOZ_FINAL : public nsIObserver
  99 {
 100   NS_DECL_ISUPPORTS
 101   NS_DECL_NSIOBSERVER
 102 };
 103
 104 class StartupCache
 105 {
 106
 107 friend class StartupCacheListener;
 108 friend class StartupCacheWrapper;
 109
 110 public:
 111
 112   // StartupCache methods. See above comments for a more detailed description.
 113
 114   // Returns a buffer that was previously stored, caller takes ownership.
 115   nsresult GetBuffer(const char* id, char** outbuf, uint32_t* length);
 116
 117   // Stores a buffer. Caller keeps ownership, we make a copy.
 118   nsresult PutBuffer(const char* id, const char* inbuf, uint32_t length);
 119
 120   // Removes the cache file.
 121   void InvalidateCache();
 122
 123   // Signal that data should not be loaded from the cache file
 124   static void IgnoreDiskCache();
 125
 126   // In DEBUG builds, returns a stream that will attempt to check for
 127   // and disallow multiple writes of the same object.
 128   nsresult GetDebugObjectOutputStream(nsIObjectOutputStream* aStream,
 129                                       nsIObjectOutputStream** outStream);
 130
 131   nsresult RecordAgesAlways();
 132
 133   static StartupCache* GetSingleton();
 134   static void DeleteSingleton();
 135
 136   // This measures all the heap memory used by the StartupCache, i.e. it
 137   // excludes the mapping.
 138   size_t HeapSizeOfIncludingThis(nsMallocSizeOfFun mallocSizeOf);
 139
 140   size_t SizeOfMapping();
 141
 142 private:
 143   StartupCache();
 144   ~StartupCache();
 145
 146   enum TelemetrifyAge {
 147     IGNORE_AGE = 0,
 148     RECORD_AGE = 1
 149   };
 150   static enum TelemetrifyAge gPostFlushAgeAction;
 151
 152   nsresult LoadArchive(enum TelemetrifyAge flag);
 153   nsresult Init();
 154   void WriteToDisk();
 155   nsresult ResetStartupWriteTimer();
 156   void WaitOnWriteThread();
 157
 158   static nsresult InitSingleton();
 159   static void WriteTimeout(nsITimer *aTimer, void *aClosure);
 160   static void ThreadedWrite(void *aClosure);
 161
 162   static size_t SizeOfEntryExcludingThis(const nsACString& key,
 163                                          const nsAutoPtr<CacheEntry>& data,
 164                                          nsMallocSizeOfFun mallocSizeOf,
 165                                          void *);
 166
 167   nsClassHashtable<nsCStringHashKey, CacheEntry> mTable;
 168   nsRefPtr<nsZipArchive> mArchive;
 169   nsCOMPtr<nsIFile> mFile;
 170
 171   nsCOMPtr<nsIObserverService> mObserverService;
 172   nsRefPtr<StartupCacheListener> mListener;
 173   nsCOMPtr<nsITimer> mTimer;
 174
 175   bool mStartupWriteInitiated;
 176
 177   static StartupCache *gStartupCache;
 178   static bool gShutdownInitiated;
 179   static bool gIgnoreDiskCache;
 180   PRThread *mWriteThread;
 181 #ifdef DEBUG
 182   nsTHashtable<nsISupportsHashKey> mWriteObjectMap;
 183 #endif
 184
 185   nsIMemoryReporter* mMappingMemoryReporter;
 186   nsIMemoryReporter* mDataMemoryReporter;
 187 };
 188
 189 // This debug outputstream attempts to detect if clients are writing multiple
 190 // references to the same object. We only support that if that object
 191 // is a singleton.
 192 #ifdef DEBUG
 193 class StartupCacheDebugOutputStream MOZ_FINAL
 194   : public nsIObjectOutputStream
 195 {
 196   NS_DECL_ISUPPORTS
 197   NS_DECL_NSIOBJECTOUTPUTSTREAM
 198
 199   StartupCacheDebugOutputStream (nsIObjectOutputStream* binaryStream,
 200                                    nsTHashtable<nsISupportsHashKey>* objectMap)
 201   : mBinaryStream(binaryStream), mObjectMap(objectMap) { }
 202
 203   NS_FORWARD_SAFE_NSIBINARYOUTPUTSTREAM(mBinaryStream)
 204   NS_FORWARD_SAFE_NSIOUTPUTSTREAM(mBinaryStream)
 205
 206   bool CheckReferences(nsISupports* aObject);
 207
 208   nsCOMPtr<nsIObjectOutputStream> mBinaryStream;
 209   nsTHashtable<nsISupportsHashKey> *mObjectMap;
 210 };
 211 #endif // DEBUG
 212
 213 // XPCOM wrapper interface provided for tests only.
 214 #define NS_STARTUPCACHE_CID \
 215       {0xae4505a9, 0x87ab, 0x477c, \
 216       {0xb5, 0x77, 0xf9, 0x23, 0x57, 0xed, 0xa8, 0x84}}
 217 // contract id: "@mozilla.org/startupcache/cache;1"
 218
 219 class StartupCacheWrapper MOZ_FINAL
 220   : public nsIStartupCache
 221 {
 222   NS_DECL_ISUPPORTS
 223   NS_DECL_NSISTARTUPCACHE
 224
 225   static StartupCacheWrapper* GetSingleton();
 226   static StartupCacheWrapper *gStartupCacheWrapper;
 227 };
 228
 229 } // namespace scache
 230 } // namespace mozilla
 231 #endif //StartupCache_h_