axmol/scripting/javascript/spidermonkey-win32/include/gc/Root.h

484 lines
14 KiB
C
Raw Normal View History

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
* vim: set ts=8 sw=4 et tw=78:
*
* 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 jsgc_root_h__
#define jsgc_root_h__
#ifdef __cplusplus
#include "mozilla/TypeTraits.h"
#include "jsapi.h"
#include "js/TemplateLib.h"
#include "js/Utility.h"
namespace JS {
/*
* 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 classes below are used to root stack locations whose value may be held
* live across a call that can trigger GC (i.e. a call which might allocate any
* GC things). For a code fragment such as:
*
* Foo();
* ... = obj->lastProperty();
*
* If Foo() 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 Foo() 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.
*
* Several classes are available for rooting stack locations. All are templated
* on the type T of the value being rooted, for which RootMethods<T> must
* have an instantiation.
*
* - 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 allocate GC things or otherwise 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.
*/
template <typename T> class MutableHandle;
template <typename T> class Rooted;
template <typename T>
struct RootMethods { };
/*
* Handle provides an implicit constructor for NullPtr so that, given:
* foo(Handle<JSObject*> h);
* callers can simply write:
* foo(NullPtr());
* which avoids creating a Rooted<JSObject*> just to pass NULL.
*/
struct NullPtr
{
static void * const constNullValue;
};
template <typename T>
class MutableHandle;
template <typename T>
class HandleBase {};
/*
* 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 Handle : public HandleBase<T>
{
public:
/* Creates a handle from a handle of a type convertible to T. */
template <typename S>
Handle(Handle<S> handle,
typename mozilla::EnableIf<mozilla::IsConvertible<S, T>::value, int>::Type dummy = 0)
{
ptr = reinterpret_cast<const T *>(handle.address());
}
/* Create a handle for a NULL pointer. */
Handle(NullPtr) {
typedef typename js::tl::StaticAssert<js::tl::IsPointerType<T>::result>::result _;
ptr = reinterpret_cast<const T *>(&NullPtr::constNullValue);
}
friend class MutableHandle<T>;
Handle(MutableHandle<T> handle) {
ptr = handle.address();
}
/*
* 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 Handle from a raw location of a T.
*/
static Handle fromMarkedLocation(const T *p) {
Handle h;
h.ptr = p;
return h;
}
/*
* 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
Handle(Rooted<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
Handle(MutableHandle<S> &root,
typename mozilla::EnableIf<mozilla::IsConvertible<S, T>::value, int>::Type dummy = 0);
const T *address() const { return ptr; }
T get() const { return *ptr; }
operator T () const { return get(); }
T operator ->() const { return get(); }
private:
Handle() {}
const T *ptr;
template <typename S>
void operator =(S v) MOZ_DELETE;
};
typedef Handle<JSObject*> HandleObject;
typedef Handle<JSFunction*> HandleFunction;
typedef Handle<JSScript*> HandleScript;
typedef Handle<JSString*> HandleString;
typedef Handle<jsid> HandleId;
typedef Handle<Value> HandleValue;
template <typename T>
class MutableHandleBase {};
/*
* 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 MutableHandle : public MutableHandleBase<T>
{
public:
template <typename S>
MutableHandle(MutableHandle<S> handle,
typename mozilla::EnableIf<mozilla::IsConvertible<S, T>::value, int>::Type dummy = 0)
{
this->ptr = reinterpret_cast<const T *>(handle.address());
}
template <typename S>
inline
MutableHandle(Rooted<S> *root,
typename mozilla::EnableIf<mozilla::IsConvertible<S, T>::value, int>::Type dummy = 0);
void set(T v)
{
JS_ASSERT(!RootMethods<T>::poisoned(v));
*ptr = 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;
}
T *address() const { return ptr; }
T get() const { return *ptr; }
operator T () const { return get(); }
T operator ->() const { return get(); }
private:
MutableHandle() {}
T *ptr;
template <typename S>
void operator =(S v) MOZ_DELETE;
};
typedef MutableHandle<JSObject*> MutableHandleObject;
typedef MutableHandle<Value> MutableHandleValue;
/*
* Raw pointer used as documentation that a parameter does not need to be
* rooted.
*/
typedef JSObject * RawObject;
/*
* By default, pointers should use the inheritance hierarchy to find their
* ThingRootKind. Some pointer types are explicitly set in jspubtd.h so that
* Rooted<T> may be used without the class definition being available.
*/
template <typename T>
struct RootKind<T *> { static ThingRootKind rootKind() { return T::rootKind(); }; };
template <typename T>
struct RootMethods<T *>
{
static T *initial() { return NULL; }
static ThingRootKind kind() { return RootKind<T *>::rootKind(); }
static bool poisoned(T *v) { return IsPoisonedPtr(v); }
};
template <typename T>
class RootedBase {};
/*
* 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 Rooted : public RootedBase<T>
{
void init(JSContext *cx_)
{
#if defined(JSGC_ROOT_ANALYSIS) || defined(JSGC_USE_EXACT_ROOTING)
ContextFriendFields *cx = ContextFriendFields::get(cx_);
ThingRootKind kind = RootMethods<T>::kind();
this->stack = reinterpret_cast<Rooted<T>**>(&cx->thingGCRooters[kind]);
this->prev = *stack;
*stack = this;
JS_ASSERT(!RootMethods<T>::poisoned(ptr));
#endif
}
public:
Rooted(JSContext *cx) : ptr(RootMethods<T>::initial()) { init(cx); }
Rooted(JSContext *cx, T initial) : ptr(initial) { init(cx); }
~Rooted()
{
#if defined(JSGC_ROOT_ANALYSIS) || defined(JSGC_USE_EXACT_ROOTING)
JS_ASSERT(*stack == this);
*stack = prev;
#endif
}
#if defined(JSGC_ROOT_ANALYSIS) || defined(JSGC_USE_EXACT_ROOTING)
Rooted<T> *previous() { return prev; }
#endif
operator T () const { return ptr; }
T operator ->() const { return ptr; }
T * address() { return &ptr; }
const T * address() const { return &ptr; }
T & get() { return ptr; }
const T & get() const { return ptr; }
T & operator =(T value)
{
JS_ASSERT(!RootMethods<T>::poisoned(value));
ptr = value;
return ptr;
}
T & operator =(const Rooted &value)
{
ptr = value;
return ptr;
}
private:
#if defined(JSGC_ROOT_ANALYSIS) || defined(JSGC_USE_EXACT_ROOTING)
Rooted<T> **stack, *prev;
#endif
T ptr;
Rooted() MOZ_DELETE;
Rooted(const Rooted &) MOZ_DELETE;
};
template<typename T> template <typename S>
inline
Handle<T>::Handle(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(MutableHandle<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
MutableHandle<T>::MutableHandle(Rooted<S> *root,
typename mozilla::EnableIf<mozilla::IsConvertible<S, T>::value, int>::Type dummy)
{
ptr = root->address();
}
typedef Rooted<JSObject*> RootedObject;
typedef Rooted<JSFunction*> RootedFunction;
typedef Rooted<JSScript*> RootedScript;
typedef Rooted<JSString*> RootedString;
typedef Rooted<jsid> RootedId;
typedef Rooted<Value> RootedValue;
/*
* Mark a stack location as a root for the rooting analysis, without actually
* rooting it in release builds. This should only be used for stack locations
* of GC things that cannot be relocated by a garbage collection, and that
* are definitely reachable via another path.
*/
class SkipRoot
{
#if defined(DEBUG) && defined(JSGC_ROOT_ANALYSIS)
SkipRoot **stack, *prev;
const uint8_t *start;
const uint8_t *end;
template <typename T>
void init(ContextFriendFields *cx, const T *ptr, size_t count)
{
this->stack = &cx->skipGCRooters;
this->prev = *stack;
*stack = this;
this->start = (const uint8_t *) ptr;
this->end = this->start + (sizeof(T) * count);
}
public:
template <typename T>
SkipRoot(JSContext *cx, const T *ptr, size_t count = 1
JS_GUARD_OBJECT_NOTIFIER_PARAM)
{
init(ContextFriendFields::get(cx), ptr, count);
JS_GUARD_OBJECT_NOTIFIER_INIT;
}
~SkipRoot()
{
JS_ASSERT(*stack == this);
*stack = prev;
}
SkipRoot *previous() { return prev; }
bool contains(const uint8_t *v, size_t len) {
return v >= start && v + len <= end;
}
#else /* DEBUG && JSGC_ROOT_ANALYSIS */
public:
template <typename T>
SkipRoot(JSContext *cx, const T *ptr, size_t count = 1
JS_GUARD_OBJECT_NOTIFIER_PARAM)
{
JS_GUARD_OBJECT_NOTIFIER_INIT;
}
#endif /* DEBUG && JSGC_ROOT_ANALYSIS */
JS_DECL_USE_GUARD_OBJECT_NOTIFIER
};
/*
* This typedef is to annotate parameters that we have manually verified do not
* need rooting, as opposed to parameters that have not yet been considered.
*/
typedef JSObject *RawObject;
#ifdef DEBUG
JS_FRIEND_API(bool) IsRootingUnnecessaryForContext(JSContext *cx);
JS_FRIEND_API(void) SetRootingUnnecessaryForContext(JSContext *cx, bool value);
JS_FRIEND_API(bool) RelaxRootChecksForContext(JSContext *cx);
#endif
class AssertRootingUnnecessary {
JS_DECL_USE_GUARD_OBJECT_NOTIFIER
#ifdef DEBUG
JSContext *cx;
bool prev;
#endif
public:
AssertRootingUnnecessary(JSContext *cx JS_GUARD_OBJECT_NOTIFIER_PARAM)
{
JS_GUARD_OBJECT_NOTIFIER_INIT;
#ifdef DEBUG
this->cx = cx;
prev = IsRootingUnnecessaryForContext(cx);
SetRootingUnnecessaryForContext(cx, true);
#endif
}
~AssertRootingUnnecessary() {
#ifdef DEBUG
SetRootingUnnecessaryForContext(cx, prev);
#endif
}
};
#if defined(DEBUG) && defined(JS_GC_ZEAL) && defined(JSGC_ROOT_ANALYSIS) && !defined(JS_THREADSAFE)
extern void
CheckStackRoots(JSContext *cx);
#endif
/*
* Hook for dynamic root analysis. Checks the native stack and poisons
* references to GC things which have not been rooted.
*/
inline void MaybeCheckStackRoots(JSContext *cx, bool relax = true)
{
#ifdef DEBUG
JS_ASSERT(!IsRootingUnnecessaryForContext(cx));
# if defined(JS_GC_ZEAL) && defined(JSGC_ROOT_ANALYSIS) && !defined(JS_THREADSAFE)
if (relax && RelaxRootChecksForContext(cx))
return;
CheckStackRoots(cx);
# endif
#endif
}
} /* namespace JS */
#endif /* __cplusplus */
#endif /* jsgc_root_h___ */