js/public/Anchor.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  * vim: set ts=8 sts=4 et sw=4 tw=99:
   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 /* JS::Anchor implementation. */
   8
   9 #ifndef js_Anchor_h
  10 #define js_Anchor_h
  11
  12 #include "mozilla/Attributes.h"
  13
  14 class JSFunction;
  15 class JSObject;
  16 class JSScript;
  17 class JSString;
  18
  19 namespace JS { class Value; }
  20
  21 namespace JS {
  22
  23 /*
  24  * Protecting non-Value, non-JSObject *, non-JSString * values from collection
  25  *
  26  * Most of the time, the garbage collector's conservative stack scanner works
  27  * behind the scenes, finding all live values and protecting them from being
  28  * collected. However, when JSAPI client code obtains a pointer to data the
  29  * scanner does not know about, owned by an object the scanner does know about,
  30  * Care Must Be Taken.
  31  *
  32  * The scanner recognizes only a select set of types: pointers to JSObjects and
  33  * similar things (JSFunctions, and so on), pointers to JSStrings, and Values.
  34  * So while the scanner finds all live |JSString| pointers, it does not notice
  35  * |jschar| pointers.
  36  *
  37  * So suppose we have:
  38  *
  39  *   void f(JSString *str) {
  40  *     const jschar *ch = JS_GetStringCharsZ(str);
  41  *     ... do stuff with ch, but no uses of str ...;
  42  *   }
  43  *
  44  * After the call to |JS_GetStringCharsZ|, there are no further uses of
  45  * |str|, which means that the compiler is within its rights to not store
  46  * it anywhere. But because the stack scanner will not notice |ch|, there
  47  * is no longer any live value in this frame that would keep the string
  48  * alive. If |str| is the last reference to that |JSString|, and the
  49  * collector runs while we are using |ch|, the string's array of |jschar|s
  50  * may be freed out from under us.
  51  *
  52  * Note that there is only an issue when 1) we extract a thing X the scanner
  53  * doesn't recognize from 2) a thing Y the scanner does recognize, and 3) if Y
  54  * gets garbage-collected, then X gets freed. If we have code like this:
  55  *
  56  *   void g(JSObject *obj) {
  57  *     JS::Value x;
  58  *     JS_GetProperty(obj, "x", &x);
  59  *     ... do stuff with x ...
  60  *   }
  61  *
  62  * there's no problem, because the value we've extracted, x, is a Value, a
  63  * type that the conservative scanner recognizes.
  64  *
  65  * Conservative GC frees us from the obligation to explicitly root the types it
  66  * knows about, but when we work with derived values like |ch|, we must root
  67  * their owners, as the derived value alone won't keep them alive.
  68  *
  69  * A JS::Anchor is a kind of GC root that allows us to keep the owners of
  70  * derived values like |ch| alive throughout the Anchor's lifetime. We could
  71  * fix the above code as follows:
  72  *
  73  *   void f(JSString *str) {
  74  *     JS::Anchor<JSString *> a_str(str);
  75  *     const jschar *ch = JS_GetStringCharsZ(str);
  76  *     ... do stuff with ch, but no uses of str ...;
  77  *   }
  78  *
  79  * This simply ensures that |str| will be live until |a_str| goes out of scope.
  80  * As long as we don't retain a pointer to the string's characters for longer
  81  * than that, we have avoided all garbage collection hazards.
  82  */
  83 template<typename T> class AnchorPermitted;
  84 template<> class AnchorPermitted<JSObject *> { };
  85 template<> class AnchorPermitted<const JSObject *> { };
  86 template<> class AnchorPermitted<JSFunction *> { };
  87 template<> class AnchorPermitted<const JSFunction *> { };
  88 template<> class AnchorPermitted<JSString *> { };
  89 template<> class AnchorPermitted<const JSString *> { };
  90 template<> class AnchorPermitted<Value> { };
  91 template<> class AnchorPermitted<const JSScript *> { };
  92 template<> class AnchorPermitted<JSScript *> { };
  93
  94 template<typename T>
  95 class Anchor : AnchorPermitted<T>
  96 {
  97   public:
  98     Anchor() { }
  99     explicit Anchor(T t) { hold = t; }
 100     inline ~Anchor();
 101     T &get() { return hold; }
 102     const T &get() const { return hold; }
 103     void set(const T &t) { hold = t; }
 104     void operator=(const T &t) { hold = t; }
 105     void clear() { hold = 0; }
 106
 107   private:
 108     T hold;
 109     Anchor(const Anchor &other) MOZ_DELETE;
 110     void operator=(const Anchor &other) MOZ_DELETE;
 111 };
 112
 113 template<typename T>
 114 inline Anchor<T>::~Anchor()
 115 {
 116 #ifdef __GNUC__
 117     /*
 118      * No code is generated for this. But because this is marked 'volatile', G++ will
 119      * assume it has important side-effects, and won't delete it. (G++ never looks at
 120      * the actual text and notices it's empty.) And because we have passed |hold| to
 121      * it, GCC will keep |hold| alive until this point.
 122      *
 123      * The "memory" clobber operand ensures that G++ will not move prior memory
 124      * accesses after the asm --- it's a barrier. Unfortunately, it also means that
 125      * G++ will assume that all memory has changed after the asm, as it would for a
 126      * call to an unknown function. I don't know of a way to avoid that consequence.
 127      */
 128     asm volatile("":: "g" (hold) : "memory");
 129 #else
 130     /*
 131      * An adequate portable substitute, for non-structure types.
 132      *
 133      * The compiler promises that, by the end of an expression statement, the
 134      * last-stored value to a volatile object is the same as it would be in an
 135      * unoptimized, direct implementation (the "abstract machine" whose behavior the
 136      * language spec describes). However, the compiler is still free to reorder
 137      * non-volatile accesses across this store --- which is what we must prevent. So
 138      * assigning the held value to a volatile variable, as we do here, is not enough.
 139      *
 140      * In our case, however, garbage collection only occurs at function calls, so it
 141      * is sufficient to ensure that the destructor's store isn't moved earlier across
 142      * any function calls that could collect. It is hard to imagine the compiler
 143      * analyzing the program so thoroughly that it could prove that such motion was
 144      * safe. In practice, compilers treat calls to the collector as opaque operations
 145      * --- in particular, as operations which could access volatile variables, across
 146      * which this destructor must not be moved.
 147      *
 148      * ("Objection, your honor!  *Alleged* killer whale!")
 149      *
 150      * The disadvantage of this approach is that it does generate code for the store.
 151      * We do need to use Anchors in some cases where cycles are tight.
 152      *
 153      * Note that there is a Anchor<Value>::~Anchor() specialization in Value.h.
 154      */
 155     volatile T sink;
 156     sink = hold;
 157 #endif  /* defined(__GNUC__) */
 158 }
 159
 160 } // namespace JS
 161
 162 #endif /* js_Anchor_h */