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_
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"
20 #include "nsIObserverService.h"
21 #include "nsIObserver.h"
22 #include "nsIOutputStream.h"
24 #include "mozilla/Attributes.h"
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.
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.
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
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 * Finally, getDebugObjectOutputStream() allows debug code to wrap an objectstream
48 * with a debug objectstream, to check for multiply-referenced objects. These will
49 * generally fail to deserialize correctly, unless they are stateless singletons or the
50 * client maintains their own object data map for deserialization.
52 * Writes before the final-ui-startup notification are placed in an intermediate
53 * cache in memory, then written out to disk at a later time, to get writes off the
54 * startup path. In any case, clients should not rely on being able to GetBuffer()
55 * data that is written to the cache, since it may not have been written to disk or
56 * another client may have invalidated the cache. In other words, it should be used as
57 * a cache only, and not a reliable persistent store.
59 * Some utility functions are provided in StartupCacheUtils. These functions wrap the
60 * buffers into object streams, which may be useful for serializing objects. Note
61 * the above caution about multiply-referenced objects, though -- the streams are just
62 * as 'dumb' as the underlying buffers about multiply-referenced objects. They just
63 * provide some convenience in writing out data.
66 class nsIMemoryReporter
;
73 nsAutoArrayPtr
<char> data
;
76 CacheEntry() : data(nullptr), size(0) { }
78 // Takes possession of buf
79 CacheEntry(char* buf
, PRUint32 len
) : data(buf
), size(len
) { }
85 size_t SizeOfExcludingThis(nsMallocSizeOfFun mallocSizeOf
) {
86 return mallocSizeOf(data
);
90 // We don't want to refcount StartupCache, and ObserverService wants to
91 // refcount its listeners, so we'll let it refcount this instead.
92 class StartupCacheListener MOZ_FINAL
: public nsIObserver
101 friend class StartupCacheListener
;
102 friend class StartupCacheWrapper
;
106 // StartupCache methods. See above comments for a more detailed description.
108 // Returns a buffer that was previously stored, caller takes ownership.
109 nsresult
GetBuffer(const char* id
, char** outbuf
, PRUint32
* length
);
111 // Stores a buffer. Caller keeps ownership, we make a copy.
112 nsresult
PutBuffer(const char* id
, const char* inbuf
, PRUint32 length
);
114 // Removes the cache file.
115 void InvalidateCache();
117 // In DEBUG builds, returns a stream that will attempt to check for
118 // and disallow multiple writes of the same object.
119 nsresult
GetDebugObjectOutputStream(nsIObjectOutputStream
* aStream
,
120 nsIObjectOutputStream
** outStream
);
122 nsresult
RecordAgesAlways();
124 static StartupCache
* GetSingleton();
125 static void DeleteSingleton();
127 // This measures all the heap memory used by the StartupCache, i.e. it
128 // excludes the mapping.
129 size_t HeapSizeOfIncludingThis(nsMallocSizeOfFun mallocSizeOf
);
131 size_t SizeOfMapping();
137 enum TelemetrifyAge
{
141 static enum TelemetrifyAge gPostFlushAgeAction
;
143 nsresult
LoadArchive(enum TelemetrifyAge flag
);
146 nsresult
ResetStartupWriteTimer();
147 void WaitOnWriteThread();
149 static nsresult
InitSingleton();
150 static void WriteTimeout(nsITimer
*aTimer
, void *aClosure
);
151 static void ThreadedWrite(void *aClosure
);
153 static size_t SizeOfEntryExcludingThis(const nsACString
& key
,
154 const nsAutoPtr
<CacheEntry
>& data
,
155 nsMallocSizeOfFun mallocSizeOf
,
158 nsClassHashtable
<nsCStringHashKey
, CacheEntry
> mTable
;
159 nsRefPtr
<nsZipArchive
> mArchive
;
160 nsCOMPtr
<nsIFile
> mFile
;
162 nsCOMPtr
<nsIObserverService
> mObserverService
;
163 nsRefPtr
<StartupCacheListener
> mListener
;
164 nsCOMPtr
<nsITimer
> mTimer
;
166 bool mStartupWriteInitiated
;
168 static StartupCache
*gStartupCache
;
169 static bool gShutdownInitiated
;
170 PRThread
*mWriteThread
;
172 nsTHashtable
<nsISupportsHashKey
> mWriteObjectMap
;
175 nsIMemoryReporter
* mMappingMemoryReporter
;
176 nsIMemoryReporter
* mDataMemoryReporter
;
179 // This debug outputstream attempts to detect if clients are writing multiple
180 // references to the same object. We only support that if that object
183 class StartupCacheDebugOutputStream MOZ_FINAL
184 : public nsIObjectOutputStream
187 NS_DECL_NSIOBJECTOUTPUTSTREAM
189 StartupCacheDebugOutputStream (nsIObjectOutputStream
* binaryStream
,
190 nsTHashtable
<nsISupportsHashKey
>* objectMap
)
191 : mBinaryStream(binaryStream
), mObjectMap(objectMap
) { }
193 NS_FORWARD_SAFE_NSIBINARYOUTPUTSTREAM(mBinaryStream
)
194 NS_FORWARD_SAFE_NSIOUTPUTSTREAM(mBinaryStream
)
196 bool CheckReferences(nsISupports
* aObject
);
198 nsCOMPtr
<nsIObjectOutputStream
> mBinaryStream
;
199 nsTHashtable
<nsISupportsHashKey
> *mObjectMap
;
203 // XPCOM wrapper interface provided for tests only.
204 #define NS_STARTUPCACHE_CID \
205 {0xae4505a9, 0x87ab, 0x477c, \
206 {0xb5, 0x77, 0xf9, 0x23, 0x57, 0xed, 0xa8, 0x84}}
207 // contract id: "@mozilla.org/startupcache/cache;1"
209 class StartupCacheWrapper MOZ_FINAL
210 : public nsIStartupCache
213 NS_DECL_NSISTARTUPCACHE
215 static StartupCacheWrapper
* GetSingleton();
216 static StartupCacheWrapper
*gStartupCacheWrapper
;
219 } // namespace scache
220 } // namespace mozilla
221 #endif //StartupCache_h_