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 <utility>
10 
11 #include "nsClassHashtable.h"
12 #include "nsComponentManagerUtils.h"
13 #include "nsTArray.h"
14 #include "nsTHashSet.h"
15 #include "nsTStringHasher.h"  // mozilla::DefaultHasher<nsCString>
16 #include "nsZipArchive.h"
17 #include "nsITimer.h"
18 #include "nsIMemoryReporter.h"
19 #include "nsIObserverService.h"
20 #include "nsIObserver.h"
21 #include "nsIObjectOutputStream.h"
22 #include "nsIFile.h"
23 #include "mozilla/Attributes.h"
24 #include "mozilla/AutoMemMap.h"
25 #include "mozilla/Compression.h"
26 #include "mozilla/MemoryReporting.h"
27 #include "mozilla/Mutex.h"
28 #include "mozilla/Result.h"
29 #include "mozilla/UniquePtr.h"
30 
31 /**
32  * The StartupCache is a persistent cache of simple key-value pairs,
33  * where the keys are null-terminated c-strings and the values are
34  * arbitrary data, passed as a (char*, size) tuple.
35  *
36  * Clients should use the GetSingleton() static method to access the cache. It
37  * will be available from the end of XPCOM init (NS_InitXPCOM3 in
38  * XPCOMInit.cpp), until XPCOM shutdown begins. The GetSingleton() method will
39  * return null if the cache is unavailable. The cache is only provided for
40  * libxul builds -- it will fail to link in non-libxul builds. The XPCOM
41  * interface is provided only to allow compiled-code tests; clients should avoid
42  * using it.
43  *
44  * The API provided is very simple: GetBuffer() returns a buffer that was
45  * previously stored in the cache (if any), and PutBuffer() inserts a buffer
46  * into the cache. GetBuffer returns a new buffer, and the caller must take
47  * ownership of it. PutBuffer will assert if the client attempts to insert a
48  * buffer with the same name as an existing entry. The cache makes a copy of the
49  * passed-in buffer, so client retains ownership.
50  *
51  * InvalidateCache() may be called if a client suspects data corruption
52  * or wishes to invalidate for any other reason. This will remove all existing
53  * cache data. Additionally, the static method IgnoreDiskCache() can be called
54  * if it is believed that the on-disk cache file is itself corrupt. This call
55  * implicitly calls InvalidateCache (if the singleton has been initialized) to
56  * ensure any data already read from disk is discarded. The cache will not load
57  * data from the disk file until a successful write occurs.
58  *
59  * Finally, getDebugObjectOutputStream() allows debug code to wrap an
60  * objectstream with a debug objectstream, to check for multiply-referenced
61  * objects. These will generally fail to deserialize correctly, unless they are
62  * stateless singletons or the client maintains their own object data map for
63  * deserialization.
64  *
65  * Writes before the final-ui-startup notification are placed in an intermediate
66  * cache in memory, then written out to disk at a later time, to get writes off
67  * the startup path. In any case, clients should not rely on being able to
68  * GetBuffer() data that is written to the cache, since it may not have been
69  * written to disk or another client may have invalidated the cache. In other
70  * words, it should be used as a cache only, and not a reliable persistent
71  * store.
72  *
73  * Some utility functions are provided in StartupCacheUtils. These functions
74  * wrap the buffers into object streams, which may be useful for serializing
75  * objects. Note the above caution about multiply-referenced objects, though --
76  * the streams are just as 'dumb' as the underlying buffers about
77  * multiply-referenced objects. They just provide some convenience in writing
78  * out data.
79  */
80 
81 namespace mozilla {
82 
83 namespace scache {
84 
85 struct StartupCacheEntry {
86   UniquePtr<char[]> mData;
87   uint32_t mOffset;
88   uint32_t mCompressedSize;
89   uint32_t mUncompressedSize;
90   int32_t mHeaderOffsetInFile;
91   int32_t mRequestedOrder;
92   bool mRequested;
93 
StartupCacheEntryStartupCacheEntry94   MOZ_IMPLICIT StartupCacheEntry(uint32_t aOffset, uint32_t aCompressedSize,
95                                  uint32_t aUncompressedSize)
96       : mData(nullptr),
97         mOffset(aOffset),
98         mCompressedSize(aCompressedSize),
99         mUncompressedSize(aUncompressedSize),
100         mHeaderOffsetInFile(0),
101         mRequestedOrder(0),
102         mRequested(false) {}
103 
StartupCacheEntryStartupCacheEntry104   StartupCacheEntry(UniquePtr<char[]> aData, size_t aLength,
105                     int32_t aRequestedOrder)
106       : mData(std::move(aData)),
107         mOffset(0),
108         mCompressedSize(0),
109         mUncompressedSize(aLength),
110         mHeaderOffsetInFile(0),
111         mRequestedOrder(0),
112         mRequested(true) {}
113 
114   struct Comparator {
115     using Value = std::pair<const nsCString*, StartupCacheEntry*>;
116 
EqualsStartupCacheEntry::Comparator117     bool Equals(const Value& a, const Value& b) const {
118       return a.second->mRequestedOrder == b.second->mRequestedOrder;
119     }
120 
LessThanStartupCacheEntry::Comparator121     bool LessThan(const Value& a, const Value& b) const {
122       return a.second->mRequestedOrder < b.second->mRequestedOrder;
123     }
124   };
125 };
126 
127 // We don't want to refcount StartupCache, and ObserverService wants to
128 // refcount its listeners, so we'll let it refcount this instead.
129 class StartupCacheListener final : public nsIObserver {
130   ~StartupCacheListener() = default;
131   NS_DECL_THREADSAFE_ISUPPORTS
132   NS_DECL_NSIOBSERVER
133 };
134 
135 class StartupCache : public nsIMemoryReporter {
136   friend class StartupCacheListener;
137 
138  public:
139   NS_DECL_THREADSAFE_ISUPPORTS
140   NS_DECL_NSIMEMORYREPORTER
141 
142   // StartupCache methods. See above comments for a more detailed description.
143 
144   // true if the archive has an entry for the buffer or not.
145   bool HasEntry(const char* id);
146 
147   // Returns a buffer that was previously stored, caller does not take ownership
148   nsresult GetBuffer(const char* id, const char** outbuf, uint32_t* length);
149 
150   // Stores a buffer. Caller yields ownership.
151   nsresult PutBuffer(const char* id, UniquePtr<char[]>&& inbuf,
152                      uint32_t length);
153 
154   // Removes the cache file.
155   void InvalidateCache(bool memoryOnly = false);
156 
157   // For use during shutdown - this will write the startupcache's data
158   // to disk if the timer hasn't already gone off.
159   void MaybeInitShutdownWrite();
160 
161   // For use during shutdown - ensure we complete the shutdown write
162   // before shutdown, even in the FastShutdown case.
163   void EnsureShutdownWriteComplete();
164 
165   // Signal that data should not be loaded from the cache file
166   static void IgnoreDiskCache();
167 
168   // In DEBUG builds, returns a stream that will attempt to check for
169   // and disallow multiple writes of the same object.
170   nsresult GetDebugObjectOutputStream(nsIObjectOutputStream* aStream,
171                                       nsIObjectOutputStream** outStream);
172 
173   static StartupCache* GetSingletonNoInit();
174   static StartupCache* GetSingleton();
175   static void DeleteSingleton();
176 
177   // This measures all the heap memory used by the StartupCache, i.e. it
178   // excludes the mapping.
179   size_t HeapSizeOfIncludingThis(mozilla::MallocSizeOf mallocSizeOf) const;
180 
181   bool ShouldCompactCache();
182   nsresult ResetStartupWriteTimerCheckingReadCount();
183   nsresult ResetStartupWriteTimer();
184   bool StartupWriteComplete();
185 
186  private:
187   StartupCache();
188   virtual ~StartupCache();
189 
190   friend class StartupCacheInfo;
191 
192   Result<Ok, nsresult> LoadArchive();
193   nsresult Init();
194 
195   // Returns a file pointer for the cache file with the given name in the
196   // current profile.
197   Result<nsCOMPtr<nsIFile>, nsresult> GetCacheFile(const nsAString& suffix);
198 
199   // Opens the cache file for reading.
200   Result<Ok, nsresult> OpenCache();
201 
202   // Writes the cache to disk
203   Result<Ok, nsresult> WriteToDisk();
204 
205   void WaitOnPrefetchThread();
206   void StartPrefetchMemoryThread();
207 
208   static nsresult InitSingleton();
209   static void WriteTimeout(nsITimer* aTimer, void* aClosure);
210   void MaybeWriteOffMainThread();
211   static void ThreadedPrefetch(void* aClosure);
212 
213   HashMap<nsCString, StartupCacheEntry> mTable;
214   // owns references to the contents of tables which have been invalidated.
215   // In theory grows forever if the cache is continually filled and then
216   // invalidated, but this should not happen in practice.
217   nsTArray<decltype(mTable)> mOldTables;
218   nsCOMPtr<nsIFile> mFile;
219   loader::AutoMemMap mCacheData;
220   Mutex mTableLock;
221 
222   nsCOMPtr<nsIObserverService> mObserverService;
223   RefPtr<StartupCacheListener> mListener;
224   nsCOMPtr<nsITimer> mTimer;
225 
226   Atomic<bool> mDirty;
227   Atomic<bool> mWrittenOnce;
228   bool mCurTableReferenced;
229   uint32_t mRequestedCount;
230   size_t mCacheEntriesBaseOffset;
231 
232   static StaticRefPtr<StartupCache> gStartupCache;
233   static bool gShutdownInitiated;
234   static bool gIgnoreDiskCache;
235   static bool gFoundDiskCacheOnInit;
236   PRThread* mPrefetchThread;
237   UniquePtr<Compression::LZ4FrameDecompressionContext> mDecompressionContext;
238 #ifdef DEBUG
239   nsTHashSet<nsCOMPtr<nsISupports>> mWriteObjectMap;
240 #endif
241 };
242 
243 // This debug outputstream attempts to detect if clients are writing multiple
244 // references to the same object. We only support that if that object
245 // is a singleton.
246 #ifdef DEBUG
247 class StartupCacheDebugOutputStream final : public nsIObjectOutputStream {
248   ~StartupCacheDebugOutputStream() = default;
249 
250   NS_DECL_ISUPPORTS
251   NS_DECL_NSIOBJECTOUTPUTSTREAM
252 
StartupCacheDebugOutputStream(nsIObjectOutputStream * binaryStream,nsTHashSet<nsCOMPtr<nsISupports>> * objectMap)253   StartupCacheDebugOutputStream(nsIObjectOutputStream* binaryStream,
254                                 nsTHashSet<nsCOMPtr<nsISupports>>* objectMap)
255       : mBinaryStream(binaryStream), mObjectMap(objectMap) {}
256 
257   NS_FORWARD_SAFE_NSIBINARYOUTPUTSTREAM(mBinaryStream)
258   NS_FORWARD_SAFE_NSIOUTPUTSTREAM(mBinaryStream)
259 
260   bool CheckReferences(nsISupports* aObject);
261 
262   nsCOMPtr<nsIObjectOutputStream> mBinaryStream;
263   nsTHashSet<nsCOMPtr<nsISupports>>* mObjectMap;
264 };
265 #endif  // DEBUG
266 
267 }  // namespace scache
268 }  // namespace mozilla
269 
270 #endif  // StartupCache_h_
271