Bug 1936278 - Prevent search mode chiclet from being dismissed when clicking in page...
[gecko.git] / dom / svg / DOMSVGAnimatedLengthList.h
blob04551a41b27b001a24aa201d575c3cfdd6581571
1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
3 /* This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7 #ifndef DOM_SVG_DOMSVGANIMATEDLENGTHLIST_H_
8 #define DOM_SVG_DOMSVGANIMATEDLENGTHLIST_H_
10 #include "nsCycleCollectionParticipant.h"
11 #include "SVGElement.h"
12 #include "mozilla/Attributes.h"
13 #include "mozilla/RefPtr.h"
15 namespace mozilla {
17 class SVGAnimatedLengthList;
18 class SVGLengthList;
20 namespace dom {
22 class DOMSVGLengthList;
24 /**
25 * Class DOMSVGAnimatedLengthList
27 * This class is used to create the DOM tearoff objects that wrap internal
28 * SVGAnimatedLengthList objects. We have this internal-DOM split because DOM
29 * classes are relatively heavy-weight objects with non-optimal interfaces for
30 * internal code, and they're relatively infrequently used. Having separate
31 * internal and DOM classes does add complexity - especially for lists where
32 * the internal list and DOM lists (and their items) need to be kept in sync -
33 * but it keeps the internal classes light and fast, and in 99% of cases
34 * they're all that's used. DOM wrappers are only instantiated when script
35 * demands it.
37 * Ownership model:
39 * The diagram below shows the ownership model between the various DOM objects
40 * in the tree of DOM objects that correspond to an SVG length list attribute.
41 * The angled brackets ">" and "<" denote a reference from one object to
42 * another, where the "!" character denotes a strong reference, and the "~"
43 * character denotes a weak reference.
45 * .----<!----. .----<!----. .----<!----.
46 * | | | | | |
47 * element ~> DOMSVGAnimatedLengthList ~> DOMSVGLengthList ~> DOMSVGLength
49 * Rationale:
51 * The following three paragraphs explain the main three requirements that must
52 * be met by any design. These are followed by an explanation of the rationale
53 * behind our particular design.
55 * 1: DOMSVGAnimatedLengthList, DOMSVGLengthLists and DOMSVGLength get to their
56 * internal counterparts via their element, and they use their element to send
57 * out appropriate notifications when they change. Because of this, having
58 * their element disappear out from under them would be very bad. To keep their
59 * element alive at least as long as themselves, each of these classes must
60 * contain a _strong_ reference (directly or indirectly) to their element.
62 * 2: Another central requirement of any design is the SVG specification's
63 * requirement that script must always be given the exact same objects each
64 * time it accesses a given object in a DOM object tree corresponding to an SVG
65 * length list attribute. In practice "always" actually means "whenever script
66 * has kept a references to a DOM object it previously accessed", since a
67 * script will only be able to detect any difference in object identity if it
68 * has a previous reference to compare against.
70 * 3: The wiggle room in the "same object" requirement leads us to a third
71 * (self imposed) requirement: if script no longer has a reference to a given
72 * DOM object from an object tree corresponding to an SVG length list
73 * attribute, and if that object doesn't currently have any descendants, then
74 * that object should be released to free up memory.
76 * To help in understanding our current design, consider this BROKEN design:
78 * .-------------------------------<!-------------------------.
79 * |--------------------<!----------------. |
80 * |----<!----. | |
81 * | | | |
82 * element ~> DOMSVGAnimatedLengthList !> DOMSVGLengthList !> DOMSVGLength
84 * Having all the objects keep a reference directly to their element like this
85 * would reduce the number of dereferences that they need to make to get their
86 * internal counterpart. However, this design does not meet the "same object"
87 * requirement of the SVG specification. If script keeps a reference to a
88 * DOMSVGLength or DOMSVGLengthList object, but not to that object's
89 * DOMSVGAnimatedLengthList, then the DOMSVGAnimatedLengthList may be garbage
90 * collected. We'd then have no way to return the same DOMSVGLength /
91 * DOMSVGLengthList object that the script has a reference to if the script
92 * went looking for it via the DOMSVGAnimatedLengthList property on the
93 * element - we'd end up creating a fresh DOMSVGAnimatedLengthList, with no
94 * knowlegde of the existing DOMSVGLengthList or DOMSVGLength object.
96 * The way we solve this problem is by making sure that parent objects cannot
97 * die until all their children are dead by having child objects hold a strong
98 * reference to their parent object. Note that this design means that the child
99 * objects hold a strong reference to their element too, albeit indirectly via
100 * the strong reference to their parent object:
102 * .----<!----. .----<!----. .----<!----.
103 * | | | | | |
104 * element ~> DOMSVGAnimatedLengthList ~> DOMSVGLengthList ~> DOMSVGLength
106 * One drawback of this design is that objects must look up their parent
107 * chain to find their element, but that overhead is relatively small.
109 class DOMSVGAnimatedLengthList final : public nsWrapperCache {
110 friend class DOMSVGLengthList;
112 public:
113 NS_INLINE_DECL_CYCLE_COLLECTING_NATIVE_REFCOUNTING(DOMSVGAnimatedLengthList)
114 NS_DECL_CYCLE_COLLECTION_SCRIPT_HOLDER_NATIVE_CLASS(DOMSVGAnimatedLengthList)
117 * Factory method to create and return a DOMSVGAnimatedLengthList wrapper
118 * for a given internal SVGAnimatedLengthList object. The factory takes care
119 * of caching the object that it returns so that the same object can be
120 * returned for the given SVGAnimatedLengthList each time it is requested.
121 * The cached object is only removed from the cache when it is destroyed due
122 * to there being no more references to it or to any of its descendant
123 * objects. If that happens, any subsequent call requesting the DOM wrapper
124 * for the SVGAnimatedLengthList will naturally result in a new
125 * DOMSVGAnimatedLengthList being returned.
127 static already_AddRefed<DOMSVGAnimatedLengthList> GetDOMWrapper(
128 SVGAnimatedLengthList* aList, dom::SVGElement* aElement,
129 uint8_t aAttrEnum, uint8_t aAxis);
132 * This method returns the DOMSVGAnimatedLengthList wrapper for an internal
133 * SVGAnimatedLengthList object if it currently has a wrapper. If it does
134 * not, then nullptr is returned.
136 static DOMSVGAnimatedLengthList* GetDOMWrapperIfExists(
137 SVGAnimatedLengthList* aList);
140 * Called by internal code to notify us when we need to sync the length of
141 * our baseVal DOM list with its internal list. This is called just prior to
142 * the length of the internal baseVal list being changed so that any DOM list
143 * items that need to be removed from the DOM list can first get their values
144 * from their internal counterpart.
146 * The only time this method could fail is on OOM when trying to increase the
147 * length of the DOM list. If that happens then this method simply clears the
148 * list and returns. Callers just proceed as normal, and we simply accept
149 * that the DOM list will be empty (until successfully set to a new value).
151 void InternalBaseValListWillChangeTo(const SVGLengthList& aNewValue);
152 void InternalAnimValListWillChangeTo(const SVGLengthList& aNewValue);
155 * Returns true if our attribute is animating (in which case our animVal is
156 * not simply a mirror of our baseVal).
158 bool IsAnimating() const;
160 // WebIDL
161 dom::SVGElement* GetParentObject() const { return mElement; }
162 JSObject* WrapObject(JSContext* aCx,
163 JS::Handle<JSObject*> aGivenProto) override;
164 // These aren't weak refs because mBaseVal and mAnimVal are weak
165 already_AddRefed<DOMSVGLengthList> BaseVal();
166 already_AddRefed<DOMSVGLengthList> AnimVal();
168 private:
170 * Only our static GetDOMWrapper() factory method may create objects of our
171 * type.
173 DOMSVGAnimatedLengthList(dom::SVGElement* aElement, uint8_t aAttrEnum,
174 uint8_t aAxis)
175 : mBaseVal(nullptr),
176 mAnimVal(nullptr),
177 mElement(aElement),
178 mAttrEnum(aAttrEnum),
179 mAxis(aAxis) {}
181 ~DOMSVGAnimatedLengthList();
183 /// Get a reference to this DOM wrapper object's internal counterpart.
184 SVGAnimatedLengthList& InternalAList();
185 const SVGAnimatedLengthList& InternalAList() const;
187 // Weak refs to our DOMSVGLengthList baseVal/animVal objects. These objects
188 // are friends and take care of clearing these pointers when they die, making
189 // these true weak references.
190 DOMSVGLengthList* mBaseVal;
191 DOMSVGLengthList* mAnimVal;
193 // Strong ref to our element to keep it alive. We hold this not only for
194 // ourself, but also for our base/animVal and all of their items.
195 RefPtr<dom::SVGElement> mElement;
197 uint8_t mAttrEnum;
198 uint8_t mAxis;
201 } // namespace dom
202 } // namespace mozilla
204 #endif // DOM_SVG_DOMSVGANIMATEDLENGTHLIST_H_