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