/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ /* vim: set ts=8 sts=2 et sw=2 tw=80: */ /* This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ #ifndef MOZILLA_DOMSVGANIMATEDLENGTHLIST_H__ #define MOZILLA_DOMSVGANIMATEDLENGTHLIST_H__ #include "nsCOMPtr.h" #include "nsCycleCollectionParticipant.h" #include "nsSVGElement.h" #include "mozilla/Attributes.h" namespace mozilla { class SVGAnimatedLengthList; class SVGLengthList; class DOMSVGLengthList; /** * Class DOMSVGAnimatedLengthList * * This class is used to create the DOM tearoff objects that wrap internal * SVGAnimatedLengthList objects. We have this internal-DOM split because DOM * classes are relatively heavy-weight objects with non-optimal interfaces for * internal code, and they're relatively infrequently used. Having separate * internal and DOM classes does add complexity - especially for lists where * the internal list and DOM lists (and their items) need to be kept in sync - * but it keeps the internal classes light and fast, and in 99% of cases * they're all that's used. DOM wrappers are only instantiated when script * demands it. * * Ownership model: * * The diagram below shows the ownership model between the various DOM objects * in the tree of DOM objects that correspond to an SVG length list attribute. * The angled brackets ">" and "<" denote a reference from one object to * another, where the "!" character denotes a strong reference, and the "~" * character denotes a weak reference. * * .----<!----. .----<!----. .----<!----. * | | | | | | * element ~> DOMSVGAnimatedLengthList ~> DOMSVGLengthList ~> DOMSVGLength * * Rationale: * * The following three paragraphs explain the main three requirements that must * be met by any design. These are followed by an explanation of the rationale * behind our particular design. * * 1: DOMSVGAnimatedLengthList, DOMSVGLengthLists and DOMSVGLength get to their * internal counterparts via their element, and they use their element to send * out appropriate notifications when they change. Because of this, having * their element disappear out from under them would be very bad. To keep their * element alive at least as long as themselves, each of these classes must * contain a _strong_ reference (directly or indirectly) to their element. * * 2: Another central requirement of any design is the SVG specification's * requirement that script must always be given the exact same objects each * time it accesses a given object in a DOM object tree corresponding to an SVG * length list attribute. In practice "always" actually means "whenever script * has kept a references to a DOM object it previously accessed", since a * script will only be able to detect any difference in object identity if it * has a previous reference to compare against. * * 3: The wiggle room in the "same object" requirement leads us to a third * (self imposed) requirement: if script no longer has a reference to a given * DOM object from an object tree corresponding to an SVG length list * attribute, and if that object doesn't currently have any descendants, then * that object should be released to free up memory. * * To help in understanding our current design, consider this BROKEN design: * * .-------------------------------<!-------------------------. * |--------------------<!----------------. | * |----<!----. | | * | | | | * element ~> DOMSVGAnimatedLengthList !> DOMSVGLengthList !> DOMSVGLength * * Having all the objects keep a reference directly to their element like this * would reduce the number of dereferences that they need to make to get their * internal counterpart. Hovewer, this design does not meet the "same object" * requirement of the SVG specification. If script keeps a reference to a * DOMSVGLength or DOMSVGLengthList object, but not to that object's * DOMSVGAnimatedLengthList, then the DOMSVGAnimatedLengthList may be garbage * collected. We'd then have no way to return the same DOMSVGLength / * DOMSVGLengthList object that the script has a reference to if the script * went looking for it via the DOMSVGAnimatedLengthList property on the * element - we'd end up creating a fresh DOMSVGAnimatedLengthList, with no * knowlegde of the existing DOMSVGLengthList or DOMSVGLength object. * * The way we solve this problem is by making sure that parent objects cannot * die until all their children are dead by having child objects hold a strong * reference to their parent object. Note that this design means that the child * objects hold a strong reference to their element too, albeit indirectly via * the strong reference to their parent object: * * .----<!----. .----<!----. .----<!----. * | | | | | | * element ~> DOMSVGAnimatedLengthList ~> DOMSVGLengthList ~> DOMSVGLength * * One drawback of this design is that objects must look up their parent * chain to find their element, but that overhead is relatively small. */ class DOMSVGAnimatedLengthList final : public nsWrapperCache { friend class DOMSVGLengthList; public: NS_INLINE_DECL_CYCLE_COLLECTING_NATIVE_REFCOUNTING(DOMSVGAnimatedLengthList) NS_DECL_CYCLE_COLLECTION_SCRIPT_HOLDER_NATIVE_CLASS(DOMSVGAnimatedLengthList) /** * Factory method to create and return a DOMSVGAnimatedLengthList wrapper * for a given internal SVGAnimatedLengthList object. The factory takes care * of caching the object that it returns so that the same object can be * returned for the given SVGAnimatedLengthList each time it is requested. * The cached object is only removed from the cache when it is destroyed due * to there being no more references to it or to any of its descendant * objects. If that happens, any subsequent call requesting the DOM wrapper * for the SVGAnimatedLengthList will naturally result in a new * DOMSVGAnimatedLengthList being returned. */ static already_AddRefed<DOMSVGAnimatedLengthList> GetDOMWrapper(SVGAnimatedLengthList *aList, nsSVGElement *aElement, uint8_t aAttrEnum, uint8_t aAxis); /** * This method returns the DOMSVGAnimatedLengthList wrapper for an internal * SVGAnimatedLengthList object if it currently has a wrapper. If it does * not, then nullptr is returned. */ static DOMSVGAnimatedLengthList* GetDOMWrapperIfExists(SVGAnimatedLengthList *aList); /** * Called by internal code to notify us when we need to sync the length of * our baseVal DOM list with its internal list. This is called just prior to * the length of the internal baseVal list being changed so that any DOM list * items that need to be removed from the DOM list can first get their values * from their internal counterpart. * * The only time this method could fail is on OOM when trying to increase the * length of the DOM list. If that happens then this method simply clears the * list and returns. Callers just proceed as normal, and we simply accept * that the DOM list will be empty (until successfully set to a new value). */ void InternalBaseValListWillChangeTo(const SVGLengthList& aNewValue); void InternalAnimValListWillChangeTo(const SVGLengthList& aNewValue); /** * Returns true if our attribute is animating (in which case our animVal is * not simply a mirror of our baseVal). */ bool IsAnimating() const; // WebIDL nsSVGElement* GetParentObject() const { return mElement; } virtual JSObject* WrapObject(JSContext* aCx, JS::Handle<JSObject*> aGivenProto) override; // These aren't weak refs because mBaseVal and mAnimVal are weak already_AddRefed<DOMSVGLengthList> BaseVal(); already_AddRefed<DOMSVGLengthList> AnimVal(); private: /** * Only our static GetDOMWrapper() factory method may create objects of our * type. */ DOMSVGAnimatedLengthList(nsSVGElement *aElement, uint8_t aAttrEnum, uint8_t aAxis) : mBaseVal(nullptr) , mAnimVal(nullptr) , mElement(aElement) , mAttrEnum(aAttrEnum) , mAxis(aAxis) { } ~DOMSVGAnimatedLengthList(); /// Get a reference to this DOM wrapper object's internal counterpart. SVGAnimatedLengthList& InternalAList(); const SVGAnimatedLengthList& InternalAList() const; // Weak refs to our DOMSVGLengthList baseVal/animVal objects. These objects // are friends and take care of clearing these pointers when they die, making // these true weak references. DOMSVGLengthList *mBaseVal; DOMSVGLengthList *mAnimVal; // Strong ref to our element to keep it alive. We hold this not only for // ourself, but also for our base/animVal and all of their items. RefPtr<nsSVGElement> mElement; uint8_t mAttrEnum; uint8_t mAxis; }; } // namespace mozilla #endif // MOZILLA_DOMSVGANIMATEDLENGTHLIST_H__