CallNonGenericMethod.h (4846B)
1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- 2 * vim: set ts=8 sts=2 et sw=2 tw=80: 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 #ifndef js_CallNonGenericMethod_h 8 #define js_CallNonGenericMethod_h 9 10 #include "jstypes.h" 11 12 #include "js/CallArgs.h" 13 14 namespace JS { 15 16 // Returns true if |v| is considered an acceptable this-value. 17 typedef bool (*IsAcceptableThis)(HandleValue v); 18 19 // Implements the guts of a method; guaranteed to be provided an acceptable 20 // this-value, as determined by a corresponding IsAcceptableThis method. 21 typedef bool (*NativeImpl)(JSContext* cx, const CallArgs& args); 22 23 namespace detail { 24 25 // DON'T CALL THIS DIRECTLY. It's for use only by CallNonGenericMethod! 26 extern JS_PUBLIC_API bool CallMethodIfWrapped(JSContext* cx, 27 IsAcceptableThis test, 28 NativeImpl impl, 29 const CallArgs& args); 30 31 } // namespace detail 32 33 // Methods usually act upon |this| objects only from a single global object and 34 // compartment. Sometimes, however, a method must act upon |this| values from 35 // multiple global objects or compartments. In such cases the |this| value a 36 // method might see will be wrapped, such that various access to the object -- 37 // to its class, its private data, its reserved slots, and so on -- will not 38 // work properly without entering that object's compartment. This method 39 // implements a solution to this problem. 40 // 41 // To implement a method that accepts |this| values from multiple compartments, 42 // define two functions. The first function matches the IsAcceptableThis type 43 // and indicates whether the provided value is an acceptable |this| for the 44 // method; it must be a pure function only of its argument. 45 // 46 // static const JSClass AnswerClass = { ... }; 47 // 48 // static bool 49 // IsAnswerObject(const Value& v) 50 // { 51 // if (!v.isObject()) { 52 // return false; 53 // } 54 // return JS_GetClass(&v.toObject()) == &AnswerClass; 55 // } 56 // 57 // The second function implements the NativeImpl signature and defines the 58 // behavior of the method when it is provided an acceptable |this| value. 59 // Aside from some typing niceties -- see the CallArgs interface for details -- 60 // its interface is the same as that of JSNative. 61 // 62 // static bool 63 // answer_getAnswer_impl(JSContext* cx, const JS::CallArgs& args) 64 // { 65 // args.rval().setInt32(42); 66 // return true; 67 // } 68 // 69 // The implementation function is guaranteed to be called *only* with a |this| 70 // value which is considered acceptable. 71 // 72 // Now to implement the actual method, write a JSNative that calls the method 73 // declared below, passing the appropriate template and runtime arguments. 74 // 75 // static bool 76 // answer_getAnswer(JSContext* cx, unsigned argc, JS::Value* vp) 77 // { 78 // JS::CallArgs args = JS::CallArgsFromVp(argc, vp); 79 // return JS::CallNonGenericMethod<IsAnswerObject, 80 // answer_getAnswer_impl>(cx, args); 81 // } 82 // 83 // Note that, because they are used as template arguments, the predicate 84 // and implementation functions must have external linkage. (This is 85 // unfortunate, but GCC wasn't inlining things as one would hope when we 86 // passed them as function arguments.) 87 // 88 // JS::CallNonGenericMethod will test whether |args.thisv()| is acceptable. If 89 // it is, it will call the provided implementation function, which will return 90 // a value and indicate success. If it is not, it will attempt to unwrap 91 // |this| and call the implementation function on the unwrapped |this|. If 92 // that succeeds, all well and good. If it doesn't succeed, a TypeError will 93 // be thrown. 94 // 95 // Note: JS::CallNonGenericMethod will only work correctly if it's called in 96 // tail position in a JSNative. Do not call it from any other place. 97 // 98 template <IsAcceptableThis Test, NativeImpl Impl> 99 MOZ_ALWAYS_INLINE bool CallNonGenericMethod(JSContext* cx, 100 const CallArgs& args) { 101 HandleValue thisv = args.thisv(); 102 if (Test(thisv)) { 103 return Impl(cx, args); 104 } 105 106 return detail::CallMethodIfWrapped(cx, Test, Impl, args); 107 } 108 109 MOZ_ALWAYS_INLINE bool CallNonGenericMethod(JSContext* cx, 110 IsAcceptableThis Test, 111 NativeImpl Impl, 112 const CallArgs& args) { 113 HandleValue thisv = args.thisv(); 114 if (Test(thisv)) { 115 return Impl(cx, args); 116 } 117 118 return detail::CallMethodIfWrapped(cx, Test, Impl, args); 119 } 120 121 } // namespace JS 122 123 #endif /* js_CallNonGenericMethod_h */