The Tor Browser: comparison js/public/Anchor.h

--1:000000000000
+:c350a7a846e9
+/* -*- 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/. */
+/* JS::Anchor implementation. */
+#ifndef js_Anchor_h
+#define js_Anchor_h
+#include "mozilla/Attributes.h"
+#include "js/TypeDecls.h"
+namespace JS {
+/*
+* Protecting non-Value, non-JSObject *, non-JSString * values from collection
+*
+* Most of the time, the garbage collector's conservative stack scanner works
+* behind the scenes, finding all live values and protecting them from being
+* collected. However, when JSAPI client code obtains a pointer to data the
+* scanner does not know about, owned by an object the scanner does know about,
+* Care Must Be Taken.
+*
+* The scanner recognizes only a select set of types: pointers to JSObjects and
+* similar things (JSFunctions, and so on), pointers to JSStrings, and Values.
+* So while the scanner finds all live |JSString| pointers, it does not notice
+* |jschar| pointers.
+*
+* So suppose we have:
+*
+*   void f(JSString *str) {
+*     const jschar *ch = JS_GetStringCharsZ(str);
+*     ... do stuff with ch, but no uses of str ...;
+*   }
+*
+* After the call to |JS_GetStringCharsZ|, there are no further uses of
+* |str|, which means that the compiler is within its rights to not store
+* it anywhere. But because the stack scanner will not notice |ch|, there
+* is no longer any live value in this frame that would keep the string
+* alive. If |str| is the last reference to that |JSString|, and the
+* collector runs while we are using |ch|, the string's array of |jschar|s
+* may be freed out from under us.
+*
+* Note that there is only an issue when 1) we extract a thing X the scanner
+* doesn't recognize from 2) a thing Y the scanner does recognize, and 3) if Y
+* gets garbage-collected, then X gets freed. If we have code like this:
+*
+*   void g(JSObject *obj) {
+*     JS::Value x;
+*     JS_GetProperty(obj, "x", &x);
+*     ... do stuff with x ...
+*   }
+*
+* there's no problem, because the value we've extracted, x, is a Value, a
+* type that the conservative scanner recognizes.
+*
+* Conservative GC frees us from the obligation to explicitly root the types it
+* knows about, but when we work with derived values like |ch|, we must root
+* their owners, as the derived value alone won't keep them alive.
+*
+* A JS::Anchor is a kind of GC root that allows us to keep the owners of
+* derived values like |ch| alive throughout the Anchor's lifetime. We could
+* fix the above code as follows:
+*
+*   void f(JSString *str) {
+*     JS::Anchor<JSString *> a_str(str);
+*     const jschar *ch = JS_GetStringCharsZ(str);
+*     ... do stuff with ch, but no uses of str ...;
+*   }
+*
+* This simply ensures that |str| will be live until |a_str| goes out of scope.
+* As long as we don't retain a pointer to the string's characters for longer
+* than that, we have avoided all garbage collection hazards.
+*/
+template<typename T> class AnchorPermitted;
+template<> class AnchorPermitted<JSObject *> { };
+template<> class AnchorPermitted<const JSObject *> { };
+template<> class AnchorPermitted<JSFunction *> { };
+template<> class AnchorPermitted<const JSFunction *> { };
+template<> class AnchorPermitted<JSString *> { };
+template<> class AnchorPermitted<const JSString *> { };
+template<> class AnchorPermitted<Value> { };
+template<> class AnchorPermitted<const JSScript *> { };
+template<> class AnchorPermitted<JSScript *> { };
+template<typename T>
+class Anchor : AnchorPermitted<T>
+{
+public:
+Anchor() { }
+explicit Anchor(T t) { hold = t; }
+inline ~Anchor();
+private:
+T hold;
+/*
+* Rooting analysis considers use of operator= to be a use of an anchor.
+* For simplicity, Anchor is treated as if it contained a GC thing, from
+* construction. Thus if we had
+*
+*   void operator=(const T &t) { hold = t; }
+*
+* and this code
+*
+*   JS::Anchor<JSString*> anchor;
+*   stuff that could GC, producing |str|;
+*   anchor = str;
+*
+* the last line would be seen as a hazard, because the final = would "use"
+* |anchor| that is a GC thing -- which could have been moved around by the
+* GC. The workaround is to structure your code so that JS::Anchor is
+* always constructed, living for however long the corresponding value must
+* live.
+*/
+void operator=(const T &t) MOZ_DELETE;
+Anchor(const Anchor &other) MOZ_DELETE;
+void operator=(const Anchor &other) MOZ_DELETE;
+};
+template<typename T>
+inline Anchor<T>::~Anchor()
+{
+#ifdef __GNUC__
+/*
+* No code is generated for this. But because this is marked 'volatile', G++ will
+* assume it has important side-effects, and won't delete it. (G++ never looks at
+* the actual text and notices it's empty.) And because we have passed |hold| to
+* it, GCC will keep |hold| alive until this point.
+*
+* The "memory" clobber operand ensures that G++ will not move prior memory
+* accesses after the asm --- it's a barrier. Unfortunately, it also means that
+* G++ will assume that all memory has changed after the asm, as it would for a
+* call to an unknown function. I don't know of a way to avoid that consequence.
+*/
+asm volatile("":: "g" (hold) : "memory");
+#else
+/*
+* An adequate portable substitute, for non-structure types.
+*
+* The compiler promises that, by the end of an expression statement, the
+* last-stored value to a volatile object is the same as it would be in an
+* unoptimized, direct implementation (the "abstract machine" whose behavior the
+* language spec describes). However, the compiler is still free to reorder
+* non-volatile accesses across this store --- which is what we must prevent. So
+* assigning the held value to a volatile variable, as we do here, is not enough.
+*
+* In our case, however, garbage collection only occurs at function calls, so it
+* is sufficient to ensure that the destructor's store isn't moved earlier across
+* any function calls that could collect. It is hard to imagine the compiler
+* analyzing the program so thoroughly that it could prove that such motion was
+* safe. In practice, compilers treat calls to the collector as opaque operations
+* --- in particular, as operations which could access volatile variables, across
+* which this destructor must not be moved.
+*
+* ("Objection, your honor!  *Alleged* killer whale!")
+*
+* The disadvantage of this approach is that it does generate code for the store.
+* We do need to use Anchors in some cases where cycles are tight.
+*
+* Note that there is a Anchor<Value>::~Anchor() specialization in Value.h.
+*/
+volatile T sink;
+sink = hold;
+#endif  /* defined(__GNUC__) */
+}
+} // namespace JS
+#endif /* js_Anchor_h */

The Tor Browser / file comparison

comparison: js/public/Anchor.h

js/public/Anchor.h