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/. */
6 #ifndef StartupCache_h_
7 #define StartupCache_h_
11 #include "nsClassHashtable.h"
12 #include "nsComponentManagerUtils.h"
14 #include "nsTHashSet.h"
15 #include "nsTStringHasher.h" // mozilla::DefaultHasher<nsCString>
16 #include "nsZipArchive.h"
18 #include "nsIMemoryReporter.h"
19 #include "nsIObserverService.h"
20 #include "nsIObserver.h"
21 #include "nsIObjectOutputStream.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 #include "mozilla/UniquePtrExtensions.h"
33 * The StartupCache is a persistent cache of simple key-value pairs,
34 * where the keys are null-terminated c-strings and the values are
35 * arbitrary data, passed as a (char*, size) tuple.
37 * Clients should use the GetSingleton() static method to access the cache. It
38 * will be available from the end of XPCOM init (NS_InitXPCOM3 in
39 * XPCOMInit.cpp), until XPCOM shutdown begins. The GetSingleton() method will
40 * return null if the cache is unavailable. The cache is only provided for
41 * libxul builds -- it will fail to link in non-libxul builds. The XPCOM
42 * interface is provided only to allow compiled-code tests; clients should avoid
45 * The API provided is very simple: GetBuffer() returns a buffer that was
46 * previously stored in the cache (if any), and PutBuffer() inserts a buffer
47 * into the cache. GetBuffer returns a new buffer, and the caller must take
48 * ownership of it. PutBuffer will assert if the client attempts to insert a
49 * buffer with the same name as an existing entry. The cache makes a copy of the
50 * passed-in buffer, so client retains ownership.
52 * InvalidateCache() may be called if a client suspects data corruption
53 * or wishes to invalidate for any other reason. This will remove all existing
54 * cache data. Additionally, the static method IgnoreDiskCache() can be called
55 * if it is believed that the on-disk cache file is itself corrupt. This call
56 * implicitly calls InvalidateCache (if the singleton has been initialized) to
57 * ensure any data already read from disk is discarded. The cache will not load
58 * data from the disk file until a successful write occurs.
60 * Finally, getDebugObjectOutputStream() allows debug code to wrap an
61 * objectstream with a debug objectstream, to check for multiply-referenced
62 * objects. These will generally fail to deserialize correctly, unless they are
63 * stateless singletons or the client maintains their own object data map for
66 * Writes before the final-ui-startup notification are placed in an intermediate
67 * cache in memory, then written out to disk at a later time, to get writes off
68 * the startup path. In any case, clients should not rely on being able to
69 * GetBuffer() data that is written to the cache, since it may not have been
70 * written to disk or another client may have invalidated the cache. In other
71 * words, it should be used as a cache only, and not a reliable persistent
74 * Some utility functions are provided in StartupCacheUtils. These functions
75 * wrap the buffers into object streams, which may be useful for serializing
76 * objects. Note the above caution about multiply-referenced objects, though --
77 * the streams are just as 'dumb' as the underlying buffers about
78 * multiply-referenced objects. They just provide some convenience in writing
86 struct StartupCacheEntry
{
87 UniqueFreePtr
<char[]> mData
;
89 uint32_t mCompressedSize
;
90 uint32_t mUncompressedSize
;
91 int32_t mHeaderOffsetInFile
;
92 int32_t mRequestedOrder
;
95 MOZ_IMPLICIT
StartupCacheEntry(uint32_t aOffset
, uint32_t aCompressedSize
,
96 uint32_t aUncompressedSize
)
99 mCompressedSize(aCompressedSize
),
100 mUncompressedSize(aUncompressedSize
),
101 mHeaderOffsetInFile(0),
105 StartupCacheEntry(UniqueFreePtr
<char[]> aData
, size_t aLength
,
106 int32_t aRequestedOrder
)
107 : mData(std::move(aData
)),
110 mUncompressedSize(aLength
),
111 mHeaderOffsetInFile(0),
116 using Value
= std::pair
<const nsCString
*, StartupCacheEntry
*>;
118 bool Equals(const Value
& a
, const Value
& b
) const {
119 return a
.second
->mRequestedOrder
== b
.second
->mRequestedOrder
;
122 bool LessThan(const Value
& a
, const Value
& b
) const {
123 return a
.second
->mRequestedOrder
< b
.second
->mRequestedOrder
;
128 // We don't want to refcount StartupCache, and ObserverService wants to
129 // refcount its listeners, so we'll let it refcount this instead.
130 class StartupCacheListener final
: public nsIObserver
{
131 ~StartupCacheListener() = default;
132 NS_DECL_THREADSAFE_ISUPPORTS
136 class StartupCache
: public nsIMemoryReporter
{
137 friend class StartupCacheListener
;
140 NS_DECL_THREADSAFE_ISUPPORTS
141 NS_DECL_NSIMEMORYREPORTER
143 // StartupCache methods. See above comments for a more detailed description.
145 // true if the archive has an entry for the buffer or not.
146 bool HasEntry(const char* id
);
148 // Returns a buffer that was previously stored, caller does not take ownership
149 nsresult
GetBuffer(const char* id
, const char** outbuf
, uint32_t* length
);
151 // Stores a buffer. Caller yields ownership.
152 nsresult
PutBuffer(const char* id
, UniqueFreePtr
<char[]>&& inbuf
,
155 // Removes the cache file.
156 void InvalidateCache(bool memoryOnly
= false);
158 // If some event knowingly re-generates the startup cache (like live language
159 // switching) count these events in order to allow them.
160 void CountAllowedInvalidation();
162 // For use during shutdown - this will write the startupcache's data
163 // to disk if the timer hasn't already gone off.
164 void MaybeInitShutdownWrite();
166 // For use during shutdown - ensure we complete the shutdown write
167 // before shutdown, even in the FastShutdown case.
168 void EnsureShutdownWriteComplete();
170 // Signal that data should not be loaded from the cache file
171 static void IgnoreDiskCache();
173 // In DEBUG builds, returns a stream that will attempt to check for
174 // and disallow multiple writes of the same object.
175 nsresult
GetDebugObjectOutputStream(nsIObjectOutputStream
* aStream
,
176 nsIObjectOutputStream
** outStream
);
178 static StartupCache
* GetSingletonNoInit();
179 static StartupCache
* GetSingleton();
180 static void DeleteSingleton();
182 // This measures all the heap memory used by the StartupCache, i.e. it
183 // excludes the mapping.
184 size_t HeapSizeOfIncludingThis(mozilla::MallocSizeOf mallocSizeOf
) const;
186 bool ShouldCompactCache();
187 nsresult
ResetStartupWriteTimerCheckingReadCount();
188 nsresult
ResetStartupWriteTimer();
189 bool StartupWriteComplete();
193 virtual ~StartupCache();
195 friend class StartupCacheInfo
;
197 Result
<Ok
, nsresult
> LoadArchive();
200 // Returns a file pointer for the cache file with the given name in the
202 Result
<nsCOMPtr
<nsIFile
>, nsresult
> GetCacheFile(const nsAString
& suffix
);
204 // Opens the cache file for reading.
205 Result
<Ok
, nsresult
> OpenCache();
207 // Writes the cache to disk
208 Result
<Ok
, nsresult
> WriteToDisk();
210 void WaitOnPrefetchThread();
211 void StartPrefetchMemoryThread();
213 static nsresult
InitSingleton();
214 static void WriteTimeout(nsITimer
* aTimer
, void* aClosure
);
215 void MaybeWriteOffMainThread();
216 static void ThreadedPrefetch(void* aClosure
);
218 HashMap
<nsCString
, StartupCacheEntry
> mTable
;
219 // This owns references to the contents of tables which have been invalidated.
220 // In theory it grows forever if the cache is continually filled and then
221 // invalidated, but this should not happen in practice. Deleting old tables
222 // could create dangling pointers. RefPtrs could be introduced, but it would
223 // be a large amount of error-prone work to change.
224 nsTArray
<decltype(mTable
)> mOldTables
;
225 size_t mAllowedInvalidationsCount
;
226 nsCOMPtr
<nsIFile
> mFile
;
227 loader::AutoMemMap mCacheData
;
228 Mutex mTableLock MOZ_UNANNOTATED
;
230 nsCOMPtr
<nsIObserverService
> mObserverService
;
231 RefPtr
<StartupCacheListener
> mListener
;
232 nsCOMPtr
<nsITimer
> mTimer
;
235 Atomic
<bool> mWrittenOnce
;
236 bool mCurTableReferenced
;
237 uint32_t mRequestedCount
;
238 size_t mCacheEntriesBaseOffset
;
240 static StaticRefPtr
<StartupCache
> gStartupCache
;
241 static bool gShutdownInitiated
;
242 static bool gIgnoreDiskCache
;
243 static bool gFoundDiskCacheOnInit
;
244 PRThread
* mPrefetchThread
;
245 UniquePtr
<Compression::LZ4FrameDecompressionContext
> mDecompressionContext
;
247 nsTHashSet
<nsCOMPtr
<nsISupports
>> mWriteObjectMap
;
251 // This debug outputstream attempts to detect if clients are writing multiple
252 // references to the same object. We only support that if that object
255 class StartupCacheDebugOutputStream final
: public nsIObjectOutputStream
{
256 ~StartupCacheDebugOutputStream() = default;
259 NS_DECL_NSIOBJECTOUTPUTSTREAM
261 StartupCacheDebugOutputStream(nsIObjectOutputStream
* binaryStream
,
262 nsTHashSet
<nsCOMPtr
<nsISupports
>>* objectMap
)
263 : mBinaryStream(binaryStream
), mObjectMap(objectMap
) {}
265 NS_FORWARD_SAFE_NSIBINARYOUTPUTSTREAM(mBinaryStream
)
266 NS_FORWARD_SAFE_NSIOUTPUTSTREAM(mBinaryStream
)
268 bool CheckReferences(nsISupports
* aObject
);
270 nsCOMPtr
<nsIObjectOutputStream
> mBinaryStream
;
271 nsTHashSet
<nsCOMPtr
<nsISupports
>>* mObjectMap
;
275 } // namespace scache
276 } // namespace mozilla
278 #endif // StartupCache_h_