js/public/CallNonGenericMethod.h

   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, 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 */