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