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 "nsClassHashtable.h"
  10 #include "nsComponentManagerUtils.h"
  11 #include "nsTArray.h"
  12 #include "nsZipArchive.h"
  13 #include "nsITimer.h"
  14 #include "nsIMemoryReporter.h"
  15 #include "nsIObserverService.h"
  16 #include "nsIObserver.h"
  17 #include "nsIObjectOutputStream.h"
  18 #include "nsIOutputStream.h"
  19 #include "nsIFile.h"
  20 #include "mozilla/Attributes.h"
  21 #include "mozilla/MemoryReporting.h"
  22 #include "mozilla/UniquePtr.h"
  23
  24 /**
  25  * The StartupCache is a persistent cache of simple key-value pairs,
  26  * where the keys are null-terminated c-strings and the values are
  27  * arbitrary data, passed as a (char*, size) tuple.
  28  *
  29  * Clients should use the GetSingleton() static method to access the cache. It
  30  * will be available from the end of XPCOM init (NS_InitXPCOM3 in
  31  * XPCOMInit.cpp), until XPCOM shutdown begins. The GetSingleton() method will
  32  * return null if the cache is unavailable. The cache is only provided for
  33  * libxul builds -- it will fail to link in non-libxul builds. The XPCOM
  34  * interface is provided only to allow compiled-code tests; clients should avoid
  35  * using it.
  36  *
  37  * The API provided is very simple: GetBuffer() returns a buffer that was
  38  * previously stored in the cache (if any), and PutBuffer() inserts a buffer
  39  * into the cache. GetBuffer returns a new buffer, and the caller must take
  40  * ownership of it. PutBuffer will assert if the client attempts to insert a
  41  * buffer with the same name as an existing entry. The cache makes a copy of the
  42  * passed-in buffer, so client retains ownership.
  43  *
  44  * InvalidateCache() may be called if a client suspects data corruption
  45  * or wishes to invalidate for any other reason. This will remove all existing
  46  * cache data. Additionally, the static method IgnoreDiskCache() can be called
  47  * if it is believed that the on-disk cache file is itself corrupt. This call
  48  * implicitly calls InvalidateCache (if the singleton has been initialized) to
  49  * ensure any data already read from disk is discarded. The cache will not load
  50  * data from the disk file until a successful write occurs.
  51  *
  52  * Finally, getDebugObjectOutputStream() allows debug code to wrap an
  53  * objectstream with a debug objectstream, to check for multiply-referenced
  54  * objects. These will generally fail to deserialize correctly, unless they are
  55  * stateless singletons or the client maintains their own object data map for
  56  * 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
  60  * the startup path. In any case, clients should not rely on being able to
  61  * GetBuffer() data that is written to the cache, since it may not have been
  62  * written to disk or another client may have invalidated the cache. In other
  63  * words, it should be used as a cache only, and not a reliable persistent
  64  * store.
  65  *
  66  * Some utility functions are provided in StartupCacheUtils. These functions
  67  * wrap the buffers into object streams, which may be useful for serializing
  68  * objects. Note the above caution about multiply-referenced objects, though --
  69  * the streams are just as 'dumb' as the underlying buffers about
  70  * multiply-referenced objects. They just provide some convenience in writing
  71  * out data.
  72  */
  73
  74 namespace mozilla {
  75
  76 namespace scache {
  77
  78 struct CacheEntry {
  79   UniquePtr<char[]> data;
  80   uint32_t size;
  81
  82   CacheEntry() : size(0) {}
  83
  84   // Takes possession of buf
  85   CacheEntry(UniquePtr<char[]> buf, uint32_t len)
  86       : data(std::move(buf)), size(len) {}
  87
  88   ~CacheEntry() {}
  89
  90   size_t SizeOfIncludingThis(mozilla::MallocSizeOf mallocSizeOf) {
  91     return mallocSizeOf(this) + mallocSizeOf(data.get());
  92   }
  93 };
  94
  95 // We don't want to refcount StartupCache, and ObserverService wants to
  96 // refcount its listeners, so we'll let it refcount this instead.
  97 class StartupCacheListener final : public nsIObserver {
  98   ~StartupCacheListener() {}
  99   NS_DECL_THREADSAFE_ISUPPORTS
 100   NS_DECL_NSIOBSERVER
 101 };
 102
 103 class StartupCache : public nsIMemoryReporter {
 104   friend class StartupCacheListener;
 105
 106  public:
 107   NS_DECL_THREADSAFE_ISUPPORTS
 108   NS_DECL_NSIMEMORYREPORTER
 109
 110   // StartupCache methods. See above comments for a more detailed description.
 111
 112   // Returns a buffer that was previously stored, caller takes ownership.
 113   nsresult GetBuffer(const char* id, UniquePtr<char[]>* outbuf,
 114                      uint32_t* length);
 115
 116   // Stores a buffer. Caller yields ownership.
 117   nsresult PutBuffer(const char* id, UniquePtr<char[]>&& inbuf,
 118                      uint32_t length);
 119
 120   // Removes the cache file.
 121   void InvalidateCache(bool memoryOnly = false);
 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   static StartupCache* GetSingleton();
 132   static void DeleteSingleton();
 133
 134   // This measures all the heap memory used by the StartupCache, i.e. it
 135   // excludes the mapping.
 136   size_t HeapSizeOfIncludingThis(mozilla::MallocSizeOf mallocSizeOf) const;
 137
 138   size_t SizeOfMapping();
 139
 140   // FOR TESTING ONLY
 141   nsresult ResetStartupWriteTimer();
 142   bool StartupWriteComplete();
 143
 144  private:
 145   StartupCache();
 146   virtual ~StartupCache();
 147
 148   nsresult LoadArchive();
 149   nsresult Init();
 150   void WriteToDisk();
 151   void WaitOnWriteThread();
 152
 153   static nsresult InitSingleton();
 154   static void WriteTimeout(nsITimer* aTimer, void* aClosure);
 155   static void ThreadedWrite(void* aClosure);
 156
 157   nsClassHashtable<nsCStringHashKey, CacheEntry> mTable;
 158   nsTArray<nsCString> mPendingWrites;
 159   RefPtr<nsZipArchive> mArchive;
 160   nsCOMPtr<nsIFile> mFile;
 161
 162   nsCOMPtr<nsIObserverService> mObserverService;
 163   RefPtr<StartupCacheListener> mListener;
 164   nsCOMPtr<nsITimer> mTimer;
 165
 166   bool mStartupWriteInitiated;
 167
 168   static StaticRefPtr<StartupCache> gStartupCache;
 169   static bool gShutdownInitiated;
 170   static bool gIgnoreDiskCache;
 171   PRThread* mWriteThread;
 172 #ifdef DEBUG
 173   nsTHashtable<nsISupportsHashKey> mWriteObjectMap;
 174 #endif
 175 };
 176
 177 // This debug outputstream attempts to detect if clients are writing multiple
 178 // references to the same object. We only support that if that object
 179 // is a singleton.
 180 #ifdef DEBUG
 181 class StartupCacheDebugOutputStream final : public nsIObjectOutputStream {
 182   ~StartupCacheDebugOutputStream() {}
 183
 184   NS_DECL_ISUPPORTS
 185   NS_DECL_NSIOBJECTOUTPUTSTREAM
 186
 187   StartupCacheDebugOutputStream(nsIObjectOutputStream* binaryStream,
 188                                 nsTHashtable<nsISupportsHashKey>* objectMap)
 189       : mBinaryStream(binaryStream), mObjectMap(objectMap) {}
 190
 191   NS_FORWARD_SAFE_NSIBINARYOUTPUTSTREAM(mBinaryStream)
 192   NS_FORWARD_SAFE_NSIOUTPUTSTREAM(mBinaryStream)
 193
 194   bool CheckReferences(nsISupports* aObject);
 195
 196   nsCOMPtr<nsIObjectOutputStream> mBinaryStream;
 197   nsTHashtable<nsISupportsHashKey>* mObjectMap;
 198 };
 199 #endif  // DEBUG
 200
 201 }  // namespace scache
 202 }  // namespace mozilla
 203
 204 #endif  // StartupCache_h_