1 : /* -*- Mode: C++; tab-width: 20; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 : * ***** BEGIN LICENSE BLOCK *****
3 : * Version: MPL 1.1/GPL 2.0/LGPL 2.1
4 : *
5 : * The contents of this file are subject to the Mozilla Public License Version
6 : * 1.1 (the "License"); you may not use this file except in compliance with
7 : * the License. You may obtain a copy of the License at
8 : * http://www.mozilla.org/MPL/
9 : *
10 : * Software distributed under the License is distributed on an "AS IS" basis,
11 : * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 : * for the specific language governing rights and limitations under the
13 : * License.
14 : *
15 : * The Original Code is Mozilla Corporation code.
16 : *
17 : * The Initial Developer of the Original Code is Mozilla Foundation.
18 : * Portions created by the Initial Developer are Copyright (C) 2010
19 : * the Initial Developer. All Rights Reserved.
20 : *
21 : * Contributor(s):
22 : * Robert O'Callahan <robert@ocallahan.org>
23 : *
24 : * Alternatively, the contents of this file may be used under the terms of
25 : * either the GNU General Public License Version 2 or later (the "GPL"), or
26 : * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
27 : * in which case the provisions of the GPL or the LGPL are applicable instead
28 : * of those above. If you wish to allow use of your version of this file only
29 : * under the terms of either the GPL or the LGPL, and not to allow others to
30 : * use your version of this file under the terms of the MPL, indicate your
31 : * decision by deleting the provisions above and replace them with the notice
32 : * and other provisions required by the GPL or the LGPL. If you do not delete
33 : * the provisions above, a recipient may use your version of this file under
34 : * the terms of any one of the MPL, the GPL or the LGPL.
35 : *
36 : * ***** END LICENSE BLOCK ***** */
37 :
38 : #ifndef FRAMEPROPERTYTABLE_H_
39 : #define FRAMEPROPERTYTABLE_H_
40 :
41 : #include "nsTHashtable.h"
42 : #include "nsHashKeys.h"
43 :
44 : class nsIFrame;
45 :
46 : namespace mozilla {
47 :
48 : struct FramePropertyDescriptor;
49 :
50 : typedef void (*FramePropertyDestructor)(void* aPropertyValue);
51 : typedef void (*FramePropertyDestructorWithFrame)(nsIFrame* aFrame,
52 : void* aPropertyValue);
53 :
54 : /**
55 : * A pointer to a FramePropertyDescriptor serves as a unique property ID.
56 : * The FramePropertyDescriptor stores metadata about the property.
57 : * Currently the only metadata is a destructor function. The destructor
58 : * function is called on property values when they are overwritten or
59 : * deleted.
60 : *
61 : * To use this class, declare a global (i.e., file, class or function-scope
62 : * static member) FramePropertyDescriptor and pass its address as
63 : * aProperty in the FramePropertyTable methods.
64 : */
65 : struct FramePropertyDescriptor {
66 : /**
67 : * mDestructor will be called if it's non-null.
68 : */
69 : FramePropertyDestructor mDestructor;
70 : /**
71 : * mDestructorWithFrame will be called if it's non-null and mDestructor
72 : * is null. WARNING: The frame passed to mDestructorWithFrame may
73 : * be a dangling frame pointer, if this is being called during
74 : * presshell teardown. Do not use it except to compare against
75 : * other frame pointers. No frame will have been allocated with
76 : * the same address yet.
77 : */
78 : FramePropertyDestructorWithFrame mDestructorWithFrame;
79 : /**
80 : * mDestructor and mDestructorWithFrame may both be null, in which case
81 : * no value destruction is a no-op.
82 : */
83 : };
84 :
85 : /**
86 : * The FramePropertyTable is optimized for storing 0 or 1 properties on
87 : * a given frame. Storing very large numbers of properties on a single
88 : * frame will not be efficient.
89 : *
90 : * Property values are passed as void* but do not actually have to be
91 : * valid pointers. You can use NS_INT32_TO_PTR/NS_PTR_TO_INT32 to
92 : * store PRInt32 values. Null/zero values can be stored and retrieved.
93 : * Of course, the destructor function (if any) must handle such values
94 : * correctly.
95 : */
96 : class FramePropertyTable {
97 : public:
98 0 : FramePropertyTable() : mLastFrame(nsnull), mLastEntry(nsnull)
99 : {
100 0 : mEntries.Init();
101 0 : }
102 0 : ~FramePropertyTable()
103 0 : {
104 0 : DeleteAll();
105 0 : }
106 :
107 : /**
108 : * Set a property value on a frame. This requires one hashtable
109 : * lookup (using the frame as the key) and a linear search through
110 : * the properties of that frame. Any existing value for the property
111 : * is destroyed.
112 : */
113 : void Set(nsIFrame* aFrame, const FramePropertyDescriptor* aProperty,
114 : void* aValue);
115 : /**
116 : * Get a property value for a frame. This requires one hashtable
117 : * lookup (using the frame as the key) and a linear search through
118 : * the properties of that frame. If the frame has no such property,
119 : * returns null.
120 : * @param aFoundResult if non-null, receives a value 'true' iff
121 : * the frame has a value for the property. This lets callers
122 : * disambiguate a null result, which can mean 'no such property' or
123 : * 'property value is null'.
124 : */
125 : void* Get(const nsIFrame* aFrame, const FramePropertyDescriptor* aProperty,
126 : bool* aFoundResult = nsnull);
127 : /**
128 : * Remove a property value for a frame. This requires one hashtable
129 : * lookup (using the frame as the key) and a linear search through
130 : * the properties of that frame. The old property value is returned
131 : * (and not destroyed). If the frame has no such property,
132 : * returns null.
133 : * @param aFoundResult if non-null, receives a value 'true' iff
134 : * the frame had a value for the property. This lets callers
135 : * disambiguate a null result, which can mean 'no such property' or
136 : * 'property value is null'.
137 : */
138 : void* Remove(nsIFrame* aFrame, const FramePropertyDescriptor* aProperty,
139 : bool* aFoundResult = nsnull);
140 : /**
141 : * Remove and destroy a property value for a frame. This requires one
142 : * hashtable lookup (using the frame as the key) and a linear search
143 : * through the properties of that frame. If the frame has no such
144 : * property, nothing happens.
145 : */
146 : void Delete(nsIFrame* aFrame, const FramePropertyDescriptor* aProperty);
147 : /**
148 : * Remove and destroy all property values for a frame. This requires one
149 : * hashtable lookup (using the frame as the key).
150 : */
151 : void DeleteAllFor(nsIFrame* aFrame);
152 : /**
153 : * Remove and destroy all property values for all frames.
154 : */
155 : void DeleteAll();
156 :
157 : size_t SizeOfExcludingThis(nsMallocSizeOfFun aMallocSizeOf) const;
158 :
159 : protected:
160 : /**
161 : * Stores a property descriptor/value pair. It can also be used to
162 : * store an nsTArray of PropertyValues.
163 : */
164 0 : struct PropertyValue {
165 0 : PropertyValue() : mProperty(nsnull), mValue(nsnull) {}
166 0 : PropertyValue(const FramePropertyDescriptor* aProperty, void* aValue)
167 0 : : mProperty(aProperty), mValue(aValue) {}
168 :
169 0 : bool IsArray() { return !mProperty && mValue; }
170 0 : nsTArray<PropertyValue>* ToArray()
171 : {
172 0 : NS_ASSERTION(IsArray(), "Must be array");
173 0 : return reinterpret_cast<nsTArray<PropertyValue>*>(&mValue);
174 : }
175 :
176 0 : void DestroyValueFor(nsIFrame* aFrame) {
177 0 : if (mProperty->mDestructor) {
178 0 : mProperty->mDestructor(mValue);
179 0 : } else if (mProperty->mDestructorWithFrame) {
180 0 : mProperty->mDestructorWithFrame(aFrame, mValue);
181 : }
182 0 : }
183 :
184 0 : size_t SizeOfExcludingThis(nsMallocSizeOfFun aMallocSizeOf) {
185 0 : size_t n = 0;
186 : // We don't need to measure mProperty because it always points to static
187 : // memory. As for mValue: if it's a single value we can't measure it,
188 : // because the type is opaque; if it's an array, we measure the array
189 : // storage, but we can't measure the individual values, again because
190 : // their types are opaque.
191 0 : if (IsArray()) {
192 0 : nsTArray<PropertyValue>* array = ToArray();
193 0 : n += array->SizeOfExcludingThis(aMallocSizeOf);
194 : }
195 0 : return n;
196 : }
197 :
198 : const FramePropertyDescriptor* mProperty;
199 : void* mValue;
200 : };
201 :
202 : /**
203 : * Used with an array of PropertyValues to allow lookups that compare
204 : * only on the FramePropertyDescriptor.
205 : */
206 : class PropertyComparator {
207 : public:
208 : bool Equals(const PropertyValue& a, const PropertyValue& b) const {
209 : return a.mProperty == b.mProperty;
210 : }
211 : bool Equals(const FramePropertyDescriptor* a, const PropertyValue& b) const {
212 : return a == b.mProperty;
213 : }
214 0 : bool Equals(const PropertyValue& a, const FramePropertyDescriptor* b) const {
215 0 : return a.mProperty == b;
216 : }
217 : };
218 :
219 : /**
220 : * Our hashtable entry. The key is an nsIFrame*, the value is a
221 : * PropertyValue representing one or more property/value pairs.
222 : */
223 : class Entry : public nsPtrHashKey<nsIFrame>
224 0 : {
225 : public:
226 0 : Entry(KeyTypePointer aKey) : nsPtrHashKey<nsIFrame>(aKey) {}
227 : Entry(const Entry &toCopy) :
228 : nsPtrHashKey<nsIFrame>(toCopy), mProp(toCopy.mProp) {}
229 :
230 : PropertyValue mProp;
231 : };
232 :
233 : static void DeleteAllForEntry(Entry* aEntry);
234 : static PLDHashOperator DeleteEnumerator(Entry* aEntry, void* aArg);
235 :
236 : static size_t SizeOfPropertyTableEntryExcludingThis(Entry* aEntry,
237 : nsMallocSizeOfFun aMallocSizeOf, void *);
238 :
239 : nsTHashtable<Entry> mEntries;
240 : nsIFrame* mLastFrame;
241 : Entry* mLastEntry;
242 : };
243 :
244 : /**
245 : * This class encapsulates the properties of a frame.
246 : */
247 : class FrameProperties {
248 : public:
249 0 : FrameProperties(FramePropertyTable* aTable, nsIFrame* aFrame)
250 0 : : mTable(aTable), mFrame(aFrame) {}
251 0 : FrameProperties(FramePropertyTable* aTable, const nsIFrame* aFrame)
252 0 : : mTable(aTable), mFrame(const_cast<nsIFrame*>(aFrame)) {}
253 :
254 0 : void Set(const FramePropertyDescriptor* aProperty, void* aValue) const
255 : {
256 0 : mTable->Set(mFrame, aProperty, aValue);
257 0 : }
258 0 : void* Get(const FramePropertyDescriptor* aProperty,
259 : bool* aFoundResult = nsnull) const
260 : {
261 0 : return mTable->Get(mFrame, aProperty, aFoundResult);
262 : }
263 0 : void* Remove(const FramePropertyDescriptor* aProperty,
264 : bool* aFoundResult = nsnull) const
265 : {
266 0 : return mTable->Remove(mFrame, aProperty, aFoundResult);
267 : }
268 0 : void Delete(const FramePropertyDescriptor* aProperty)
269 : {
270 0 : mTable->Delete(mFrame, aProperty);
271 0 : }
272 :
273 : private:
274 : FramePropertyTable* mTable;
275 : nsIFrame* mFrame;
276 : };
277 :
278 : }
279 :
280 : #endif /* FRAMEPROPERTYTABLE_H_ */
|