jsval/JSAPI changes

[Luke Wagner]

Very soon, the "fatval" branch (bug 549143) will be merging with TM.
This post is about the changes to the JS API. I would have liked to
have posted this information earlier, but the exact details have been in
flux until recently. (There is also a new API for values (js::Value)
which is SM-internal and described in more detail at the top of jsvalue.h.)

In a nutshell, the major changes are:

- jsval is no longer word-sized
- jsval can holds a full int32
- doubles are stored in the jsval; JSVAL_TO_DOUBLE returns double
- jsval and jsid no longer share the same representation
- JSClass method signatures have been modified to take jsids for id
arguments and pass jsval arguments by const jsval*.

In more detail:

JSVAL_* operations cannot be used on jsids, a new (more precise) set of
jsid operations/constants are provided:

JSID_IS_INT / JSID_TO_INT / INT_TO_JSID / JSID_INT_MIN / JSID_INT_MAX
JSID_IS_OBJECT / JSID_TO_OBJECT / OBJECT_TO_JSID
JSID_IS_STRING / JSID_TO_STRING / INTERNED_STRING_TO_JSID
JSID_IS_VOID / JSID_VOID
JSID_IS_DEFAULT_XML_NAMESPACE / JS_DEFAULT_XML_NAMESPACE_ID

which are straightforward replacements for their JSVAL_* counterparts.

When DEBUG is not defined, jsval and jsid are (different) integral
builtin types. To avoid implicit conversions between the two (which,
previously, was mostly valid but now is totally wrong), in debug builds
jsval and jsid are given different struct types. Default struct
assignment and (in C++) operator== allows must code not observe the
difference. This feature can be disabled by defining
JS_NO_JSVAL_JSID_STRUCT_TYPES when building SM.

JSVAL_IS_SPECIAL/JSVAL_TO_SPECIAL has been removed. While this is in
jsapi.h, it is an implementation detail; embeddings should only be using
JSVAL_IS_BOOLEAN/JSVAL_TO_BOOLEAN/BOOLEAN_TO_JSVAL.

JS_MarkGCThing was changed to take a jsval, not a void*. Embeddings
using this API should consider using the new (unfortunately named)
"tracing" GC API.

JSGCRootMapFun, the callback type for JS_MapGCRoots, is changed to take
an additional parameter which tells whether the given void* is a jsval*
or void** (GC-thing), since it is no longer possible to tell the
difference by looking at the bits.

JS_NewDoubleValue, which was deprecated, has been removed. In its
place, DOUBLE_TO_JSVAL or JS_NewNumberValue can be used, depending on
whether the caller wants doubles to be tested for whether they fit in an
int.

The particular signatures used in JSClass that have been changed are:

JSPropertyOp
JSResolveOp
JSNewResolveOp
JSCheckAccessOp

The only change made is switching "jsval id" parameters to "jsid id" and
switching "jsval v" parameters to "const jsval *v". The latter was done
due to the measured performance benefit of passing 64-bit values by
pointer on 32-bit systems. The struct types should catch type errors
involving these. However, beware function-pointer casts (viz. from a
JSNewResolveOp to a JSResolveOp), since these thwart the type system.

If you have any questions, feel free to reply here or ping me on #jsapi
(handle: luke).

[Luke Wagner]

I forgot to mention:

The type of jsval produced by PRIVATE_TO_JSVAL is no longer an int.
(PRIVATE_TO_JSVAL currently produces a double, but embeddings should not
rely on any particular underlying type of a privatized jsval.)

[Boris Zbarsky]

On 7/14/10 5:51 PM, Luke Wagner wrote:
> The latter was done
> due to the measured performance benefit of passing 64-bit values by
> pointer on 32-bit systems.

Going forward, as we move to 64-bit more and more, are we going to
revisit that?

-Boris

[Salvador Ortiz Garcia]

On 07/14/2010 04:51 PM, Luke Wagner wrote:
> Very soon, the "fatval" branch (bug 549143) will be merging with TM.
> This post is about the changes to the JS API. I would have liked to
> have posted this information earlier, but the exact details have been
> in flux until recently. (There is also a new API for values
> (js::Value) which is SM-internal and described in more detail at the
> top of jsvalue.h.)
>

Can I assume that the proper way of detection should be a simple
JS_VERSION >= 185?

Regards.

Salvador Ortiz.

[Wes Garland]

Hi, Luke!

This is great news, I look forward to the improved performance!

> JS_MarkGCThing was changed to take a jsval, not a void*. Embeddings using
this API should consider
> using the new (unfortunately named) "tracing" GC API.

Can we have a way to detect this from the pre-compiler, so that we can write
code which write with both current and older tracemonkies?

Or should we consider this part of the new rooting API, and consider
versions between <when that define appeared> and <when fatvals land>
"buggy"?

Wes

--
Wesley W. Garland
Director, Product Development
PageMail, Inc.
+1 613 542 2787 x 102

[Luke Wagner]

I would be happy to. I experimented with, at several points in
development, just passing by value, but each time had a measurable 2-3%
drop in SS/V8. I considered having the parameter type be a
platform-dependent typedef, but, since we can't use 'const jsval&' in
the C API, this would require some annoying changes to write code that
compiled with both 'const jsval *' and 'jsval'.

[Luke Wagner]

I forgot to CC the newsgroup on my reply to this.

> Can we have a way to detect this from the pre-compiler, so that we can write
> code which write with both current and older tracemonkies?
>
> Or should we consider this part of the new rooting API, and consider
> versions between<when that define appeared> and<when fatvals land>
> "buggy"?

Yes, that sounds good.

[Luke Wagner]

I'm sorry for the delayed response. I personally don't know the answer;
I was hoping for someone else to chime in.