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

--1:000000000000
+:4fc6561b1e54
+/* -*- 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/. */
+/*
+* Helper classes encapsulating access to the callee, |this| value, arguments,
+* and argument count for a function call.
+*
+* The intent of JS::CallArgs and JS::CallReceiver is that they be used to
+* encapsulate access to the un-abstracted |unsigned argc, Value *vp| arguments
+* to a function.  It's possible (albeit deprecated) to manually index into
+* |vp| to access the callee, |this|, and arguments of a function, and to set
+* its return value.  It's also possible to use the supported API of JS_CALLEE,
+* JS_THIS, JS_ARGV, JS_RVAL and JS_SET_RVAL to the same ends.  But neither API
+* has the error-handling or moving-GC correctness of CallArgs or CallReceiver.
+* New code should use CallArgs and CallReceiver instead whenever possible.
+*
+* The eventual plan is to change JSNative to take |const CallArgs&| directly,
+* for automatic assertion of correct use and to make calling functions more
+* efficient.  Embedders should start internally switching away from using
+* |argc| and |vp| directly, except to create a |CallArgs|.  Then, when an
+* eventual release making that change occurs, porting efforts will require
+* changing methods' signatures but won't require invasive changes to the
+* methods' implementations, potentially under time pressure.
+*/
+#ifndef js_CallArgs_h
+#define js_CallArgs_h
+#include "mozilla/Assertions.h"
+#include "mozilla/Attributes.h"
+#include "mozilla/TypeTraits.h"
+#include "jstypes.h"
+#include "js/RootingAPI.h"
+#include "js/Value.h"
+/* Typedef for native functions called by the JS VM. */
+typedef bool
+(* JSNative)(JSContext *cx, unsigned argc, JS::Value *vp);
+/* Typedef for native functions that may be called in parallel. */
+typedef bool
+(* JSParallelNative)(js::ForkJoinContext *cx, unsigned argc, JS::Value *vp);
+/*
+* Typedef for native functions that may be called either in parallel or
+* sequential execution.
+*/
+typedef bool
+(* JSThreadSafeNative)(js::ThreadSafeContext *cx, unsigned argc, JS::Value *vp);
+/*
+* Convenience wrappers for passing in ThreadSafeNative to places that expect
+* a JSNative or a JSParallelNative.
+*/
+template <JSThreadSafeNative threadSafeNative>
+inline bool
+JSNativeThreadSafeWrapper(JSContext *cx, unsigned argc, JS::Value *vp);
+template <JSThreadSafeNative threadSafeNative>
+inline bool
+JSParallelNativeThreadSafeWrapper(js::ForkJoinContext *cx, unsigned argc, JS::Value *vp);
+/*
+* Compute |this| for the |vp| inside a JSNative, either boxing primitives or
+* replacing with the global object as necessary.
+*
+* This method will go away at some point: instead use |args.thisv()|.  If the
+* value is an object, no further work is required.  If that value is |null| or
+* |undefined|, use |JS_GetGlobalForObject| to compute the global object.  If
+* the value is some other primitive, use |JS_ValueToObject| to box it.
+*/
+extern JS_PUBLIC_API(JS::Value)
+JS_ComputeThis(JSContext *cx, JS::Value *vp);
+namespace JS {
+extern JS_PUBLIC_DATA(const HandleValue) UndefinedHandleValue;
+/*
+* JS::CallReceiver encapsulates access to the callee, |this|, and eventual
+* return value for a function call.  The principal way to create a
+* CallReceiver is using JS::CallReceiverFromVp:
+*
+*   static bool
+*   FunctionReturningThis(JSContext *cx, unsigned argc, JS::Value *vp)
+*   {
+*       JS::CallReceiver rec = JS::CallReceiverFromVp(vp);
+*
+*       // Access to the callee must occur before accessing/setting
+*       // the return value.
+*       JSObject &callee = rec.callee();
+*       rec.rval().set(JS::ObjectValue(callee));
+*
+*       // callee() and calleev() will now assert.
+*
+*       // It's always fine to access thisv().
+*       HandleValue thisv = rec.thisv();
+*       rec.rval().set(thisv);
+*
+*       // As the return value was last set to |this|, returns |this|.
+*       return true;
+*   }
+*
+* A note on JS_ComputeThis and JS_THIS_OBJECT: these methods currently aren't
+* part of the CallReceiver interface.  We will likely add them at some point.
+* Until then, you should probably continue using |vp| directly for these two
+* cases.
+*
+* CallReceiver is exposed publicly and used internally.  Not all parts of its
+* public interface are meant to be used by embedders!  See inline comments to
+* for details.
+*/
+namespace detail {
+#ifdef JS_DEBUG
+extern JS_PUBLIC_API(void)
+CheckIsValidConstructible(Value v);
+#endif
+enum UsedRval { IncludeUsedRval, NoUsedRval };
+template<UsedRval WantUsedRval>
+class MOZ_STACK_CLASS UsedRvalBase;
+template<>
+class MOZ_STACK_CLASS UsedRvalBase<IncludeUsedRval>
+{
+protected:
+mutable bool usedRval_;
+void setUsedRval() const { usedRval_ = true; }
+void clearUsedRval() const { usedRval_ = false; }
+};
+template<>
+class MOZ_STACK_CLASS UsedRvalBase<NoUsedRval>
+{
+protected:
+void setUsedRval() const {}
+void clearUsedRval() const {}
+};
+template<UsedRval WantUsedRval>
+class MOZ_STACK_CLASS CallReceiverBase : public UsedRvalBase<
+#ifdef JS_DEBUG
+WantUsedRval
+#else
+NoUsedRval
+#endif
+>
+{
+protected:
+Value *argv_;
+public:
+/*
+* Returns the function being called, as an object.  Must not be called
+* after rval() has been used!
+*/
+JSObject &callee() const {
+MOZ_ASSERT(!this->usedRval_);
+return argv_[-2].toObject();
+}
+/*
+* Returns the function being called, as a value.  Must not be called after
+* rval() has been used!
+*/
+HandleValue calleev() const {
+MOZ_ASSERT(!this->usedRval_);
+return HandleValue::fromMarkedLocation(&argv_[-2]);
+}
+/*
+* Returns the |this| value passed to the function.  This method must not
+* be called when the function is being called as a constructor via |new|.
+* The value may or may not be an object: it is the individual function's
+* responsibility to box the value if needed.
+*/
+HandleValue thisv() const {
+// Some internal code uses thisv() in constructing cases, so don't do
+// this yet.
+// MOZ_ASSERT(!argv_[-1].isMagic(JS_IS_CONSTRUCTING));
+return HandleValue::fromMarkedLocation(&argv_[-1]);
+}
+Value computeThis(JSContext *cx) const {
+if (thisv().isObject())
+return thisv();
+return JS_ComputeThis(cx, base());
+}
+bool isConstructing() const {
+#ifdef JS_DEBUG
+if (this->usedRval_)
+CheckIsValidConstructible(calleev());
+#endif
+return argv_[-1].isMagic();
+}
+/*
+* Returns the currently-set return value.  The initial contents of this
+* value are unspecified.  Once this method has been called, callee() and
+* calleev() can no longer be used.  (If you're compiling against a debug
+* build of SpiderMonkey, these methods will assert to aid debugging.)
+*
+* If the method you're implementing succeeds by returning true, you *must*
+* set this.  (SpiderMonkey doesn't currently assert this, but it will do
+* so eventually.)  You don't need to use or change this if your method
+* fails.
+*/
+MutableHandleValue rval() const {
+this->setUsedRval();
+return MutableHandleValue::fromMarkedLocation(&argv_[-2]);
+}
+public:
+// These methods are only intended for internal use.  Embedders shouldn't
+// use them!
+Value *base() const { return argv_ - 2; }
+Value *spAfterCall() const {
+this->setUsedRval();
+return argv_ - 1;
+}
+public:
+// These methods are publicly exposed, but they are *not* to be used when
+// implementing a JSNative method and encapsulating access to |vp| within
+// it.  You probably don't want to use these!
+void setCallee(Value aCalleev) const {
+this->clearUsedRval();
+argv_[-2] = aCalleev;
+}
+void setThis(Value aThisv) const {
+argv_[-1] = aThisv;
+}
+MutableHandleValue mutableThisv() const {
+return MutableHandleValue::fromMarkedLocation(&argv_[-1]);
+}
+};
+} // namespace detail
+class MOZ_STACK_CLASS CallReceiver : public detail::CallReceiverBase<detail::IncludeUsedRval>
+{
+private:
+friend CallReceiver CallReceiverFromVp(Value *vp);
+friend CallReceiver CallReceiverFromArgv(Value *argv);
+};
+MOZ_ALWAYS_INLINE CallReceiver
+CallReceiverFromArgv(Value *argv)
+{
+CallReceiver receiver;
+receiver.clearUsedRval();
+receiver.argv_ = argv;
+return receiver;
+}
+MOZ_ALWAYS_INLINE CallReceiver
+CallReceiverFromVp(Value *vp)
+{
+return CallReceiverFromArgv(vp + 2);
+}
+/*
+* JS::CallArgs encapsulates everything JS::CallReceiver does, plus access to
+* the function call's arguments.  The principal way to create a CallArgs is
+* like so, using JS::CallArgsFromVp:
+*
+*   static bool
+*   FunctionReturningArgcTimesArg0(JSContext *cx, unsigned argc, JS::Value *vp)
+*   {
+*       JS::CallArgs args = JS::CallArgsFromVp(argc, vp);
+*
+*       // Guard against no arguments or a non-numeric arg0.
+*       if (args.length() == 0 || !args[0].isNumber()) {
+*           args.rval().setInt32(0);
+*           return true;
+*       }
+*
+*       args.rval().set(JS::NumberValue(args.length() * args[0].toNumber()));
+*       return true;
+*   }
+*
+* CallArgs is exposed publicly and used internally.  Not all parts of its
+* public interface are meant to be used by embedders!  See inline comments to
+* for details.
+*/
+namespace detail {
+template<UsedRval WantUsedRval>
+class MOZ_STACK_CLASS CallArgsBase :
+public mozilla::Conditional<WantUsedRval == detail::IncludeUsedRval,
+CallReceiver,
+CallReceiverBase<NoUsedRval> >::Type
+{
+protected:
+unsigned argc_;
+public:
+/* Returns the number of arguments. */
+unsigned length() const { return argc_; }
+/* Returns the i-th zero-indexed argument. */
+MutableHandleValue operator[](unsigned i) const {
+MOZ_ASSERT(i < argc_);
+return MutableHandleValue::fromMarkedLocation(&this->argv_[i]);
+}
+/*
+* Returns the i-th zero-indexed argument, or |undefined| if there's no
+* such argument.
+*/
+HandleValue get(unsigned i) const {
+return i < length()
+? HandleValue::fromMarkedLocation(&this->argv_[i])
+: UndefinedHandleValue;
+}
+/*
+* Returns true if the i-th zero-indexed argument is present and is not
+* |undefined|.
+*/
+bool hasDefined(unsigned i) const {
+return i < argc_ && !this->argv_[i].isUndefined();
+}
+public:
+// These methods are publicly exposed, but we're less sure of the interface
+// here than we'd like (because they're hackish and drop assertions).  Try
+// to avoid using these if you can.
+Value *array() const { return this->argv_; }
+Value *end() const { return this->argv_ + argc_; }
+};
+} // namespace detail
+class MOZ_STACK_CLASS CallArgs : public detail::CallArgsBase<detail::IncludeUsedRval>
+{
+private:
+friend CallArgs CallArgsFromVp(unsigned argc, Value *vp);
+friend CallArgs CallArgsFromSp(unsigned argc, Value *sp);
+static CallArgs create(unsigned argc, Value *argv) {
+CallArgs args;
+args.clearUsedRval();
+args.argv_ = argv;
+args.argc_ = argc;
+return args;
+}
+};
+MOZ_ALWAYS_INLINE CallArgs
+CallArgsFromVp(unsigned argc, Value *vp)
+{
+return CallArgs::create(argc, vp + 2);
+}
+// This method is only intended for internal use in SpiderMonkey.  We may
+// eventually move it to an internal header.  Embedders should use
+// JS::CallArgsFromVp!
+MOZ_ALWAYS_INLINE CallArgs
+CallArgsFromSp(unsigned argc, Value *sp)
+{
+return CallArgs::create(argc, sp - argc);
+}
+} // namespace JS
+/*
+* Macros to hide interpreter stack layout details from a JSNative using its
+* JS::Value *vp parameter.  DO NOT USE THESE!  Instead use JS::CallArgs and
+* friends, above.  These macros will be removed when we change JSNative to
+* take a const JS::CallArgs&.
+*/
+#define JS_THIS_OBJECT(cx,vp)   (JSVAL_TO_OBJECT(JS_THIS(cx,vp)))
+/*
+* Note: if this method returns null, an error has occurred and must be
+* propagated or caught.
+*/
+MOZ_ALWAYS_INLINE JS::Value
+JS_THIS(JSContext *cx, JS::Value *vp)
+{
+return JSVAL_IS_PRIMITIVE(vp[1]) ? JS_ComputeThis(cx, vp) : vp[1];
+}
+/*
+* |this| is passed to functions in ES5 without change.  Functions themselves
+* do any post-processing they desire to box |this|, compute the global object,
+* &c.  This macro retrieves a function's unboxed |this| value.
+*
+* This macro must not be used in conjunction with JS_THIS or JS_THIS_OBJECT,
+* or vice versa.  Either use the provided this value with this macro, or
+* compute the boxed |this| value using those.  JS_THIS_VALUE must not be used
+* if the function is being called as a constructor.
+*
+* But: DO NOT USE THIS!  Instead use JS::CallArgs::thisv(), above.
+*
+*/
+#define JS_THIS_VALUE(cx,vp)    ((vp)[1])
+#endif /* js_CallArgs_h */

The Tor Browser / file comparison

comparison: js/public/CallArgs.h

js/public/CallArgs.h