diff options
Diffstat (limited to 'js/public/RootingAPI.h')
| -rw-r--r-- | js/public/RootingAPI.h | 1330 |
1 files changed, 1330 insertions, 0 deletions
diff --git a/js/public/RootingAPI.h b/js/public/RootingAPI.h new file mode 100644 index 000000000..9f6ed8943 --- /dev/null +++ b/js/public/RootingAPI.h @@ -0,0 +1,1330 @@ +/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- + * vim: set ts=8 sts=4 et sw=4 tw=99: + * 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 js_RootingAPI_h +#define js_RootingAPI_h + +#include "mozilla/Attributes.h" +#include "mozilla/DebugOnly.h" +#include "mozilla/GuardObjects.h" +#include "mozilla/LinkedList.h" +#include "mozilla/Move.h" +#include "mozilla/TypeTraits.h" + +#include <type_traits> + +#include "jspubtd.h" + +#include "js/GCAnnotations.h" +#include "js/GCAPI.h" +#include "js/GCPolicyAPI.h" +#include "js/HeapAPI.h" +#include "js/TypeDecls.h" +#include "js/UniquePtr.h" +#include "js/Utility.h" + +/* + * Moving GC Stack Rooting + * + * A moving GC may change the physical location of GC allocated things, even + * when they are rooted, updating all pointers to the thing to refer to its new + * location. The GC must therefore know about all live pointers to a thing, + * not just one of them, in order to behave correctly. + * + * The |Rooted| and |Handle| classes below are used to root stack locations + * whose value may be held live across a call that can trigger GC. For a + * code fragment such as: + * + * JSObject* obj = NewObject(cx); + * DoSomething(cx); + * ... = obj->lastProperty(); + * + * If |DoSomething()| can trigger a GC, the stack location of |obj| must be + * rooted to ensure that the GC does not move the JSObject referred to by + * |obj| without updating |obj|'s location itself. This rooting must happen + * regardless of whether there are other roots which ensure that the object + * itself will not be collected. + * + * If |DoSomething()| cannot trigger a GC, and the same holds for all other + * calls made between |obj|'s definitions and its last uses, then no rooting + * is required. + * + * SpiderMonkey can trigger a GC at almost any time and in ways that are not + * always clear. For example, the following innocuous-looking actions can + * cause a GC: allocation of any new GC thing; JSObject::hasProperty; + * JS_ReportError and friends; and ToNumber, among many others. The following + * dangerous-looking actions cannot trigger a GC: js_malloc, cx->malloc_, + * rt->malloc_, and friends and JS_ReportOutOfMemory. + * + * The following family of three classes will exactly root a stack location. + * Incorrect usage of these classes will result in a compile error in almost + * all cases. Therefore, it is very hard to be incorrectly rooted if you use + * these classes exclusively. These classes are all templated on the type T of + * the value being rooted. + * + * - Rooted<T> declares a variable of type T, whose value is always rooted. + * Rooted<T> may be automatically coerced to a Handle<T>, below. Rooted<T> + * should be used whenever a local variable's value may be held live across a + * call which can trigger a GC. + * + * - Handle<T> is a const reference to a Rooted<T>. Functions which take GC + * things or values as arguments and need to root those arguments should + * generally use handles for those arguments and avoid any explicit rooting. + * This has two benefits. First, when several such functions call each other + * then redundant rooting of multiple copies of the GC thing can be avoided. + * Second, if the caller does not pass a rooted value a compile error will be + * generated, which is quicker and easier to fix than when relying on a + * separate rooting analysis. + * + * - MutableHandle<T> is a non-const reference to Rooted<T>. It is used in the + * same way as Handle<T> and includes a |set(const T& v)| method to allow + * updating the value of the referenced Rooted<T>. A MutableHandle<T> can be + * created with an implicit cast from a Rooted<T>*. + * + * In some cases the small performance overhead of exact rooting (measured to + * be a few nanoseconds on desktop) is too much. In these cases, try the + * following: + * + * - Move all Rooted<T> above inner loops: this allows you to re-use the root + * on each iteration of the loop. + * + * - Pass Handle<T> through your hot call stack to avoid re-rooting costs at + * every invocation. + * + * The following diagram explains the list of supported, implicit type + * conversions between classes of this family: + * + * Rooted<T> ----> Handle<T> + * | ^ + * | | + * | | + * +---> MutableHandle<T> + * (via &) + * + * All of these types have an implicit conversion to raw pointers. + */ + +namespace js { + +template <typename T> +struct BarrierMethods { +}; + +template <typename T> +class RootedBase {}; + +template <typename T> +class HandleBase {}; + +template <typename T> +class MutableHandleBase {}; + +template <typename T> +class HeapBase {}; + +// Cannot use FOR_EACH_HEAP_ABLE_GC_POINTER_TYPE, as this would import too many macros into scope +template <typename T> struct IsHeapConstructibleType { static constexpr bool value = false; }; +#define DECLARE_IS_HEAP_CONSTRUCTIBLE_TYPE(T) \ + template <> struct IsHeapConstructibleType<T> { static constexpr bool value = true; }; +FOR_EACH_PUBLIC_GC_POINTER_TYPE(DECLARE_IS_HEAP_CONSTRUCTIBLE_TYPE) +FOR_EACH_PUBLIC_TAGGED_GC_POINTER_TYPE(DECLARE_IS_HEAP_CONSTRUCTIBLE_TYPE) +#undef DECLARE_IS_HEAP_CONSTRUCTIBLE_TYPE + +template <typename T> +class PersistentRootedBase {}; + +static void* const ConstNullValue = nullptr; + +namespace gc { +struct Cell; +template<typename T> +struct PersistentRootedMarker; +} /* namespace gc */ + +#define DECLARE_POINTER_COMPARISON_OPS(T) \ + bool operator==(const T& other) const { return get() == other; } \ + bool operator!=(const T& other) const { return get() != other; } + +// Important: Return a reference so passing a Rooted<T>, etc. to +// something that takes a |const T&| is not a GC hazard. +#define DECLARE_POINTER_CONSTREF_OPS(T) \ + operator const T&() const { return get(); } \ + const T& operator->() const { return get(); } + +// Assignment operators on a base class are hidden by the implicitly defined +// operator= on the derived class. Thus, define the operator= directly on the +// class as we would need to manually pass it through anyway. +#define DECLARE_POINTER_ASSIGN_OPS(Wrapper, T) \ + Wrapper<T>& operator=(const T& p) { \ + set(p); \ + return *this; \ + } \ + Wrapper<T>& operator=(T&& p) { \ + set(mozilla::Move(p)); \ + return *this; \ + } \ + Wrapper<T>& operator=(const Wrapper<T>& other) { \ + set(other.get()); \ + return *this; \ + } \ + +#define DELETE_ASSIGNMENT_OPS(Wrapper, T) \ + template <typename S> Wrapper<T>& operator=(S) = delete; \ + Wrapper<T>& operator=(const Wrapper<T>&) = delete; + +#define DECLARE_NONPOINTER_ACCESSOR_METHODS(ptr) \ + const T* address() const { return &(ptr); } \ + const T& get() const { return (ptr); } \ + +#define DECLARE_NONPOINTER_MUTABLE_ACCESSOR_METHODS(ptr) \ + T* address() { return &(ptr); } \ + T& get() { return (ptr); } \ + +} /* namespace js */ + +namespace JS { + +template <typename T> class Rooted; +template <typename T> class PersistentRooted; + +/* This is exposing internal state of the GC for inlining purposes. */ +JS_FRIEND_API(bool) isGCEnabled(); + +JS_FRIEND_API(void) HeapObjectPostBarrier(JSObject** objp, JSObject* prev, JSObject* next); + +#ifdef JS_DEBUG +/** + * For generational GC, assert that an object is in the tenured generation as + * opposed to being in the nursery. + */ +extern JS_FRIEND_API(void) +AssertGCThingMustBeTenured(JSObject* obj); +extern JS_FRIEND_API(void) +AssertGCThingIsNotAnObjectSubclass(js::gc::Cell* cell); +#else +inline void +AssertGCThingMustBeTenured(JSObject* obj) {} +inline void +AssertGCThingIsNotAnObjectSubclass(js::gc::Cell* cell) {} +#endif + +/** + * The Heap<T> class is a heap-stored reference to a JS GC thing. All members of + * heap classes that refer to GC things should use Heap<T> (or possibly + * TenuredHeap<T>, described below). + * + * Heap<T> is an abstraction that hides some of the complexity required to + * maintain GC invariants for the contained reference. It uses operator + * overloading to provide a normal pointer interface, but notifies the GC every + * time the value it contains is updated. This is necessary for generational GC, + * which keeps track of all pointers into the nursery. + * + * Heap<T> instances must be traced when their containing object is traced to + * keep the pointed-to GC thing alive. + * + * Heap<T> objects should only be used on the heap. GC references stored on the + * C/C++ stack must use Rooted/Handle/MutableHandle instead. + * + * Type T must be a public GC pointer type. + */ +template <typename T> +class MOZ_NON_MEMMOVABLE Heap : public js::HeapBase<T> +{ + // Please note: this can actually also be used by nsXBLMaybeCompiled<T>, for legacy reasons. + static_assert(js::IsHeapConstructibleType<T>::value, + "Type T must be a public GC pointer type"); + public: + Heap() { + static_assert(sizeof(T) == sizeof(Heap<T>), + "Heap<T> must be binary compatible with T."); + init(GCPolicy<T>::initial()); + } + explicit Heap(const T& p) { init(p); } + + /* + * For Heap, move semantics are equivalent to copy semantics. In C++, a + * copy constructor taking const-ref is the way to get a single function + * that will be used for both lvalue and rvalue copies, so we can simply + * omit the rvalue variant. + */ + explicit Heap(const Heap<T>& p) { init(p.ptr); } + + ~Heap() { + post(ptr, GCPolicy<T>::initial()); + } + + DECLARE_POINTER_CONSTREF_OPS(T); + DECLARE_POINTER_ASSIGN_OPS(Heap, T); + + const T* address() const { return &ptr; } + + void exposeToActiveJS() const { + js::BarrierMethods<T>::exposeToJS(ptr); + } + const T& get() const { + exposeToActiveJS(); + return ptr; + } + const T& unbarrieredGet() const { + return ptr; + } + + T* unsafeGet() { return &ptr; } + + explicit operator bool() const { + return bool(js::BarrierMethods<T>::asGCThingOrNull(ptr)); + } + explicit operator bool() { + return bool(js::BarrierMethods<T>::asGCThingOrNull(ptr)); + } + + private: + void init(const T& newPtr) { + ptr = newPtr; + post(GCPolicy<T>::initial(), ptr); + } + + void set(const T& newPtr) { + T tmp = ptr; + ptr = newPtr; + post(tmp, ptr); + } + + void post(const T& prev, const T& next) { + js::BarrierMethods<T>::postBarrier(&ptr, prev, next); + } + + T ptr; +}; + +static MOZ_ALWAYS_INLINE bool +ObjectIsTenured(JSObject* obj) +{ + return !js::gc::IsInsideNursery(reinterpret_cast<js::gc::Cell*>(obj)); +} + +static MOZ_ALWAYS_INLINE bool +ObjectIsTenured(const Heap<JSObject*>& obj) +{ + return ObjectIsTenured(obj.unbarrieredGet()); +} + +static MOZ_ALWAYS_INLINE bool +ObjectIsMarkedGray(JSObject* obj) +{ + auto cell = reinterpret_cast<js::gc::Cell*>(obj); + return js::gc::detail::CellIsMarkedGrayIfKnown(cell); +} + +static MOZ_ALWAYS_INLINE bool +ObjectIsMarkedGray(const JS::Heap<JSObject*>& obj) +{ + return ObjectIsMarkedGray(obj.unbarrieredGet()); +} + +static MOZ_ALWAYS_INLINE bool +ScriptIsMarkedGray(JSScript* script) +{ + auto cell = reinterpret_cast<js::gc::Cell*>(script); + return js::gc::detail::CellIsMarkedGrayIfKnown(cell); +} + +static MOZ_ALWAYS_INLINE bool +ScriptIsMarkedGray(const Heap<JSScript*>& script) +{ + return ScriptIsMarkedGray(script.unbarrieredGet()); +} + +/** + * The TenuredHeap<T> class is similar to the Heap<T> class above in that it + * encapsulates the GC concerns of an on-heap reference to a JS object. However, + * it has two important differences: + * + * 1) Pointers which are statically known to only reference "tenured" objects + * can avoid the extra overhead of SpiderMonkey's write barriers. + * + * 2) Objects in the "tenured" heap have stronger alignment restrictions than + * those in the "nursery", so it is possible to store flags in the lower + * bits of pointers known to be tenured. TenuredHeap wraps a normal tagged + * pointer with a nice API for accessing the flag bits and adds various + * assertions to ensure that it is not mis-used. + * + * GC things are said to be "tenured" when they are located in the long-lived + * heap: e.g. they have gained tenure as an object by surviving past at least + * one GC. For performance, SpiderMonkey allocates some things which are known + * to normally be long lived directly into the tenured generation; for example, + * global objects. Additionally, SpiderMonkey does not visit individual objects + * when deleting non-tenured objects, so object with finalizers are also always + * tenured; for instance, this includes most DOM objects. + * + * The considerations to keep in mind when using a TenuredHeap<T> vs a normal + * Heap<T> are: + * + * - It is invalid for a TenuredHeap<T> to refer to a non-tenured thing. + * - It is however valid for a Heap<T> to refer to a tenured thing. + * - It is not possible to store flag bits in a Heap<T>. + */ +template <typename T> +class TenuredHeap : public js::HeapBase<T> +{ + public: + TenuredHeap() : bits(0) { + static_assert(sizeof(T) == sizeof(TenuredHeap<T>), + "TenuredHeap<T> must be binary compatible with T."); + } + explicit TenuredHeap(T p) : bits(0) { setPtr(p); } + explicit TenuredHeap(const TenuredHeap<T>& p) : bits(0) { setPtr(p.getPtr()); } + + bool operator==(const TenuredHeap<T>& other) { return bits == other.bits; } + bool operator!=(const TenuredHeap<T>& other) { return bits != other.bits; } + + void setPtr(T newPtr) { + MOZ_ASSERT((reinterpret_cast<uintptr_t>(newPtr) & flagsMask) == 0); + if (newPtr) + AssertGCThingMustBeTenured(newPtr); + bits = (bits & flagsMask) | reinterpret_cast<uintptr_t>(newPtr); + } + + void setFlags(uintptr_t flagsToSet) { + MOZ_ASSERT((flagsToSet & ~flagsMask) == 0); + bits |= flagsToSet; + } + + void unsetFlags(uintptr_t flagsToUnset) { + MOZ_ASSERT((flagsToUnset & ~flagsMask) == 0); + bits &= ~flagsToUnset; + } + + bool hasFlag(uintptr_t flag) const { + MOZ_ASSERT((flag & ~flagsMask) == 0); + return (bits & flag) != 0; + } + + T unbarrieredGetPtr() const { return reinterpret_cast<T>(bits & ~flagsMask); } + uintptr_t getFlags() const { return bits & flagsMask; } + + void exposeToActiveJS() const { + js::BarrierMethods<T>::exposeToJS(unbarrieredGetPtr()); + } + T getPtr() const { + exposeToActiveJS(); + return unbarrieredGetPtr(); + } + + operator T() const { return getPtr(); } + T operator->() const { return getPtr(); } + + explicit operator bool() const { + return bool(js::BarrierMethods<T>::asGCThingOrNull(unbarrieredGetPtr())); + } + explicit operator bool() { + return bool(js::BarrierMethods<T>::asGCThingOrNull(unbarrieredGetPtr())); + } + + TenuredHeap<T>& operator=(T p) { + setPtr(p); + return *this; + } + + TenuredHeap<T>& operator=(const TenuredHeap<T>& other) { + bits = other.bits; + return *this; + } + + private: + enum { + maskBits = 3, + flagsMask = (1 << maskBits) - 1, + }; + + uintptr_t bits; +}; + +/** + * Reference to a T that has been rooted elsewhere. This is most useful + * as a parameter type, which guarantees that the T lvalue is properly + * rooted. See "Move GC Stack Rooting" above. + * + * If you want to add additional methods to Handle for a specific + * specialization, define a HandleBase<T> specialization containing them. + */ +template <typename T> +class MOZ_NONHEAP_CLASS Handle : public js::HandleBase<T> +{ + friend class JS::MutableHandle<T>; + + public: + /* Creates a handle from a handle of a type convertible to T. */ + template <typename S> + MOZ_IMPLICIT Handle(Handle<S> handle, + typename mozilla::EnableIf<mozilla::IsConvertible<S, T>::value, int>::Type dummy = 0) + { + static_assert(sizeof(Handle<T>) == sizeof(T*), + "Handle must be binary compatible with T*."); + ptr = reinterpret_cast<const T*>(handle.address()); + } + + MOZ_IMPLICIT Handle(decltype(nullptr)) { + static_assert(mozilla::IsPointer<T>::value, + "nullptr_t overload not valid for non-pointer types"); + ptr = reinterpret_cast<const T*>(&js::ConstNullValue); + } + + MOZ_IMPLICIT Handle(MutableHandle<T> handle) { + ptr = handle.address(); + } + + /* + * Take care when calling this method! + * + * This creates a Handle from the raw location of a T. + * + * It should be called only if the following conditions hold: + * + * 1) the location of the T is guaranteed to be marked (for some reason + * other than being a Rooted), e.g., if it is guaranteed to be reachable + * from an implicit root. + * + * 2) the contents of the location are immutable, or at least cannot change + * for the lifetime of the handle, as its users may not expect its value + * to change underneath them. + */ + static constexpr Handle fromMarkedLocation(const T* p) { + return Handle(p, DeliberatelyChoosingThisOverload, + ImUsingThisOnlyInFromFromMarkedLocation); + } + + /* + * Construct a handle from an explicitly rooted location. This is the + * normal way to create a handle, and normally happens implicitly. + */ + template <typename S> + inline + MOZ_IMPLICIT Handle(const Rooted<S>& root, + typename mozilla::EnableIf<mozilla::IsConvertible<S, T>::value, int>::Type dummy = 0); + + template <typename S> + inline + MOZ_IMPLICIT Handle(const PersistentRooted<S>& root, + typename mozilla::EnableIf<mozilla::IsConvertible<S, T>::value, int>::Type dummy = 0); + + /* Construct a read only handle from a mutable handle. */ + template <typename S> + inline + MOZ_IMPLICIT Handle(MutableHandle<S>& root, + typename mozilla::EnableIf<mozilla::IsConvertible<S, T>::value, int>::Type dummy = 0); + + DECLARE_POINTER_COMPARISON_OPS(T); + DECLARE_POINTER_CONSTREF_OPS(T); + DECLARE_NONPOINTER_ACCESSOR_METHODS(*ptr); + + private: + Handle() {} + DELETE_ASSIGNMENT_OPS(Handle, T); + + enum Disambiguator { DeliberatelyChoosingThisOverload = 42 }; + enum CallerIdentity { ImUsingThisOnlyInFromFromMarkedLocation = 17 }; + constexpr Handle(const T* p, Disambiguator, CallerIdentity) : ptr(p) {} + + const T* ptr; +}; + +/** + * Similar to a handle, but the underlying storage can be changed. This is + * useful for outparams. + * + * If you want to add additional methods to MutableHandle for a specific + * specialization, define a MutableHandleBase<T> specialization containing + * them. + */ +template <typename T> +class MOZ_STACK_CLASS MutableHandle : public js::MutableHandleBase<T> +{ + public: + inline MOZ_IMPLICIT MutableHandle(Rooted<T>* root); + inline MOZ_IMPLICIT MutableHandle(PersistentRooted<T>* root); + + private: + // Disallow nullptr for overloading purposes. + MutableHandle(decltype(nullptr)) = delete; + + public: + void set(const T& v) { + *ptr = v; + } + void set(T&& v) { + *ptr = mozilla::Move(v); + } + + /* + * This may be called only if the location of the T is guaranteed + * to be marked (for some reason other than being a Rooted), + * e.g., if it is guaranteed to be reachable from an implicit root. + * + * Create a MutableHandle from a raw location of a T. + */ + static MutableHandle fromMarkedLocation(T* p) { + MutableHandle h; + h.ptr = p; + return h; + } + + DECLARE_POINTER_CONSTREF_OPS(T); + DECLARE_NONPOINTER_ACCESSOR_METHODS(*ptr); + DECLARE_NONPOINTER_MUTABLE_ACCESSOR_METHODS(*ptr); + + private: + MutableHandle() {} + DELETE_ASSIGNMENT_OPS(MutableHandle, T); + + T* ptr; +}; + +} /* namespace JS */ + +namespace js { + +template <typename T> +struct BarrierMethods<T*> +{ + static T* initial() { return nullptr; } + static gc::Cell* asGCThingOrNull(T* v) { + if (!v) + return nullptr; + MOZ_ASSERT(uintptr_t(v) > 32); + return reinterpret_cast<gc::Cell*>(v); + } + static void postBarrier(T** vp, T* prev, T* next) { + if (next) + JS::AssertGCThingIsNotAnObjectSubclass(reinterpret_cast<js::gc::Cell*>(next)); + } + static void exposeToJS(T* t) { + if (t) + js::gc::ExposeGCThingToActiveJS(JS::GCCellPtr(t)); + } +}; + +template <> +struct BarrierMethods<JSObject*> +{ + static JSObject* initial() { return nullptr; } + static gc::Cell* asGCThingOrNull(JSObject* v) { + if (!v) + return nullptr; + MOZ_ASSERT(uintptr_t(v) > 32); + return reinterpret_cast<gc::Cell*>(v); + } + static void postBarrier(JSObject** vp, JSObject* prev, JSObject* next) { + JS::HeapObjectPostBarrier(vp, prev, next); + } + static void exposeToJS(JSObject* obj) { + if (obj) + JS::ExposeObjectToActiveJS(obj); + } +}; + +template <> +struct BarrierMethods<JSFunction*> +{ + static JSFunction* initial() { return nullptr; } + static gc::Cell* asGCThingOrNull(JSFunction* v) { + if (!v) + return nullptr; + MOZ_ASSERT(uintptr_t(v) > 32); + return reinterpret_cast<gc::Cell*>(v); + } + static void postBarrier(JSFunction** vp, JSFunction* prev, JSFunction* next) { + JS::HeapObjectPostBarrier(reinterpret_cast<JSObject**>(vp), + reinterpret_cast<JSObject*>(prev), + reinterpret_cast<JSObject*>(next)); + } + static void exposeToJS(JSFunction* fun) { + if (fun) + JS::ExposeObjectToActiveJS(reinterpret_cast<JSObject*>(fun)); + } +}; + +// Provide hash codes for Cell kinds that may be relocated and, thus, not have +// a stable address to use as the base for a hash code. Instead of the address, +// this hasher uses Cell::getUniqueId to provide exact matches and as a base +// for generating hash codes. +// +// Note: this hasher, like PointerHasher can "hash" a nullptr. While a nullptr +// would not likely be a useful key, there are some cases where being able to +// hash a nullptr is useful, either on purpose or because of bugs: +// (1) existence checks where the key may happen to be null and (2) some +// aggregate Lookup kinds embed a JSObject* that is frequently null and do not +// null test before dispatching to the hasher. +template <typename T> +struct JS_PUBLIC_API(MovableCellHasher) +{ + using Key = T; + using Lookup = T; + + static bool hasHash(const Lookup& l); + static bool ensureHash(const Lookup& l); + static HashNumber hash(const Lookup& l); + static bool match(const Key& k, const Lookup& l); + static void rekey(Key& k, const Key& newKey) { k = newKey; } +}; + +template <typename T> +struct JS_PUBLIC_API(MovableCellHasher<JS::Heap<T>>) +{ + using Key = JS::Heap<T>; + using Lookup = T; + + static bool hasHash(const Lookup& l) { return MovableCellHasher<T>::hasHash(l); } + static bool ensureHash(const Lookup& l) { return MovableCellHasher<T>::ensureHash(l); } + static HashNumber hash(const Lookup& l) { return MovableCellHasher<T>::hash(l); } + static bool match(const Key& k, const Lookup& l) { + return MovableCellHasher<T>::match(k.unbarrieredGet(), l); + } + static void rekey(Key& k, const Key& newKey) { k.unsafeSet(newKey); } +}; + +template <typename T> +struct FallibleHashMethods<MovableCellHasher<T>> +{ + template <typename Lookup> static bool hasHash(Lookup&& l) { + return MovableCellHasher<T>::hasHash(mozilla::Forward<Lookup>(l)); + } + template <typename Lookup> static bool ensureHash(Lookup&& l) { + return MovableCellHasher<T>::ensureHash(mozilla::Forward<Lookup>(l)); + } +}; + +} /* namespace js */ + +namespace js { + +// The alignment must be set because the Rooted and PersistentRooted ptr fields +// may be accessed through reinterpret_cast<Rooted<ConcreteTraceable>*>, and +// the compiler may choose a different alignment for the ptr field when it +// knows the actual type stored in DispatchWrapper<T>. +// +// It would make more sense to align only those specific fields of type +// DispatchWrapper, rather than DispatchWrapper itself, but that causes MSVC to +// fail when Rooted is used in an IsConvertible test. +template <typename T> +class alignas(8) DispatchWrapper +{ + static_assert(JS::MapTypeToRootKind<T>::kind == JS::RootKind::Traceable, + "DispatchWrapper is intended only for usage with a Traceable"); + + using TraceFn = void (*)(JSTracer*, T*, const char*); + TraceFn tracer; + alignas(gc::CellSize) T storage; + + public: + template <typename U> + MOZ_IMPLICIT DispatchWrapper(U&& initial) + : tracer(&JS::GCPolicy<T>::trace), + storage(mozilla::Forward<U>(initial)) + { } + + // Mimic a pointer type, so that we can drop into Rooted. + T* operator &() { return &storage; } + const T* operator &() const { return &storage; } + operator T&() { return storage; } + operator const T&() const { return storage; } + + // Trace the contained storage (of unknown type) using the trace function + // we set aside when we did know the type. + static void TraceWrapped(JSTracer* trc, T* thingp, const char* name) { + auto wrapper = reinterpret_cast<DispatchWrapper*>( + uintptr_t(thingp) - offsetof(DispatchWrapper, storage)); + wrapper->tracer(trc, &wrapper->storage, name); + } +}; + +} /* namespace js */ + +namespace JS { + +/** + * Local variable of type T whose value is always rooted. This is typically + * used for local variables, or for non-rooted values being passed to a + * function that requires a handle, e.g. Foo(Root<T>(cx, x)). + * + * If you want to add additional methods to Rooted for a specific + * specialization, define a RootedBase<T> specialization containing them. + */ +template <typename T> +class MOZ_RAII Rooted : public js::RootedBase<T> +{ + inline void registerWithRootLists(js::RootedListHeads& roots) { + this->stack = &roots[JS::MapTypeToRootKind<T>::kind]; + this->prev = *stack; + *stack = reinterpret_cast<Rooted<void*>*>(this); + } + + inline js::RootedListHeads& rootLists(JS::RootingContext* cx) { + return rootLists(static_cast<js::ContextFriendFields*>(cx)); + } + inline js::RootedListHeads& rootLists(js::ContextFriendFields* cx) { + if (JS::Zone* zone = cx->zone_) + return JS::shadow::Zone::asShadowZone(zone)->stackRoots_; + MOZ_ASSERT(cx->isJSContext); + return cx->roots.stackRoots_; + } + inline js::RootedListHeads& rootLists(JSContext* cx) { + return rootLists(js::ContextFriendFields::get(cx)); + } + + public: + template <typename RootingContext> + explicit Rooted(const RootingContext& cx) + : ptr(GCPolicy<T>::initial()) + { + registerWithRootLists(rootLists(cx)); + } + + template <typename RootingContext, typename S> + Rooted(const RootingContext& cx, S&& initial) + : ptr(mozilla::Forward<S>(initial)) + { + registerWithRootLists(rootLists(cx)); + } + + ~Rooted() { + MOZ_ASSERT(*stack == reinterpret_cast<Rooted<void*>*>(this)); + *stack = prev; + } + + Rooted<T>* previous() { return reinterpret_cast<Rooted<T>*>(prev); } + + /* + * This method is public for Rooted so that Codegen.py can use a Rooted + * interchangeably with a MutableHandleValue. + */ + void set(const T& value) { + ptr = value; + } + void set(T&& value) { + ptr = mozilla::Move(value); + } + + DECLARE_POINTER_COMPARISON_OPS(T); + DECLARE_POINTER_CONSTREF_OPS(T); + DECLARE_POINTER_ASSIGN_OPS(Rooted, T); + DECLARE_NONPOINTER_ACCESSOR_METHODS(ptr); + DECLARE_NONPOINTER_MUTABLE_ACCESSOR_METHODS(ptr); + + private: + /* + * These need to be templated on void* to avoid aliasing issues between, for + * example, Rooted<JSObject> and Rooted<JSFunction>, which use the same + * stack head pointer for different classes. + */ + Rooted<void*>** stack; + Rooted<void*>* prev; + + /* + * For pointer types, the TraceKind for tracing is based on the list it is + * in (selected via MapTypeToRootKind), so no additional storage is + * required here. Non-pointer types, however, share the same list, so the + * function to call for tracing is stored adjacent to the struct. Since C++ + * cannot templatize on storage class, this is implemented via the wrapper + * class DispatchWrapper. + */ + using MaybeWrapped = typename mozilla::Conditional< + MapTypeToRootKind<T>::kind == JS::RootKind::Traceable, + js::DispatchWrapper<T>, + T>::Type; + MaybeWrapped ptr; + + Rooted(const Rooted&) = delete; +} JS_HAZ_ROOTED; + +} /* namespace JS */ + +namespace js { + +/** + * Augment the generic Rooted<T> interface when T = JSObject* with + * class-querying and downcasting operations. + * + * Given a Rooted<JSObject*> obj, one can view + * Handle<StringObject*> h = obj.as<StringObject*>(); + * as an optimization of + * Rooted<StringObject*> rooted(cx, &obj->as<StringObject*>()); + * Handle<StringObject*> h = rooted; + */ +template <> +class RootedBase<JSObject*> +{ + public: + template <class U> + JS::Handle<U*> as() const; +}; + +/** + * Augment the generic Handle<T> interface when T = JSObject* with + * downcasting operations. + * + * Given a Handle<JSObject*> obj, one can view + * Handle<StringObject*> h = obj.as<StringObject*>(); + * as an optimization of + * Rooted<StringObject*> rooted(cx, &obj->as<StringObject*>()); + * Handle<StringObject*> h = rooted; + */ +template <> +class HandleBase<JSObject*> +{ + public: + template <class U> + JS::Handle<U*> as() const; +}; + +/** Interface substitute for Rooted<T> which does not root the variable's memory. */ +template <typename T> +class MOZ_RAII FakeRooted : public RootedBase<T> +{ + public: + template <typename CX> + explicit FakeRooted(CX* cx) : ptr(JS::GCPolicy<T>::initial()) {} + + template <typename CX> + FakeRooted(CX* cx, T initial) : ptr(initial) {} + + DECLARE_POINTER_COMPARISON_OPS(T); + DECLARE_POINTER_CONSTREF_OPS(T); + DECLARE_POINTER_ASSIGN_OPS(FakeRooted, T); + DECLARE_NONPOINTER_ACCESSOR_METHODS(ptr); + DECLARE_NONPOINTER_MUTABLE_ACCESSOR_METHODS(ptr); + + private: + T ptr; + + void set(const T& value) { + ptr = value; + } + + FakeRooted(const FakeRooted&) = delete; +}; + +/** Interface substitute for MutableHandle<T> which is not required to point to rooted memory. */ +template <typename T> +class FakeMutableHandle : public js::MutableHandleBase<T> +{ + public: + MOZ_IMPLICIT FakeMutableHandle(T* t) { + ptr = t; + } + + MOZ_IMPLICIT FakeMutableHandle(FakeRooted<T>* root) { + ptr = root->address(); + } + + void set(const T& v) { + *ptr = v; + } + + DECLARE_POINTER_CONSTREF_OPS(T); + DECLARE_NONPOINTER_ACCESSOR_METHODS(*ptr); + DECLARE_NONPOINTER_MUTABLE_ACCESSOR_METHODS(*ptr); + + private: + FakeMutableHandle() {} + DELETE_ASSIGNMENT_OPS(FakeMutableHandle, T); + + T* ptr; +}; + +/** + * Types for a variable that either should or shouldn't be rooted, depending on + * the template parameter allowGC. Used for implementing functions that can + * operate on either rooted or unrooted data. + * + * The toHandle() and toMutableHandle() functions are for calling functions + * which require handle types and are only called in the CanGC case. These + * allow the calling code to type check. + */ +enum AllowGC { + NoGC = 0, + CanGC = 1 +}; +template <typename T, AllowGC allowGC> +class MaybeRooted +{ +}; + +template <typename T> class MaybeRooted<T, CanGC> +{ + public: + typedef JS::Handle<T> HandleType; + typedef JS::Rooted<T> RootType; + typedef JS::MutableHandle<T> MutableHandleType; + + static inline JS::Handle<T> toHandle(HandleType v) { + return v; + } + + static inline JS::MutableHandle<T> toMutableHandle(MutableHandleType v) { + return v; + } + + template <typename T2> + static inline JS::Handle<T2*> downcastHandle(HandleType v) { + return v.template as<T2>(); + } +}; + +template <typename T> class MaybeRooted<T, NoGC> +{ + public: + typedef const T& HandleType; + typedef FakeRooted<T> RootType; + typedef FakeMutableHandle<T> MutableHandleType; + + static JS::Handle<T> toHandle(HandleType v) { + MOZ_CRASH("Bad conversion"); + } + + static JS::MutableHandle<T> toMutableHandle(MutableHandleType v) { + MOZ_CRASH("Bad conversion"); + } + + template <typename T2> + static inline T2* downcastHandle(HandleType v) { + return &v->template as<T2>(); + } +}; + +} /* namespace js */ + +namespace JS { + +template <typename T> template <typename S> +inline +Handle<T>::Handle(const Rooted<S>& root, + typename mozilla::EnableIf<mozilla::IsConvertible<S, T>::value, int>::Type dummy) +{ + ptr = reinterpret_cast<const T*>(root.address()); +} + +template <typename T> template <typename S> +inline +Handle<T>::Handle(const PersistentRooted<S>& root, + typename mozilla::EnableIf<mozilla::IsConvertible<S, T>::value, int>::Type dummy) +{ + ptr = reinterpret_cast<const T*>(root.address()); +} + +template <typename T> template <typename S> +inline +Handle<T>::Handle(MutableHandle<S>& root, + typename mozilla::EnableIf<mozilla::IsConvertible<S, T>::value, int>::Type dummy) +{ + ptr = reinterpret_cast<const T*>(root.address()); +} + +template <typename T> +inline +MutableHandle<T>::MutableHandle(Rooted<T>* root) +{ + static_assert(sizeof(MutableHandle<T>) == sizeof(T*), + "MutableHandle must be binary compatible with T*."); + ptr = root->address(); +} + +template <typename T> +inline +MutableHandle<T>::MutableHandle(PersistentRooted<T>* root) +{ + static_assert(sizeof(MutableHandle<T>) == sizeof(T*), + "MutableHandle must be binary compatible with T*."); + ptr = root->address(); +} + +/** + * A copyable, assignable global GC root type with arbitrary lifetime, an + * infallible constructor, and automatic unrooting on destruction. + * + * These roots can be used in heap-allocated data structures, so they are not + * associated with any particular JSContext or stack. They are registered with + * the JSRuntime itself, without locking, so they require a full JSContext to be + * initialized, not one of its more restricted superclasses. Initialization may + * take place on construction, or in two phases if the no-argument constructor + * is called followed by init(). + * + * Note that you must not use an PersistentRooted in an object owned by a JS + * object: + * + * Whenever one object whose lifetime is decided by the GC refers to another + * such object, that edge must be traced only if the owning JS object is traced. + * This applies not only to JS objects (which obviously are managed by the GC) + * but also to C++ objects owned by JS objects. + * + * If you put a PersistentRooted in such a C++ object, that is almost certainly + * a leak. When a GC begins, the referent of the PersistentRooted is treated as + * live, unconditionally (because a PersistentRooted is a *root*), even if the + * JS object that owns it is unreachable. If there is any path from that + * referent back to the JS object, then the C++ object containing the + * PersistentRooted will not be destructed, and the whole blob of objects will + * not be freed, even if there are no references to them from the outside. + * + * In the context of Firefox, this is a severe restriction: almost everything in + * Firefox is owned by some JS object or another, so using PersistentRooted in + * such objects would introduce leaks. For these kinds of edges, Heap<T> or + * TenuredHeap<T> would be better types. It's up to the implementor of the type + * containing Heap<T> or TenuredHeap<T> members to make sure their referents get + * marked when the object itself is marked. + */ +template<typename T> +class PersistentRooted : public js::PersistentRootedBase<T>, + private mozilla::LinkedListElement<PersistentRooted<T>> +{ + using ListBase = mozilla::LinkedListElement<PersistentRooted<T>>; + + friend class mozilla::LinkedList<PersistentRooted>; + friend class mozilla::LinkedListElement<PersistentRooted>; + + void registerWithRootLists(js::RootLists& roots) { + MOZ_ASSERT(!initialized()); + JS::RootKind kind = JS::MapTypeToRootKind<T>::kind; + roots.heapRoots_[kind].insertBack(reinterpret_cast<JS::PersistentRooted<void*>*>(this)); + } + + js::RootLists& rootLists(JSContext* cx) { + return rootLists(JS::RootingContext::get(cx)); + } + js::RootLists& rootLists(JS::RootingContext* cx) { + MOZ_ASSERT(cx->isJSContext); + return cx->roots; + } + + // Disallow ExclusiveContext*. + js::RootLists& rootLists(js::ContextFriendFields* cx) = delete; + + public: + PersistentRooted() : ptr(GCPolicy<T>::initial()) {} + + template <typename RootingContext> + explicit PersistentRooted(const RootingContext& cx) + : ptr(GCPolicy<T>::initial()) + { + registerWithRootLists(rootLists(cx)); + } + + template <typename RootingContext, typename U> + PersistentRooted(const RootingContext& cx, U&& initial) + : ptr(mozilla::Forward<U>(initial)) + { + registerWithRootLists(rootLists(cx)); + } + + PersistentRooted(const PersistentRooted& rhs) + : mozilla::LinkedListElement<PersistentRooted<T>>(), + ptr(rhs.ptr) + { + /* + * Copy construction takes advantage of the fact that the original + * is already inserted, and simply adds itself to whatever list the + * original was on - no JSRuntime pointer needed. + * + * This requires mutating rhs's links, but those should be 'mutable' + * anyway. C++ doesn't let us declare mutable base classes. + */ + const_cast<PersistentRooted&>(rhs).setNext(this); + } + + bool initialized() { + return ListBase::isInList(); + } + + template <typename RootingContext> + void init(const RootingContext& cx) { + init(cx, GCPolicy<T>::initial()); + } + + template <typename RootingContext, typename U> + void init(const RootingContext& cx, U&& initial) { + ptr = mozilla::Forward<U>(initial); + registerWithRootLists(rootLists(cx)); + } + + void reset() { + if (initialized()) { + set(GCPolicy<T>::initial()); + ListBase::remove(); + } + } + + DECLARE_POINTER_COMPARISON_OPS(T); + DECLARE_POINTER_CONSTREF_OPS(T); + DECLARE_POINTER_ASSIGN_OPS(PersistentRooted, T); + DECLARE_NONPOINTER_ACCESSOR_METHODS(ptr); + + // These are the same as DECLARE_NONPOINTER_MUTABLE_ACCESSOR_METHODS, except + // they check that |this| is initialized in case the caller later stores + // something in |ptr|. + T* address() { + MOZ_ASSERT(initialized()); + return &ptr; + } + T& get() { + MOZ_ASSERT(initialized()); + return ptr; + } + + private: + template <typename U> + void set(U&& value) { + MOZ_ASSERT(initialized()); + ptr = mozilla::Forward<U>(value); + } + + // See the comment above Rooted::ptr. + using MaybeWrapped = typename mozilla::Conditional< + MapTypeToRootKind<T>::kind == JS::RootKind::Traceable, + js::DispatchWrapper<T>, + T>::Type; + MaybeWrapped ptr; +} JS_HAZ_ROOTED; + +class JS_PUBLIC_API(ObjectPtr) +{ + Heap<JSObject*> value; + + public: + ObjectPtr() : value(nullptr) {} + + explicit ObjectPtr(JSObject* obj) : value(obj) {} + + ObjectPtr(const ObjectPtr& other) : value(other.value) {} + + ObjectPtr(ObjectPtr&& other) + : value(other.value) + { + other.value = nullptr; + } + + /* Always call finalize before the destructor. */ + ~ObjectPtr() { MOZ_ASSERT(!value); } + + void finalize(JSRuntime* rt); + void finalize(JSContext* cx); + + void init(JSObject* obj) { value = obj; } + + JSObject* get() const { return value; } + JSObject* unbarrieredGet() const { return value.unbarrieredGet(); } + + void writeBarrierPre(JSContext* cx) { + IncrementalObjectBarrier(value); + } + + void updateWeakPointerAfterGC(); + + ObjectPtr& operator=(JSObject* obj) { + IncrementalObjectBarrier(value); + value = obj; + return *this; + } + + void trace(JSTracer* trc, const char* name); + + JSObject& operator*() const { return *value; } + JSObject* operator->() const { return value; } + operator JSObject*() const { return value; } + + explicit operator bool() const { return value.unbarrieredGet(); } + explicit operator bool() { return value.unbarrieredGet(); } +}; + +} /* namespace JS */ + +namespace js { + +template <typename Outer, typename T, typename D> +class UniquePtrOperations +{ + const UniquePtr<T, D>& uniquePtr() const { return static_cast<const Outer*>(this)->get(); } + + public: + explicit operator bool() const { return !!uniquePtr(); } + T* get() const { return uniquePtr().get(); } + T* operator->() const { return get(); } + T& operator*() const { return *uniquePtr(); } +}; + +template <typename Outer, typename T, typename D> +class MutableUniquePtrOperations : public UniquePtrOperations<Outer, T, D> +{ + UniquePtr<T, D>& uniquePtr() { return static_cast<Outer*>(this)->get(); } + + public: + MOZ_MUST_USE typename UniquePtr<T, D>::Pointer release() { return uniquePtr().release(); } + void reset(T* ptr = T()) { uniquePtr().reset(ptr); } +}; + +template <typename T, typename D> +class RootedBase<UniquePtr<T, D>> + : public MutableUniquePtrOperations<JS::Rooted<UniquePtr<T, D>>, T, D> +{ }; + +template <typename T, typename D> +class MutableHandleBase<UniquePtr<T, D>> + : public MutableUniquePtrOperations<JS::MutableHandle<UniquePtr<T, D>>, T, D> +{ }; + +template <typename T, typename D> +class HandleBase<UniquePtr<T, D>> + : public UniquePtrOperations<JS::Handle<UniquePtr<T, D>>, T, D> +{ }; + +template <typename T, typename D> +class PersistentRootedBase<UniquePtr<T, D>> + : public MutableUniquePtrOperations<JS::PersistentRooted<UniquePtr<T, D>>, T, D> +{ }; + +namespace gc { + +template <typename T, typename TraceCallbacks> +void +CallTraceCallbackOnNonHeap(T* v, const TraceCallbacks& aCallbacks, const char* aName, void* aClosure) +{ + static_assert(sizeof(T) == sizeof(JS::Heap<T>), "T and Heap<T> must be compatible."); + MOZ_ASSERT(v); + mozilla::DebugOnly<Cell*> cell = BarrierMethods<T>::asGCThingOrNull(*v); + MOZ_ASSERT(cell); + MOZ_ASSERT(!IsInsideNursery(cell)); + JS::Heap<T>* asHeapT = reinterpret_cast<JS::Heap<T>*>(v); + aCallbacks.Trace(asHeapT, aName, aClosure); +} + +} /* namespace gc */ +} /* namespace js */ + +// mozilla::Swap uses a stack temporary, which prevents classes like Heap<T> +// from being declared MOZ_HEAP_CLASS. +namespace mozilla { + +template <typename T> +inline void +Swap(JS::Heap<T>& aX, JS::Heap<T>& aY) +{ + T tmp = aX; + aX = aY; + aY = tmp; +} + +template <typename T> +inline void +Swap(JS::TenuredHeap<T>& aX, JS::TenuredHeap<T>& aY) +{ + T tmp = aX; + aX = aY; + aY = tmp; +} + +} /* namespace mozilla */ + +#undef DELETE_ASSIGNMENT_OPS + +#endif /* js_RootingAPI_h */ |