Bumping manifests a=b2g-bump
[gecko.git] / startupcache / StartupCache.h
blobcba030a057bcc4f1e67ce9d2cc90f476c28bc2ac
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_
9 #include "nsClassHashtable.h"
10 #include "nsComponentManagerUtils.h"
11 #include "nsZipArchive.h"
12 #include "nsIStartupCache.h"
13 #include "nsITimer.h"
14 #include "nsIMemoryReporter.h"
15 #include "nsIObserverService.h"
16 #include "nsIObserver.h"
17 #include "nsIOutputStream.h"
18 #include "nsIFile.h"
19 #include "mozilla/Attributes.h"
20 #include "mozilla/MemoryReporting.h"
21 #include "mozilla/StaticPtr.h"
23 /**
24 * The StartupCache is a persistent cache of simple key-value pairs,
25 * where the keys are null-terminated c-strings and the values are
26 * arbitrary data, passed as a (char*, size) tuple.
28 * Clients should use the GetSingleton() static method to access the cache. It
29 * will be available from the end of XPCOM init (NS_InitXPCOM3 in nsXPComInit.cpp),
30 * until XPCOM shutdown begins. The GetSingleton() method will return null if the cache
31 * is unavailable. The cache is only provided for libxul builds --
32 * it will fail to link in non-libxul builds. The XPCOM interface is provided
33 * only to allow compiled-code tests; clients should avoid using it.
35 * The API provided is very simple: GetBuffer() returns a buffer that was previously
36 * stored in the cache (if any), and PutBuffer() inserts a buffer into the cache.
37 * GetBuffer returns a new buffer, and the caller must take ownership of it.
38 * PutBuffer will assert if the client attempts to insert a buffer with the same name as
39 * an existing entry. The cache makes a copy of the passed-in buffer, so client
40 * retains ownership.
42 * InvalidateCache() may be called if a client suspects data corruption
43 * or wishes to invalidate for any other reason. This will remove all existing cache data.
44 * Additionally, the static method IgnoreDiskCache() can be called if it is
45 * believed that the on-disk cache file is itself corrupt. This call implicitly
46 * calls InvalidateCache (if the singleton has been initialized) to ensure any
47 * data already read from disk is discarded. The cache will not load data from
48 * the disk file until a successful write occurs.
50 * Finally, getDebugObjectOutputStream() allows debug code to wrap an objectstream
51 * with a debug objectstream, to check for multiply-referenced objects. These will
52 * generally fail to deserialize correctly, unless they are stateless singletons or the
53 * client maintains their own object data map for deserialization.
55 * Writes before the final-ui-startup notification are placed in an intermediate
56 * cache in memory, then written out to disk at a later time, to get writes off the
57 * startup path. In any case, clients should not rely on being able to GetBuffer()
58 * data that is written to the cache, since it may not have been written to disk or
59 * another client may have invalidated the cache. In other words, it should be used as
60 * a cache only, and not a reliable persistent store.
62 * Some utility functions are provided in StartupCacheUtils. These functions wrap the
63 * buffers into object streams, which may be useful for serializing objects. Note
64 * the above caution about multiply-referenced objects, though -- the streams are just
65 * as 'dumb' as the underlying buffers about multiply-referenced objects. They just
66 * provide some convenience in writing out data.
69 namespace mozilla {
71 namespace scache {
73 struct CacheEntry
75 nsAutoArrayPtr<char> data;
76 uint32_t size;
78 CacheEntry() : data(nullptr), size(0) { }
80 // Takes possession of buf
81 CacheEntry(char* buf, uint32_t len) : data(buf), size(len) { }
83 ~CacheEntry()
87 size_t SizeOfExcludingThis(mozilla::MallocSizeOf mallocSizeOf) {
88 return mallocSizeOf(data);
92 // We don't want to refcount StartupCache, and ObserverService wants to
93 // refcount its listeners, so we'll let it refcount this instead.
94 class StartupCacheListener MOZ_FINAL : public nsIObserver
96 ~StartupCacheListener() {}
97 NS_DECL_THREADSAFE_ISUPPORTS
98 NS_DECL_NSIOBSERVER
101 class StartupCache : public nsIMemoryReporter
104 friend class StartupCacheListener;
105 friend class StartupCacheWrapper;
107 public:
108 NS_DECL_THREADSAFE_ISUPPORTS
109 NS_DECL_NSIMEMORYREPORTER
111 // StartupCache methods. See above comments for a more detailed description.
113 // Returns a buffer that was previously stored, caller takes ownership.
114 nsresult GetBuffer(const char* id, char** outbuf, uint32_t* length);
116 // Stores a buffer. Caller keeps ownership, we make a copy.
117 nsresult PutBuffer(const char* id, const char* inbuf, uint32_t length);
119 // Removes the cache file.
120 void InvalidateCache();
122 // Signal that data should not be loaded from the cache file
123 static void IgnoreDiskCache();
125 // In DEBUG builds, returns a stream that will attempt to check for
126 // and disallow multiple writes of the same object.
127 nsresult GetDebugObjectOutputStream(nsIObjectOutputStream* aStream,
128 nsIObjectOutputStream** outStream);
130 nsresult RecordAgesAlways();
132 static StartupCache* GetSingleton();
133 static void DeleteSingleton();
135 // This measures all the heap memory used by the StartupCache, i.e. it
136 // excludes the mapping.
137 size_t HeapSizeOfIncludingThis(mozilla::MallocSizeOf mallocSizeOf);
139 size_t SizeOfMapping();
141 private:
142 StartupCache();
143 virtual ~StartupCache();
145 enum TelemetrifyAge {
146 IGNORE_AGE = 0,
147 RECORD_AGE = 1
149 static enum TelemetrifyAge gPostFlushAgeAction;
151 nsresult LoadArchive(enum TelemetrifyAge flag);
152 nsresult Init();
153 void WriteToDisk();
154 nsresult ResetStartupWriteTimer();
155 void WaitOnWriteThread();
157 static nsresult InitSingleton();
158 static void WriteTimeout(nsITimer *aTimer, void *aClosure);
159 static void ThreadedWrite(void *aClosure);
161 static size_t SizeOfEntryExcludingThis(const nsACString& key,
162 const nsAutoPtr<CacheEntry>& data,
163 mozilla::MallocSizeOf mallocSizeOf,
164 void *);
166 nsClassHashtable<nsCStringHashKey, CacheEntry> mTable;
167 nsRefPtr<nsZipArchive> mArchive;
168 nsCOMPtr<nsIFile> mFile;
170 nsCOMPtr<nsIObserverService> mObserverService;
171 nsRefPtr<StartupCacheListener> mListener;
172 nsCOMPtr<nsITimer> mTimer;
174 bool mStartupWriteInitiated;
176 static StaticRefPtr<StartupCache> gStartupCache;
177 static bool gShutdownInitiated;
178 static bool gIgnoreDiskCache;
179 PRThread *mWriteThread;
180 #ifdef DEBUG
181 nsTHashtable<nsISupportsHashKey> mWriteObjectMap;
182 #endif
185 // This debug outputstream attempts to detect if clients are writing multiple
186 // references to the same object. We only support that if that object
187 // is a singleton.
188 #ifdef DEBUG
189 class StartupCacheDebugOutputStream MOZ_FINAL
190 : public nsIObjectOutputStream
192 ~StartupCacheDebugOutputStream() {}
194 NS_DECL_ISUPPORTS
195 NS_DECL_NSIOBJECTOUTPUTSTREAM
197 StartupCacheDebugOutputStream (nsIObjectOutputStream* binaryStream,
198 nsTHashtable<nsISupportsHashKey>* objectMap)
199 : mBinaryStream(binaryStream), mObjectMap(objectMap) { }
201 NS_FORWARD_SAFE_NSIBINARYOUTPUTSTREAM(mBinaryStream)
202 NS_FORWARD_SAFE_NSIOUTPUTSTREAM(mBinaryStream)
204 bool CheckReferences(nsISupports* aObject);
206 nsCOMPtr<nsIObjectOutputStream> mBinaryStream;
207 nsTHashtable<nsISupportsHashKey> *mObjectMap;
209 #endif // DEBUG
211 // XPCOM wrapper interface provided for tests only.
212 #define NS_STARTUPCACHE_CID \
213 {0xae4505a9, 0x87ab, 0x477c, \
214 {0xb5, 0x77, 0xf9, 0x23, 0x57, 0xed, 0xa8, 0x84}}
215 // contract id: "@mozilla.org/startupcache/cache;1"
217 class StartupCacheWrapper MOZ_FINAL
218 : public nsIStartupCache
220 ~StartupCacheWrapper() {}
222 NS_DECL_THREADSAFE_ISUPPORTS
223 NS_DECL_NSISTARTUPCACHE
225 static StartupCacheWrapper* GetSingleton();
226 static StartupCacheWrapper *gStartupCacheWrapper;
229 } // namespace scache
230 } // namespace mozilla
231 #endif //StartupCache_h_