Magic-Mirror/gecko-dev
1
0
Fork 0
mirror of https://github.com/mozilla/gecko-dev.git synced 2024-11-25 05:41:12 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Bug 1212663 - Use doxygen style comments in jsapi, r=Waldo

Browse Source
This commit is contained in:
Michael Wu 2015-10-17 13:27:16 -04:00
parent eaaf58dece
commit ed4b205b47
12 changed files with 856 additions and 688 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

229
js/public/Class.h
View File

@ -46,8 +46,10 @@ template <typename T>
class AutoVectorRooter;
typedef AutoVectorRooter<jsid> AutoIdVector;
// The answer to a successful query as to whether an object is an Array per
// ES6's internal |IsArray| operation (as exposed by |Array.isArray|).
/**
* The answer to a successful query as to whether an object is an Array per
* ES6's internal |IsArray| operation (as exposed by |Array.isArray|).
*/
enum class IsArrayAnswer
{
Array,
@ -55,29 +57,33 @@ enum class IsArrayAnswer
RevokedProxy
};
// ES6 7.2.2.
//
// Returns false on failure, otherwise returns true and sets |*isArray|
// indicating whether the object passes ECMAScript's IsArray test. This is the
// same test performed by |Array.isArray|.
//
// This is NOT the same as asking whether |obj| is an Array or a wrapper around
// one. If |obj| is a proxy created by |Proxy.revocable()| and has been
// revoked, or if |obj| is a proxy whose target (at any number of hops) is a
// revoked proxy, this method throws a TypeError and returns false.
/**
* ES6 7.2.2.
*
* Returns false on failure, otherwise returns true and sets |*isArray|
* indicating whether the object passes ECMAScript's IsArray test. This is the
* same test performed by |Array.isArray|.
*
* This is NOT the same as asking whether |obj| is an Array or a wrapper around
* one. If |obj| is a proxy created by |Proxy.revocable()| and has been
* revoked, or if |obj| is a proxy whose target (at any number of hops) is a
* revoked proxy, this method throws a TypeError and returns false.
*/
extern JS_PUBLIC_API(bool)
IsArray(JSContext* cx, HandleObject obj, bool* isArray);
// Identical to IsArray above, but the nature of the object (if successfully
// determined) is communicated via |*answer|. In particular this method
// returns true and sets |*answer = IsArrayAnswer::RevokedProxy| when called on
// a revoked proxy.
//
// Most users will want the overload above, not this one.
/**
* Identical to IsArray above, but the nature of the object (if successfully
* determined) is communicated via |*answer|. In particular this method
* returns true and sets |*answer = IsArrayAnswer::RevokedProxy| when called on
* a revoked proxy.
*
* Most users will want the overload above, not this one.
*/
extern JS_PUBLIC_API(bool)
IsArray(JSContext* cx, HandleObject obj, IsArrayAnswer* answer);
/*
/**
* Per ES6, the [[DefineOwnProperty]] internal method has three different
* possible outcomes:
*
@ -113,7 +119,7 @@ IsArray(JSContext* cx, HandleObject obj, IsArrayAnswer* answer);
class ObjectOpResult
{
private:
/*
/**
* code_ is either one of the special codes OkCode or Uninitialized, or
* an error code. For now the error codes are private to the JS engine;
* they're defined in js/src/js.msg.
@ -249,117 +255,136 @@ class ObjectOpResult
// JSClass operation signatures.
// Get a property named by id in obj. Note the jsid id type -- id may
// be a string (Unicode property identifier) or an int (element index). The
// *vp out parameter, on success, is the new property value after the action.
/**
* Get a property named by id in obj. Note the jsid id type -- id may
* be a string (Unicode property identifier) or an int (element index). The
* *vp out parameter, on success, is the new property value after the action.
*/
typedef bool
(* JSGetterOp)(JSContext* cx, JS::HandleObject obj, JS::HandleId id,
JS::MutableHandleValue vp);
// Add a property named by id to obj.
/** Add a property named by id to obj. */
typedef bool
(* JSAddPropertyOp)(JSContext* cx, JS::HandleObject obj, JS::HandleId id, JS::HandleValue v);
// Set a property named by id in obj, treating the assignment as strict
// mode code if strict is true. Note the jsid id type -- id may be a string
// (Unicode property identifier) or an int (element index). The *vp out
// parameter, on success, is the new property value after the
// set.
/**
* Set a property named by id in obj, treating the assignment as strict
* mode code if strict is true. Note the jsid id type -- id may be a string
* (Unicode property identifier) or an int (element index). The *vp out
* parameter, on success, is the new property value after the
* set.
*/
typedef bool
(* JSSetterOp)(JSContext* cx, JS::HandleObject obj, JS::HandleId id,
JS::MutableHandleValue vp, JS::ObjectOpResult& result);
// Delete a property named by id in obj.
//
// If an error occurred, return false as per normal JSAPI error practice.
//
// If no error occurred, but the deletion attempt wasn't allowed (perhaps
// because the property was non-configurable), call result.fail() and
// return true. This will cause |delete obj[id]| to evaluate to false in
// non-strict mode code, and to throw a TypeError in strict mode code.
//
// If no error occurred and the deletion wasn't disallowed (this is *not* the
// same as saying that a deletion actually occurred -- deleting a non-existent
// property, or an inherited property, is allowed -- it's just pointless),
// call result.succeed() and return true.
/**
* Delete a property named by id in obj.
*
* If an error occurred, return false as per normal JSAPI error practice.
*
* If no error occurred, but the deletion attempt wasn't allowed (perhaps
* because the property was non-configurable), call result.fail() and
* return true. This will cause |delete obj[id]| to evaluate to false in
* non-strict mode code, and to throw a TypeError in strict mode code.
*
* If no error occurred and the deletion wasn't disallowed (this is *not* the
* same as saying that a deletion actually occurred -- deleting a non-existent
* property, or an inherited property, is allowed -- it's just pointless),
* call result.succeed() and return true.
*/
typedef bool
(* JSDeletePropertyOp)(JSContext* cx, JS::HandleObject obj, JS::HandleId id,
JS::ObjectOpResult& result);
// The type of ObjectOps::enumerate. This callback overrides a portion of
// SpiderMonkey's default [[Enumerate]] internal method. When an ordinary object
// is enumerated, that object and each object on its prototype chain is tested
// for an enumerate op, and those ops are called in order. The properties each
// op adds to the 'properties' vector are added to the set of values the for-in
// loop will iterate over. All of this is nonstandard.
//
// An object is "enumerated" when it's the target of a for-in loop or
// JS_Enumerate(). The callback's job is to populate 'properties' with the
// object's property keys. If `enumerableOnly` is true, the callback should only
// add enumerable properties.
/**
* The type of ObjectOps::enumerate. This callback overrides a portion of
* SpiderMonkey's default [[Enumerate]] internal method. When an ordinary object
* is enumerated, that object and each object on its prototype chain is tested
* for an enumerate op, and those ops are called in order. The properties each
* op adds to the 'properties' vector are added to the set of values the for-in
* loop will iterate over. All of this is nonstandard.
*
* An object is "enumerated" when it's the target of a for-in loop or
* JS_Enumerate(). The callback's job is to populate 'properties' with the
* object's property keys. If `enumerableOnly` is true, the callback should only
* add enumerable properties.
*/
typedef bool
(* JSNewEnumerateOp)(JSContext* cx, JS::HandleObject obj, JS::AutoIdVector& properties,
bool enumerableOnly);
// The old-style JSClass.enumerate op should define all lazy properties not
// yet reflected in obj.
/**
* The old-style JSClass.enumerate op should define all lazy properties not
* yet reflected in obj.
*/
typedef bool
(* JSEnumerateOp)(JSContext* cx, JS::HandleObject obj);
// Resolve a lazy property named by id in obj by defining it directly in obj.
// Lazy properties are those reflected from some peer native property space
// (e.g., the DOM attributes for a given node reflected as obj) on demand.
//
// JS looks for a property in an object, and if not found, tries to resolve
// the given id. *resolvedp should be set to true iff the property was
// was defined on |obj|.
//
/**
* Resolve a lazy property named by id in obj by defining it directly in obj.
* Lazy properties are those reflected from some peer native property space
* (e.g., the DOM attributes for a given node reflected as obj) on demand.
*
* JS looks for a property in an object, and if not found, tries to resolve
* the given id. *resolvedp should be set to true iff the property was
* was defined on |obj|.
*/
typedef bool
(* JSResolveOp)(JSContext* cx, JS::HandleObject obj, JS::HandleId id,
bool* resolvedp);
// A class with a resolve hook can optionally have a mayResolve hook. This hook
// must have no side effects and must return true for a given id if the resolve
// hook may resolve this id. This is useful when we're doing a "pure" lookup: if
// mayResolve returns false, we know we don't have to call the effectful resolve
// hook.
//
// maybeObj, if non-null, is the object on which we're doing the lookup. This
// can be nullptr: during JIT compilation we sometimes know the Class but not
// the object.
/**
* A class with a resolve hook can optionally have a mayResolve hook. This hook
* must have no side effects and must return true for a given id if the resolve
* hook may resolve this id. This is useful when we're doing a "pure" lookup: if
* mayResolve returns false, we know we don't have to call the effectful resolve
* hook.
*
* maybeObj, if non-null, is the object on which we're doing the lookup. This
* can be nullptr: during JIT compilation we sometimes know the Class but not
* the object.
*/
typedef bool
(* JSMayResolveOp)(const JSAtomState& names, jsid id, JSObject* maybeObj);
// Finalize obj, which the garbage collector has determined to be unreachable
// from other live objects or from GC roots. Obviously, finalizers must never
// store a reference to obj.
/**
* Finalize obj, which the garbage collector has determined to be unreachable
* from other live objects or from GC roots. Obviously, finalizers must never
* store a reference to obj.
*/
typedef void
(* JSFinalizeOp)(JSFreeOp* fop, JSObject* obj);
// Finalizes external strings created by JS_NewExternalString.
/** Finalizes external strings created by JS_NewExternalString. */
struct JSStringFinalizer {
void (*finalize)(const JSStringFinalizer* fin, char16_t* chars);
};
// Check whether v is an instance of obj. Return false on error or exception,
// true on success with true in *bp if v is an instance of obj, false in
// *bp otherwise.
/**
* Check whether v is an instance of obj. Return false on error or exception,
* true on success with true in *bp if v is an instance of obj, false in
* *bp otherwise.
*/
typedef bool
(* JSHasInstanceOp)(JSContext* cx, JS::HandleObject obj, JS::MutableHandleValue vp,
bool* bp);
// Function type for trace operation of the class called to enumerate all
// traceable things reachable from obj's private data structure. For each such
// thing, a trace implementation must call one of the JS_Call*Tracer variants
// on the thing.
//
// JSTraceOp implementation can assume that no other threads mutates object
// state. It must not change state of the object or corresponding native
// structures. The only exception for this rule is the case when the embedding
// needs a tight integration with GC. In that case the embedding can check if
// the traversal is a part of the marking phase through calling
// JS_IsGCMarkingTracer and apply a special code like emptying caches or
// marking its native structures.
/**
* Function type for trace operation of the class called to enumerate all
* traceable things reachable from obj's private data structure. For each such
* thing, a trace implementation must call one of the JS_Call*Tracer variants
* on the thing.
*
* JSTraceOp implementation can assume that no other threads mutates object
* state. It must not change state of the object or corresponding native
* structures. The only exception for this rule is the case when the embedding
* needs a tight integration with GC. In that case the embedding can check if
* the traversal is a part of the marking phase through calling
* JS_IsGCMarkingTracer and apply a special code like emptying caches or
* marking its native structures.
*/
typedef void
(* JSTraceOp)(JSTracer* trc, JSObject* obj);
@ -440,12 +465,14 @@ typedef bool
(* GetElementsOp)(JSContext* cx, JS::HandleObject obj, uint32_t begin, uint32_t end,
ElementAdder* adder);
// A generic type for functions mapping an object to another object, or null
// if an error or exception was thrown on cx.
/**
* A generic type for functions mapping an object to another object, or null
* if an error or exception was thrown on cx.
*/
typedef JSObject*
(* ObjectOp)(JSContext* cx, JS::HandleObject obj);
// Hook to map an object to its inner object. Infallible.
/** Hook to map an object to its inner object. Infallible. */
typedef JSObject*
(* InnerObjectOp)(JSObject* obj);
@ -470,10 +497,10 @@ typedef void
JSNative construct; \
JSTraceOp trace
// Callback for the creation of constructor and prototype objects.
/** Callback for the creation of constructor and prototype objects. */
typedef JSObject* (*ClassObjectCreationOp)(JSContext* cx, JSProtoKey key);
// Callback for custom post-processing after class initialization via ClassSpec.
/** Callback for custom post-processing after class initialization via ClassSpec. */
typedef bool (*FinishClassInitOp)(JSContext* cx, JS::HandleObject ctor,
JS::HandleObject proto);
@ -565,13 +592,13 @@ struct ClassExtension
ObjectOp outerObject;
InnerObjectOp innerObject;
/*
/**
* isWrappedNative is true only if the class is an XPCWrappedNative.
* WeakMaps use this to override the wrapper disposal optimization.
*/
bool isWrappedNative;
/*
/**
* If an object is used as a key in a weakmap, it may be desirable for the
* garbage collector to keep that object around longer than it otherwise
* would. A common case is when the key is a wrapper around an object in
@ -584,7 +611,7 @@ struct ClassExtension
*/
JSWeakmapKeyDelegateOp weakmapKeyDelegateOp;
/*
/**
* Optional hook called when an object is moved by a compacting GC.
*
* There may exist weak pointers to an object that are not traced through
@ -816,7 +843,7 @@ Valueify(const JSClass* c)
return (const Class*)c;
}
/*
/**
* Enumeration describing possible values of the [[Class]] internal property
* value of objects.
*/
@ -825,7 +852,7 @@ enum ESClassValue {
ESClass_Boolean, ESClass_RegExp, ESClass_ArrayBuffer, ESClass_SharedArrayBuffer,
ESClass_Date, ESClass_Set, ESClass_Map,
// None of the above.
/** None of the above. */
ESClass_Other
};

4
js/public/Conversions.h
View File

@ -75,7 +75,7 @@ namespace JS {
namespace detail {
#ifdef JS_DEBUG
/*
/**
* Assert that we're not doing GC on cx, that we're in a request as
* needed, and that the compartments for cx and v are correct.
* Also check that GC would be safe at this point.
@ -89,7 +89,7 @@ inline void AssertArgumentsAreSane(JSContext* cx, HandleValue v)
} // namespace detail
/*
/**
* ES6 draft 20141224, 7.1.1, second algorithm.
*
* Most users shouldn't call this -- use JS::ToBoolean, ToNumber, or ToString

58
js/public/GCAPI.h
View File

@ -22,20 +22,20 @@ struct Statistics;
} // namespace js
typedef enum JSGCMode {
/* Perform only global GCs. */
/** Perform only global GCs. */
JSGC_MODE_GLOBAL = 0,
/* Perform per-compartment GCs until too much garbage has accumulated. */
/** Perform per-compartment GCs until too much garbage has accumulated. */
JSGC_MODE_COMPARTMENT = 1,
/*
/**
* Collect in short time slices rather than all at once. Implies
* JSGC_MODE_COMPARTMENT.
*/
JSGC_MODE_INCREMENTAL = 2
} JSGCMode;
/*
/**
* Kinds of js_GC invocation.
*/
typedef enum JSGCInvocationKind {
@ -146,19 +146,19 @@ enum Reason {
* all zones. Failing to select any zone is an error.
*/
/*
/**
* Schedule the given zone to be collected as part of the next GC.
*/
extern JS_PUBLIC_API(void)
PrepareZoneForGC(Zone* zone);
/*
/**
* Schedule all zones to be collected in the next GC.
*/
extern JS_PUBLIC_API(void)
PrepareForFullGC(JSRuntime* rt);
/*
/**
* When performing an incremental GC, the zones that were selected for the
* previous incremental slice must be selected in subsequent slices as well.
* This function selects those slices automatically.
@ -166,14 +166,14 @@ PrepareForFullGC(JSRuntime* rt);
extern JS_PUBLIC_API(void)
PrepareForIncrementalGC(JSRuntime* rt);
/*
/**
* Returns true if any zone in the system has been scheduled for GC with one of
* the functions above or by the JS engine.
*/
extern JS_PUBLIC_API(bool)
IsGCScheduled(JSRuntime* rt);
/*
/**
* Undoes the effect of the Prepare methods above. The given zone will not be
* collected in the next GC.
*/
@ -186,7 +186,7 @@ SkipZoneForGC(Zone* zone);
* The following functions perform a non-incremental GC.
*/
/*
/**
* Performs a non-incremental collection of all selected zones.
*
* If the gckind argument is GC_NORMAL, then some objects that are unreachable
@ -218,7 +218,7 @@ GCForReason(JSRuntime* rt, JSGCInvocationKind gckind, gcreason::Reason reason);
* non-incremental collections can still happen when low on memory.
*/
/*
/**
* Begin an incremental collection and perform one slice worth of work. When
* this function returns, the collection may not be complete.
* IncrementalGCSlice() must be called repeatedly until
@ -231,7 +231,7 @@ extern JS_PUBLIC_API(void)
StartIncrementalGC(JSRuntime* rt, JSGCInvocationKind gckind, gcreason::Reason reason,
int64_t millis = 0);
/*
/**
* Perform a slice of an ongoing incremental collection. When this function
* returns, the collection may not be complete. It must be called repeatedly
* until !IsIncrementalGCInProgress(rt).
@ -242,7 +242,7 @@ StartIncrementalGC(JSRuntime* rt, JSGCInvocationKind gckind, gcreason::Reason re
extern JS_PUBLIC_API(void)
IncrementalGCSlice(JSRuntime* rt, gcreason::Reason reason, int64_t millis = 0);
/*
/**
* If IsIncrementalGCInProgress(rt), this call finishes the ongoing collection
* by performing an arbitrarily long slice. If !IsIncrementalGCInProgress(rt),
* this is equivalent to GCForReason. When this function returns,
@ -251,7 +251,7 @@ IncrementalGCSlice(JSRuntime* rt, gcreason::Reason reason, int64_t millis = 0);
extern JS_PUBLIC_API(void)
FinishIncrementalGC(JSRuntime* rt, gcreason::Reason reason);
/*
/**
* If IsIncrementalGCInProgress(rt), this call aborts the ongoing collection and
* performs whatever work needs to be done to return the collector to its idle
* state. This may take an arbitrarily long time. When this function returns,
@ -345,7 +345,7 @@ struct JS_PUBLIC_API(GCDescription) {
typedef void
(* GCSliceCallback)(JSRuntime* rt, GCProgress progress, const GCDescription& desc);
/*
/**
* The GC slice callback is called at the beginning and end of each slice. This
* callback may be used for GC notifications as well as to perform additional
* marking.
@ -353,7 +353,7 @@ typedef void
extern JS_PUBLIC_API(GCSliceCallback)
SetGCSliceCallback(JSRuntime* rt, GCSliceCallback callback);
/*
/**
* Incremental GC defaults to enabled, but may be disabled for testing or in
* embeddings that have not yet implemented barriers on their native classes.
* There is not currently a way to re-enable incremental GC once it has been
@ -362,7 +362,7 @@ SetGCSliceCallback(JSRuntime* rt, GCSliceCallback callback);
extern JS_PUBLIC_API(void)
DisableIncrementalGC(JSRuntime* rt);
/*
/**
* Returns true if incremental GC is enabled. Simply having incremental GC
* enabled is not sufficient to ensure incremental collections are happening.
* See the comment "Incremental GC" above for reasons why incremental GC may be
@ -373,7 +373,7 @@ DisableIncrementalGC(JSRuntime* rt);
extern JS_PUBLIC_API(bool)
IsIncrementalGCEnabled(JSRuntime* rt);
/*
/**
* Returns true while an incremental GC is ongoing, both when actively
* collecting and between slices.
*/
@ -404,7 +404,7 @@ IncrementalValueBarrier(const Value& v);
extern JS_PUBLIC_API(void)
IncrementalObjectBarrier(JSObject* obj);
/*
/**
* Returns true if the most recent GC ran incrementally.
*/
extern JS_PUBLIC_API(bool)
@ -418,7 +418,7 @@ WasIncrementalGC(JSRuntime* rt);
* --enable-gcgenerational.
*/
/* Ensure that generational GC is disabled within some scope. */
/** Ensure that generational GC is disabled within some scope. */
class JS_PUBLIC_API(AutoDisableGenerationalGC)
{
js::gc::GCRuntime* gc;
@ -428,14 +428,14 @@ class JS_PUBLIC_API(AutoDisableGenerationalGC)
~AutoDisableGenerationalGC();
};
/*
/**
* Returns true if generational allocation and collection is currently enabled
* on the given runtime.
*/
extern JS_PUBLIC_API(bool)
IsGenerationalGCEnabled(JSRuntime* rt);
/*
/**
* Returns the GC's "number". This does not correspond directly to the number
* of GCs that have been run, but is guaranteed to be monotonically increasing
* with GC activity.
@ -443,7 +443,7 @@ IsGenerationalGCEnabled(JSRuntime* rt);
extern JS_PUBLIC_API(size_t)
GetGCNumber();
/*
/**
* The GC does not immediately return the unused memory freed by a collection
* back to the system incase it is needed soon afterwards. This call forces the
* GC to return this memory immediately.
@ -451,7 +451,7 @@ GetGCNumber();
extern JS_PUBLIC_API(void)
ShrinkGCBuffers(JSRuntime* rt);
/*
/**
* Assert if a GC occurs while this class is live. This class does not disable
* the static rooting hazard analysis.
*/
@ -477,7 +477,7 @@ class JS_PUBLIC_API(AutoAssertOnGC)
#endif
};
/*
/**
* Assert if an allocation of a GC thing occurs while this class is live. This
* class does not disable the static rooting hazard analysis.
*/
@ -499,7 +499,7 @@ class JS_PUBLIC_API(AutoAssertNoAlloc)
#endif
};
/*
/**
* Disable the static rooting hazard analysis in the live region and assert if
* any allocation that could potentially trigger a GC occurs while this guard
* object is live. This is most useful to help the exact rooting hazard analysis
@ -520,7 +520,7 @@ class JS_PUBLIC_API(AutoSuppressGCAnalysis) : public AutoAssertNoAlloc
explicit AutoSuppressGCAnalysis(JSRuntime* rt) : AutoAssertNoAlloc(rt) {}
};
/*
/**
* Assert that code is only ever called from a GC callback, disable the static
* rooting hazard analysis and assert if any allocation that could potentially
* trigger a GC occurs while this guard object is live.
@ -534,7 +534,7 @@ class JS_PUBLIC_API(AutoAssertGCCallback) : public AutoSuppressGCAnalysis
explicit AutoAssertGCCallback(JSObject* obj);
};
/*
/**
* Place AutoCheckCannotGC in scopes that you believe can never GC. These
* annotations will be verified both dynamically via AutoAssertOnGC, and
* statically with the rooting hazard analysis (implemented by making the
@ -551,7 +551,7 @@ class JS_PUBLIC_API(AutoCheckCannotGC) : public AutoAssertOnGC
explicit AutoCheckCannotGC(JSRuntime* rt) : AutoAssertOnGC(rt) {}
};
/*
/**
* Unsets the gray bit for anything reachable from |thing|. |kind| should not be
* JS::TraceKind::Shape. |thing| should be non-null.
*/

14
js/public/HeapAPI.h
View File

@ -149,11 +149,13 @@ struct Zone
} /* namespace shadow */
// A GC pointer, tagged with the trace kind.
//
// In general, a GC pointer should be stored with an exact type. This class
// is for use when that is not possible because a single pointer must point
// to several kinds of GC thing.
/**
* A GC pointer, tagged with the trace kind.
*
* In general, a GC pointer should be stored with an exact type. This class
* is for use when that is not possible because a single pointer must point
* to several kinds of GC thing.
*/
class JS_FRIEND_API(GCCellPtr)
{
public:
@ -405,7 +407,7 @@ IsIncrementalBarrierNeededOnTenuredGCThing(JS::shadow::Runtime* rt, const JS::GC
return JS::shadow::Zone::asShadowZone(zone)->needsIncrementalBarrier();
}
/*
/**
* Create an object providing access to the garbage collector's internal notion
* of the current state of memory (both GC heap memory and GCthing-controlled
* malloc memory.

2
js/public/Id.h
View File

@ -58,7 +58,7 @@ JSID_TO_STRING(jsid id)
return (JSString*)JSID_BITS(id);
}
/*
/**
* Only JSStrings that have been interned via the JSAPI can be turned into
* jsids by API clients.
*

95
js/public/MemoryMetrics.h
View File

@ -55,8 +55,7 @@ struct TabSizes
size_t other;
};
// These are the measurements used by Servo. It's important that this is a POD
// struct so that Servo can have a parallel |repr(C)| Rust equivalent.
/** These are the measurements used by Servo. */
struct ServoSizes
{
enum Kind {
@ -96,18 +95,22 @@ struct ServoSizes
namespace js {
// In memory reporting, we have concept of "sundries", line items which are too
// small to be worth reporting individually. Under some circumstances, a memory
// reporter gets tossed into the sundries bucket if it's smaller than
// MemoryReportingSundriesThreshold() bytes.
//
// We need to define this value here, rather than in the code which actually
// generates the memory reports, because NotableStringInfo uses this value.
/**
* In memory reporting, we have concept of "sundries", line items which are too
* small to be worth reporting individually. Under some circumstances, a memory
* reporter gets tossed into the sundries bucket if it's smaller than
* MemoryReportingSundriesThreshold() bytes.
*
* We need to define this value here, rather than in the code which actually
* generates the memory reports, because NotableStringInfo uses this value.
*/
JS_FRIEND_API(size_t) MemoryReportingSundriesThreshold();
// This hash policy avoids flattening ropes (which perturbs the site being
// measured and requires a JSContext) at the expense of doing a FULL ROPE COPY
// on every hash and match! Beware.
/**
* This hash policy avoids flattening ropes (which perturbs the site being
* measured and requires a JSContext) at the expense of doing a FULL ROPE COPY
* on every hash and match! Beware.
*/
struct InefficientNonFlatteningStringHashPolicy
{
typedef JSString* Lookup;
@ -221,12 +224,14 @@ struct ClassInfo
#undef FOR_EACH_SIZE
};
// Holds data about a notable class (one whose combined object and shape
// instances use more than a certain amount of memory) so we can report it
// individually.
//
// The only difference between this class and ClassInfo is that this class
// holds a copy of the filename.
/**
* Holds data about a notable class (one whose combined object and shape
* instances use more than a certain amount of memory) so we can report it
* individually.
*
* The only difference between this class and ClassInfo is that this class
* holds a copy of the filename.
*/
struct NotableClassInfo : public ClassInfo
{
NotableClassInfo();
@ -244,7 +249,7 @@ struct NotableClassInfo : public ClassInfo
NotableClassInfo(const NotableClassInfo& info) = delete;
};
// Data for tracking JIT-code memory usage.
/** Data for tracking JIT-code memory usage. */
struct CodeSizes
{
#define FOR_EACH_SIZE(macro) \
@ -269,7 +274,7 @@ struct CodeSizes
#undef FOR_EACH_SIZE
};
// Data for tracking GC memory usage.
/** Data for tracking GC memory usage. */
struct GCSizes
{
// |nurseryDecommitted| is marked as NonHeap rather than GCHeapDecommitted
@ -300,11 +305,13 @@ struct GCSizes
#undef FOR_EACH_SIZE
};
// This class holds information about the memory taken up by identical copies of
// a particular string. Multiple JSStrings may have their sizes aggregated
// together into one StringInfo object. Note that two strings with identical
// chars will not be aggregated together if one is a short string and the other
// is not.
/**
* This class holds information about the memory taken up by identical copies of
* a particular string. Multiple JSStrings may have their sizes aggregated
* together into one StringInfo object. Note that two strings with identical
* chars will not be aggregated together if one is a short string and the other
* is not.
*/
struct StringInfo
{
#define FOR_EACH_SIZE(macro) \
@ -355,11 +362,13 @@ struct StringInfo
#undef FOR_EACH_SIZE
};
// Holds data about a notable string (one which, counting all duplicates, uses
// more than a certain amount of memory) so we can report it individually.
//
// The only difference between this class and StringInfo is that
// NotableStringInfo holds a copy of some or all of the string's chars.
/**
* Holds data about a notable string (one which, counting all duplicates, uses
* more than a certain amount of memory) so we can report it individually.
*
* The only difference between this class and StringInfo is that
* NotableStringInfo holds a copy of some or all of the string's chars.
*/
struct NotableStringInfo : public StringInfo
{
static const size_t MAX_SAVED_CHARS = 1024;
@ -380,8 +389,10 @@ struct NotableStringInfo : public StringInfo
NotableStringInfo(const NotableStringInfo& info) = delete;
};
// This class holds information about the memory taken up by script sources
// from a particular file.
/**
* This class holds information about the memory taken up by script sources
* from a particular file.
*/
struct ScriptSourceInfo
{
#define FOR_EACH_SIZE(macro) \
@ -422,12 +433,14 @@ struct ScriptSourceInfo
#undef FOR_EACH_SIZE
};
// Holds data about a notable script source file (one whose combined
// script sources use more than a certain amount of memory) so we can report it
// individually.
//
// The only difference between this class and ScriptSourceInfo is that this
// class holds a copy of the filename.
/**
* Holds data about a notable script source file (one whose combined
* script sources use more than a certain amount of memory) so we can report it
* individually.
*
* The only difference between this class and ScriptSourceInfo is that this
* class holds a copy of the filename.
*/
struct NotableScriptSourceInfo : public ScriptSourceInfo
{
NotableScriptSourceInfo();
@ -445,8 +458,10 @@ struct NotableScriptSourceInfo : public ScriptSourceInfo
NotableScriptSourceInfo(const NotableScriptSourceInfo& info) = delete;
};
// These measurements relate directly to the JSRuntime, and not to zones and
// compartments within it.
/**
* These measurements relate directly to the JSRuntime, and not to zones and
* compartments within it.
*/
struct RuntimeSizes
{
#define FOR_EACH_SIZE(macro) \

26
js/public/RootingAPI.h
View File

@ -180,7 +180,7 @@ JS_FRIEND_API(bool) isGCEnabled();
JS_FRIEND_API(void) HeapObjectPostBarrier(JSObject** objp, JSObject* prev, JSObject* next);
#ifdef JS_DEBUG
/*
/**
* For generational GC, assert that an object is in the tenured generation as
* opposed to being in the nursery.
*/
@ -195,7 +195,7 @@ inline void
AssertGCThingIsNotAnObjectSubclass(js::gc::Cell* cell) {}
#endif
/*
/**
* The Heap<T> class is a heap-stored reference to a JS GC thing. All members of
* heap classes that refer to GC things should use Heap<T> (or possibly
* TenuredHeap<T>, described below).
@ -278,7 +278,7 @@ class Heap : public js::HeapBase<T>
T ptr;
};
/*
/**
* The TenuredHeap<T> class is similar to the Heap<T> class above in that it
* encapsulates the GC concerns of an on-heap reference to a JS object. However,
* it has two important differences:
@ -368,7 +368,7 @@ class TenuredHeap : public js::HeapBase<T>
uintptr_t bits;
};
/*
/**
* Reference to a T that has been rooted elsewhere. This is most useful
* as a parameter type, which guarantees that the T lvalue is properly
* rooted. See "Move GC Stack Rooting" above.
@ -457,7 +457,7 @@ class MOZ_NONHEAP_CLASS Handle : public js::HandleBase<T>
const T* ptr;
};
/*
/**
* Similar to a handle, but the underlying storage can be changed. This is
* useful for outparams.
*
@ -509,7 +509,7 @@ class MOZ_STACK_CLASS MutableHandle : public js::MutableHandleBase<T>
namespace js {
/*
/**
* By default, things should use the inheritance hierarchy to find their
* ThingRootKind. Some pointer types are explicitly set in jspubtd.h so that
* Rooted<T> may be used without the class definition being available.
@ -645,7 +645,7 @@ RootListsForRootingContext(js::PerThreadDataFriendFields* pt)
namespace JS {
/*
/**
* Local variable of type T whose value is always rooted. This is typically
* used for local variables, or for non-rooted values being passed to a
* function that requires a handle, e.g. Foo(Root<T>(cx, x)).
@ -733,7 +733,7 @@ class MOZ_RAII Rooted : public js::RootedBase<T>
namespace js {
/*
/**
* Augment the generic Rooted<T> interface when T = JSObject* with
* class-querying and downcasting operations.
*
@ -751,7 +751,7 @@ class RootedBase<JSObject*>
JS::Handle<U*> as() const;
};
/*
/**
* Augment the generic Handle<T> interface when T = JSObject* with
* downcasting operations.
*
@ -769,7 +769,7 @@ class HandleBase<JSObject*>
JS::Handle<U*> as() const;
};
/* Interface substitute for Rooted<T> which does not root the variable's memory. */
/** Interface substitute for Rooted<T> which does not root the variable's memory. */
template <typename T>
class MOZ_RAII FakeRooted : public RootedBase<T>
{
@ -796,7 +796,7 @@ class MOZ_RAII FakeRooted : public RootedBase<T>
FakeRooted(const FakeRooted&) = delete;
};
/* Interface substitute for MutableHandle<T> which is not required to point to rooted memory. */
/** Interface substitute for MutableHandle<T> which is not required to point to rooted memory. */
template <typename T>
class FakeMutableHandle : public js::MutableHandleBase<T>
{
@ -824,7 +824,7 @@ class FakeMutableHandle : public js::MutableHandleBase<T>
T* ptr;
};
/*
/**
* Types for a variable that either should or shouldn't be rooted, depending on
* the template parameter allowGC. Used for implementing functions that can
* operate on either rooted or unrooted data.
@ -930,7 +930,7 @@ MutableHandle<T>::MutableHandle(PersistentRooted<T>* root)
ptr = root->address();
}
/*
/**
* A copyable, assignable global GC root type with arbitrary lifetime, an
* infallible constructor, and automatic unrooting on destruction.
*

153
js/public/StructuredClone.h
View File

@ -23,85 +23,96 @@ struct JSStructuredCloneWriter;
namespace JS {
enum TransferableOwnership {
// Transferable data has not been filled in yet
/** Transferable data has not been filled in yet */
SCTAG_TMO_UNFILLED = 0,
// Structured clone buffer does not yet own the data
/** Structured clone buffer does not yet own the data */
SCTAG_TMO_UNOWNED = 1,
// All values at least this large are owned by the clone buffer
/** All values at least this large are owned by the clone buffer */
SCTAG_TMO_FIRST_OWNED = 2,
// Data is a pointer that can be freed
/** Data is a pointer that can be freed */
SCTAG_TMO_ALLOC_DATA = 2,
// Data is a SharedArrayBufferObject's buffer
/** Data is a SharedArrayBufferObject's buffer */
SCTAG_TMO_SHARED_BUFFER = 3,
// Data is a memory mapped pointer
/** Data is a memory mapped pointer */
SCTAG_TMO_MAPPED_DATA = 4,
// Data is embedding-specific. The engine can free it by calling the
// freeTransfer op. The embedding can also use SCTAG_TMO_USER_MIN and
// greater, up to 32 bits, to distinguish specific ownership variants.
/**
* Data is embedding-specific. The engine can free it by calling the
* freeTransfer op. The embedding can also use SCTAG_TMO_USER_MIN and
* greater, up to 32 bits, to distinguish specific ownership variants.
*/
SCTAG_TMO_CUSTOM = 5,
SCTAG_TMO_USER_MIN
};
} /* namespace JS */
// Read structured data from the reader r. This hook is used to read a value
// previously serialized by a call to the WriteStructuredCloneOp hook.
//
// tag and data are the pair of uint32_t values from the header. The callback
// may use the JS_Read* APIs to read any other relevant parts of the object
// from the reader r. closure is any value passed to the JS_ReadStructuredClone
// function. Return the new object on success, nullptr on error/exception.
/**
* Read structured data from the reader r. This hook is used to read a value
* previously serialized by a call to the WriteStructuredCloneOp hook.
*
* tag and data are the pair of uint32_t values from the header. The callback
* may use the JS_Read* APIs to read any other relevant parts of the object
* from the reader r. closure is any value passed to the JS_ReadStructuredClone
* function. Return the new object on success, nullptr on error/exception.
*/
typedef JSObject* (*ReadStructuredCloneOp)(JSContext* cx, JSStructuredCloneReader* r,
uint32_t tag, uint32_t data, void* closure);
// Structured data serialization hook. The engine can write primitive values,
// Objects, Arrays, Dates, RegExps, TypedArrays, ArrayBuffers, Sets, Maps,
// and SharedTypedArrays. Any other type of object requires application support.
// This callback must first use the JS_WriteUint32Pair API to write an object
// header, passing a value greater than JS_SCTAG_USER to the tag parameter.
// Then it can use the JS_Write* APIs to write any other relevant parts of
// the value v to the writer w. closure is any value passed to the
// JS_WriteStructuredClone function.
//
// Return true on success, false on error/exception.
/**
* Structured data serialization hook. The engine can write primitive values,
* Objects, Arrays, Dates, RegExps, TypedArrays, ArrayBuffers, Sets, Maps,
* and SharedTypedArrays. Any other type of object requires application support.
* This callback must first use the JS_WriteUint32Pair API to write an object
* header, passing a value greater than JS_SCTAG_USER to the tag parameter.
* Then it can use the JS_Write* APIs to write any other relevant parts of
* the value v to the writer w. closure is any value passed to the
* JS_WriteStructuredClone function.
*
* Return true on success, false on error/exception.
*/
typedef bool (*WriteStructuredCloneOp)(JSContext* cx, JSStructuredCloneWriter* w,
JS::HandleObject obj, void* closure);
// This is called when JS_WriteStructuredClone is given an invalid transferable.
// To follow HTML5, the application must throw a DATA_CLONE_ERR DOMException
// with error set to one of the JS_SCERR_* values.
/**
* This is called when JS_WriteStructuredClone is given an invalid transferable.
* To follow HTML5, the application must throw a DATA_CLONE_ERR DOMException
* with error set to one of the JS_SCERR_* values.
*/
typedef void (*StructuredCloneErrorOp)(JSContext* cx, uint32_t errorid);
// This is called when JS_ReadStructuredClone receives a transferable object
// not known to the engine. If this hook does not exist or returns false, the
// JS engine calls the reportError op if set, otherwise it throws a
// DATA_CLONE_ERR DOM Exception. This method is called before any other
// callback and must return a non-null object in returnObject on success.
/**
* This is called when JS_ReadStructuredClone receives a transferable object
* not known to the engine. If this hook does not exist or returns false, the
* JS engine calls the reportError op if set, otherwise it throws a
* DATA_CLONE_ERR DOM Exception. This method is called before any other
* callback and must return a non-null object in returnObject on success.
*/
typedef bool (*ReadTransferStructuredCloneOp)(JSContext* cx, JSStructuredCloneReader* r,
uint32_t tag, void* content, uint64_t extraData,
void* closure,
JS::MutableHandleObject returnObject);
// Called when JS_WriteStructuredClone receives a transferable object not
// handled by the engine. If this hook does not exist or returns false, the JS
// engine will call the reportError hook or fall back to throwing a
// DATA_CLONE_ERR DOM Exception. This method is called before any other
// callback.
//
// tag: indicates what type of transferable this is. Must be greater than
// 0xFFFF0201 (value of the internal SCTAG_TRANSFER_MAP_PENDING_ENTRY)
//
// ownership: see TransferableOwnership, above. Used to communicate any needed
// ownership info to the FreeTransferStructuredCloneOp.
//
// content, extraData: what the ReadTransferStructuredCloneOp will receive
//
/**
* Called when JS_WriteStructuredClone receives a transferable object not
* handled by the engine. If this hook does not exist or returns false, the JS
* engine will call the reportError hook or fall back to throwing a
* DATA_CLONE_ERR DOM Exception. This method is called before any other
* callback.
*
* tag: indicates what type of transferable this is. Must be greater than
* 0xFFFF0201 (value of the internal SCTAG_TRANSFER_MAP_PENDING_ENTRY)
*
* ownership: see TransferableOwnership, above. Used to communicate any needed
* ownership info to the FreeTransferStructuredCloneOp.
*
* content, extraData: what the ReadTransferStructuredCloneOp will receive
*/
typedef bool (*TransferStructuredCloneOp)(JSContext* cx,
JS::Handle<JSObject*> obj,
void* closure,
@ -111,9 +122,11 @@ typedef bool (*TransferStructuredCloneOp)(JSContext* cx,
void** content,
uint64_t* extraData);
// Called when JS_ClearStructuredClone has to free an unknown transferable
// object. Note that it should never trigger a garbage collection (and will
// assert in a debug build if it does.)
/**
* Called when JS_ClearStructuredClone has to free an unknown transferable
* object. Note that it should never trigger a garbage collection (and will
* assert in a debug build if it does.)
*/
typedef void (*FreeTransferStructuredCloneOp)(uint32_t tag, JS::TransferableOwnership ownership,
void* content, uint64_t extraData, void* closure);
@ -132,14 +145,16 @@ struct JSStructuredCloneCallbacks {
FreeTransferStructuredCloneOp freeTransfer;
};
// Note: if the *data contains transferable objects, it can be read only once.
/** Note: if the *data contains transferable objects, it can be read only once. */
JS_PUBLIC_API(bool)
JS_ReadStructuredClone(JSContext* cx, uint64_t* data, size_t nbytes, uint32_t version,
JS::MutableHandleValue vp,
const JSStructuredCloneCallbacks* optionalCallbacks, void* closure);
// Note: On success, the caller is responsible for calling
// JS_ClearStructuredClone(*datap, nbytes, optionalCallbacks, closure).
/**
* Note: On success, the caller is responsible for calling
* JS_ClearStructuredClone(*datap, nbytes, optionalCallbacks, closure).
*/
JS_PUBLIC_API(bool)
JS_WriteStructuredClone(JSContext* cx, JS::HandleValue v, uint64_t** datap, size_t* nbytesp,
const JSStructuredCloneCallbacks* optionalCallbacks,
@ -157,7 +172,7 @@ JS_PUBLIC_API(bool)
JS_StructuredClone(JSContext* cx, JS::HandleValue v, JS::MutableHandleValue vp,
const JSStructuredCloneCallbacks* optionalCallbacks, void* closure);
// RAII sugar for JS_WriteStructuredClone.
/** RAII sugar for JS_WriteStructuredClone. */
class JS_PUBLIC_API(JSAutoStructuredCloneBuffer) {
uint64_t* data_;
size_t nbytes_;
@ -194,26 +209,32 @@ class JS_PUBLIC_API(JSAutoStructuredCloneBuffer) {
void clear(const JSStructuredCloneCallbacks* optionalCallbacks=nullptr, void* closure=nullptr);
// Copy some memory. It will be automatically freed by the destructor.
/** Copy some memory. It will be automatically freed by the destructor. */
bool copy(const uint64_t* data, size_t nbytes, uint32_t version=JS_STRUCTURED_CLONE_VERSION,
const JSStructuredCloneCallbacks* callbacks=nullptr, void* closure=nullptr);
// Adopt some memory. It will be automatically freed by the destructor.
// data must have been allocated by the JS engine (e.g., extracted via
// JSAutoStructuredCloneBuffer::steal).
/**
* Adopt some memory. It will be automatically freed by the destructor.
* data must have been allocated by the JS engine (e.g., extracted via
* JSAutoStructuredCloneBuffer::steal).
*/
void adopt(uint64_t* data, size_t nbytes, uint32_t version=JS_STRUCTURED_CLONE_VERSION,
const JSStructuredCloneCallbacks* callbacks=nullptr, void* closure=nullptr);
// Release the buffer and transfer ownership to the caller. The caller is
// responsible for calling JS_ClearStructuredClone or feeding the memory
// back to JSAutoStructuredCloneBuffer::adopt.
/**
* Release the buffer and transfer ownership to the caller. The caller is
* responsible for calling JS_ClearStructuredClone or feeding the memory
* back to JSAutoStructuredCloneBuffer::adopt.
*/
void steal(uint64_t** datap, size_t* nbytesp, uint32_t* versionp=nullptr,
const JSStructuredCloneCallbacks** callbacks=nullptr, void** closure=nullptr);
// Abandon ownership of any transferable objects stored in the buffer,
// without freeing the buffer itself. Useful when copying the data out into
// an external container, though note that you will need to use adopt() or
// JS_ClearStructuredClone to properly release that data eventually.
/**
* Abandon ownership of any transferable objects stored in the buffer,
* without freeing the buffer itself. Useful when copying the data out into
* an external container, though note that you will need to use adopt() or
* JS_ClearStructuredClone to properly release that data eventually.
*/
void abandon() { ownTransferables_ = IgnoreTransferablesIfAny; }
bool read(JSContext* cx, JS::MutableHandleValue vp,

36
js/public/TracingAPI.h
View File

@ -20,27 +20,33 @@ class JS_PUBLIC_API(CallbackTracer);
template <typename T> class Heap;
template <typename T> class TenuredHeap;
// Returns a static string equivalent of |kind|.
/** Returns a static string equivalent of |kind|. */
JS_FRIEND_API(const char*)
GCTraceKindToAscii(JS::TraceKind kind);
} // namespace JS
enum WeakMapTraceKind {
// Do true ephemeron marking with an iterative weak marking phase.
/** Do true ephemeron marking with an iterative weak marking phase. */
DoNotTraceWeakMaps,
// Do true ephemeron marking with a weak key lookup marking phase. This is
// expected to be constant for the lifetime of a JSTracer; it does not
// change when switching from "plain" marking to weak marking.
/**
* Do true ephemeron marking with a weak key lookup marking phase. This is
* expected to be constant for the lifetime of a JSTracer; it does not
* change when switching from "plain" marking to weak marking.
*/
ExpandWeakMaps,
// Trace through to all values, irrespective of whether the keys are live
// or not. Used for non-marking tracers.
/**
* Trace through to all values, irrespective of whether the keys are live
* or not. Used for non-marking tracers.
*/
TraceWeakMapValues,
// Trace through to all keys and values, irrespective of whether the keys
// are live or not. Used for non-marking tracers.
/**
* Trace through to all keys and values, irrespective of whether the keys
* are live or not. Used for non-marking tracers.
*/
TraceWeakMapKeysValues
};
@ -333,8 +339,10 @@ JS_CallHashSetObjectTracer(JSTracer* trc, HashSetEnum& e, JSObject* const& key,
e.rekeyFront(updated);
}
// Trace an object that is known to always be tenured. No post barriers are
// required in this case.
/**
* Trace an object that is known to always be tenured. No post barriers are
* required in this case.
*/
extern JS_PUBLIC_API(void)
JS_CallTenuredObjectTracer(JSTracer* trc, JS::TenuredHeap<JSObject*>* objp, const char* name);
@ -348,8 +356,10 @@ TraceChildren(JSTracer* trc, GCCellPtr thing);
typedef js::HashSet<Zone*, js::DefaultHasher<Zone*>, js::SystemAllocPolicy> ZoneSet;
} // namespace JS
// Trace every value within |zones| that is wrapped by a cross-compartment
// wrapper from a zone that is not an element of |zones|.
/**
* Trace every value within |zones| that is wrapped by a cross-compartment
* wrapper from a zone that is not an element of |zones|.
*/
extern JS_PUBLIC_API(void)
JS_TraceIncomingCCWs(JSTracer* trc, const JS::ZoneSet& zones);

79
js/public/Value.h
View File

@ -237,25 +237,60 @@ typedef uint64_t JSValueShiftedTag;
typedef enum JSWhyMagic
{
JS_ELEMENTS_HOLE, /* a hole in a native object's elements */
JS_NO_ITER_VALUE, /* there is not a pending iterator value */
JS_GENERATOR_CLOSING, /* exception value thrown when closing a generator */
JS_NO_CONSTANT, /* compiler sentinel value */
JS_THIS_POISON, /* used in debug builds to catch tracing errors */
JS_ARG_POISON, /* used in debug builds to catch tracing errors */
JS_SERIALIZE_NO_NODE, /* an empty subnode in the AST serializer */
JS_LAZY_ARGUMENTS, /* lazy arguments value on the stack */
JS_OPTIMIZED_ARGUMENTS, /* optimized-away 'arguments' value */
JS_IS_CONSTRUCTING, /* magic value passed to natives to indicate construction */
JS_OVERWRITTEN_CALLEE, /* arguments.callee has been overwritten */
JS_BLOCK_NEEDS_CLONE, /* value of static block object slot */
JS_HASH_KEY_EMPTY, /* see class js::HashableValue */
JS_ION_ERROR, /* error while running Ion code */
JS_ION_BAILOUT, /* missing recover instruction result */
JS_OPTIMIZED_OUT, /* optimized out slot */
JS_UNINITIALIZED_LEXICAL, /* uninitialized lexical bindings that produce ReferenceError
* on touch. */
JS_GENERIC_MAGIC, /* for local use */
/** a hole in a native object's elements */
JS_ELEMENTS_HOLE,
/** there is not a pending iterator value */
JS_NO_ITER_VALUE,
/** exception value thrown when closing a generator */
JS_GENERATOR_CLOSING,
/** compiler sentinel value */
JS_NO_CONSTANT,
/** used in debug builds to catch tracing errors */
JS_THIS_POISON,
/** used in debug builds to catch tracing errors */
JS_ARG_POISON,
/** an empty subnode in the AST serializer */
JS_SERIALIZE_NO_NODE,
/** lazy arguments value on the stack */
JS_LAZY_ARGUMENTS,
/** optimized-away 'arguments' value */
JS_OPTIMIZED_ARGUMENTS,
/** magic value passed to natives to indicate construction */
JS_IS_CONSTRUCTING,
/** arguments.callee has been overwritten */
JS_OVERWRITTEN_CALLEE,
/** value of static block object slot */
JS_BLOCK_NEEDS_CLONE,
/** see class js::HashableValue */
JS_HASH_KEY_EMPTY,
/** error while running Ion code */
JS_ION_ERROR,
/** missing recover instruction result */
JS_ION_BAILOUT,
/** optimized out slot */
JS_OPTIMIZED_OUT,
/** uninitialized lexical bindings that produce ReferenceError on touch. */
JS_UNINITIALIZED_LEXICAL,
/** for local use */
JS_GENERIC_MAGIC,
JS_WHY_MAGIC_COUNT
} JSWhyMagic;
@ -967,7 +1002,7 @@ CanonicalizeNaN(double d)
# pragma optimize("", on)
#endif
/*
/**
* JS::Value is the interface for a single JavaScript Engine value. A few
* general notes on JS::Value:
*
@ -1682,7 +1717,7 @@ template <> struct GCMethods<JS::Value>
template <class Outer> class MutableValueOperations;
/*
/**
* A class designed for CRTP use in implementing the non-mutating parts of the
* Value interface in Value-like classes. Outer must be a class inheriting
* ValueOperations<Outer> with a visible get() method returning a const
@ -1736,7 +1771,7 @@ class ValueOperations
uint32_t magicUint32() const { return value().magicUint32(); }
};
/*
/**
* A class designed for CRTP use in implementing all the mutating parts of the
* Value interface in Value-like classes. Outer must be a class inheriting
* MutableValueOperations<Outer> with visible get() methods returning const and

544
js/src/jsapi.h
View File

File diff suppressed because it is too large Load Diff

304
js/src/jsfriendapi.h
View File

@ -57,10 +57,12 @@ JS_SplicePrototype(JSContext* cx, JS::HandleObject obj, JS::HandleObject proto);
extern JS_FRIEND_API(JSObject*)
JS_NewObjectWithUniqueType(JSContext* cx, const JSClass* clasp, JS::HandleObject proto);
// Allocate an object in exactly the same way as JS_NewObjectWithGivenProto, but
// without invoking the metadata callback on it. This allows creation of
// internal bookkeeping objects that are guaranteed to not have metadata
// attached to them.
/**
* Allocate an object in exactly the same way as JS_NewObjectWithGivenProto, but
* without invoking the metadata callback on it. This allows creation of
* internal bookkeeping objects that are guaranteed to not have metadata
* attached to them.
*/
extern JS_FRIEND_API(JSObject*)
JS_NewObjectWithoutMetadata(JSContext* cx, const JSClass* clasp, JS::Handle<JSObject*> proto);
@ -83,7 +85,7 @@ JS_NondeterministicGetWeakMapKeys(JSContext* cx, JS::HandleObject obj, JS::Mutab
extern JS_FRIEND_API(unsigned)
JS_PCToLineNumber(JSScript* script, jsbytecode* pc, unsigned* columnp = nullptr);
/*
/**
* Determine whether the given object is backed by a DeadObjectProxy.
*
* Such objects hold no other objects (they have no outgoing reference edges)
@ -156,7 +158,7 @@ JS_ObjectToOuterObject(JSContext* cx, JS::HandleObject obj);
extern JS_FRIEND_API(JSObject*)
JS_CloneObject(JSContext* cx, JS::HandleObject obj, JS::HandleObject proto);
/*
/**
* Copy the own properties of src to dst in a fast way. src and dst must both
* be native and must be in the compartment of cx. They must have the same
* class, the same parent, and the same prototype. Class reserved slots will
@ -241,13 +243,13 @@ DumpBacktrace(JSContext* cx);
namespace JS {
// Exposed for DumpJSStack
/** Exposed for DumpJSStack */
extern JS_FRIEND_API(char*)
FormatStackDump(JSContext* cx, char* buf, bool showArgs, bool showLocals, bool showThisProps);
} // namespace JS
/*
/**
* Copies all own properties from |obj| to |target|. |obj| must be a "native"
* object (that is to say, normal-ish - not an Array or a Proxy).
*
@ -417,7 +419,7 @@ extern JS_FRIEND_API(bool)
proxy_GetElements(JSContext* cx, JS::HandleObject proxy, uint32_t begin, uint32_t end,
ElementAdder* adder);
/*
/**
* A class of objects that return source code on demand.
*
* When code is compiled with setSourceIsLazy(true), SpiderMonkey doesn't
@ -432,7 +434,7 @@ class SourceHook {
public:
virtual ~SourceHook() { }
/*
/**
* Set |*src| and |*length| to refer to the source code for |filename|.
* On success, the caller owns the buffer to which |*src| points, and
* should use JS_free to free it.
@ -440,7 +442,7 @@ class SourceHook {
virtual bool load(JSContext* cx, const char* filename, char16_t** src, size_t* length) = 0;
};
/*
/**
* Have |rt| use |hook| to retrieve lazily-retrieved source code. See the
* comments for SourceHook. The runtime takes ownership of the hook, and
* will delete it when the runtime itself is deleted, or when a new hook is
@ -449,7 +451,7 @@ class SourceHook {
extern JS_FRIEND_API(void)
SetSourceHook(JSRuntime* rt, mozilla::UniquePtr<SourceHook> hook);
/* Remove |rt|'s source hook, and return it. The caller now owns the hook. */
/** Remove |rt|'s source hook, and return it. The caller now owns the hook. */
extern JS_FRIEND_API(mozilla::UniquePtr<SourceHook>)
ForgetSourceHook(JSRuntime* rt);
@ -464,7 +466,7 @@ typedef enum {
IgnoreNurseryObjects
} DumpHeapNurseryBehaviour;
/*
/**
* Dump the complete object graph of heap-allocated things.
* fp is the file for the dump output.
*/
@ -524,7 +526,7 @@ GetWeakmapKeyDelegate(JSObject* key);
JS_FRIEND_API(JS::TraceKind)
GCThingTraceKind(void* thing);
/*
/**
* Invoke cellCallback on every gray JS_OBJECT in the given zone.
*/
extern JS_FRIEND_API(void)
@ -566,9 +568,11 @@ public:
static const uint32_t FIXED_SLOTS_SHIFT = 27;
};
// This layout is shared by all native objects. For non-native objects, the
// group may always be accessed safely, and other members may be as well,
// depending on the object's specific layout.
/**
* This layout is shared by all native objects. For non-native objects, the
* group may always be accessed safely, and other members may be as well,
* depending on the object's specific layout.
*/
struct Object {
shadow::ObjectGroup* group;
shadow::Shape* shape;
@ -706,7 +710,7 @@ inline void AssertSameCompartment(JSObject* objA, JSObject* objB) {}
JS_FRIEND_API(void)
NotifyAnimationActivity(JSObject* obj);
/*
/**
* Return the outermost enclosing function (script) of the scripted caller.
* This function returns nullptr in several cases:
* - no script is running on the context
@ -1059,12 +1063,14 @@ GetPCCountScriptSummary(JSContext* cx, size_t script);
JS_FRIEND_API(JSString*)
GetPCCountScriptContents(JSContext* cx, size_t script);
// Generate lcov trace file content for the current compartment, and allocate a
// new buffer and return the content in it, the size of the newly allocated
// content within the buffer would be set to the length out-param.
//
// In case of out-of-memory, this function returns nullptr and does not set any
// value to the length out-param.
/**
* Generate lcov trace file content for the current compartment, and allocate a
* new buffer and return the content in it, the size of the newly allocated
* content within the buffer would be set to the length out-param.
*
* In case of out-of-memory, this function returns nullptr and does not set any
* value to the length out-param.
*/
JS_FRIEND_API(char*)
GetCodeCoverageSummary(JSContext* cx, size_t* length);
@ -1074,7 +1080,7 @@ ContextHasOutstandingRequests(const JSContext* cx);
typedef void
(* ActivityCallback)(void* arg, bool active);
/*
/**
* Sets a callback that is run whenever the runtime goes idle - the
* last active request ceases - and begins activity - when it was
* idle and a request begins.
@ -1099,7 +1105,7 @@ GetDOMCallbacks(JSRuntime* rt);
extern JS_FRIEND_API(JSObject*)
GetTestingFunctions(JSContext* cx);
/*
/**
* Helper to convert FreeOp to JSFreeOp when the definition of FreeOp is not
* available and the compiler does not know that FreeOp inherits from
* JSFreeOp.
@ -1112,7 +1118,7 @@ CastToJSFreeOp(FreeOp* fop)
/* Implemented in jsexn.cpp. */
/*
/**
* Get an error type name from a JSExnType constant.
* Returns nullptr for invalid arguments and JSEXN_INTERNALERR
*/
@ -1254,7 +1260,7 @@ inline bool DOMProxyIsShadowing(DOMProxyShadowsResult result) {
/* Implemented in jsdate.cpp. */
/* Detect whether the internal date value is NaN. */
/** Detect whether the internal date value is NaN. */
extern JS_FRIEND_API(bool)
DateIsValid(JSContext* cx, JS::HandleObject obj, bool* isValid);
@ -1265,7 +1271,7 @@ DateGetMsecSinceEpoch(JSContext* cx, JS::HandleObject obj, double* msecSinceEpoc
/* Implemented in jscntxt.cpp. */
/*
/**
* Report an exception, which is currently realized as a printf-style format
* string and its arguments.
*/
@ -1285,7 +1291,7 @@ GetErrorMessage(void* userRef, const unsigned errorNumber);
// AutoStableStringChars is here so we can use it in ErrorReport. It
// should get moved out of here if we can manage it. See bug 1040316.
/*
/**
* This class provides safe access to a string's chars across a GC. Once
* we allocate strings and chars in the nursery (bug 903519), this class
* will have to make a copy of the string's chars if they are allocated
@ -1354,8 +1360,10 @@ class MOZ_STACK_CLASS AutoStableStringChars
void operator=(const AutoStableStringChars& other) = delete;
};
// Creates a string of the form |ErrorType: ErrorMessage| for a JSErrorReport,
// which generally matches the toString() behavior of an ErrorObject.
/**
* Creates a string of the form |ErrorType: ErrorMessage| for a JSErrorReport,
* which generally matches the toString() behavior of an ErrorObject.
*/
extern JS_FRIEND_API(JSString*)
ErrorReportToString(JSContext* cx, JSErrorReport* reportp);
@ -1428,7 +1436,7 @@ GetSCOffset(JSStructuredCloneWriter* writer);
namespace Scalar {
/*
/**
* Scalar types that can appear in typed arrays and typed objects. The enum
* values must to be kept in sync with the JS_SCALARTYPEREPR_ constants, as
* well as the TypedArrayObject::classes and TypedArrayObject::protoClasses
@ -1444,13 +1452,13 @@ enum Type {
Float32,
Float64,
/*
/**
* Special type that is a uint8_t, but assignments are clamped to [0, 256).
* Treat the raw data type as a uint8_t.
*/
Uint8Clamped,
/*
/**
* SIMD types don't have their own TypedArray equivalent, for now.
*/
MaxTypedArrayViewType,
@ -1687,19 +1695,19 @@ extern JS_FRIEND_API(JSObject*)
JS_NewSharedFloat64ArrayWithBuffer(JSContext* cx, JS::HandleObject arrayBuffer,
uint32_t byteOffset, uint32_t length);
/*
/**
* Create a new SharedArrayBuffer with the given byte length.
*/
extern JS_FRIEND_API(JSObject*)
JS_NewSharedArrayBuffer(JSContext* cx, uint32_t nbytes);
/*
/**
* Create a new ArrayBuffer with the given byte length.
*/
extern JS_FRIEND_API(JSObject*)
JS_NewArrayBuffer(JSContext* cx, uint32_t nbytes);
/*
/**
* Check whether obj supports JS_GetTypedArray* APIs. Note that this may return
* false if a security wrapper is encountered that denies the unwrapping. If
* this test or one of the JS_Is*Array tests succeeds, then it is safe to call
@ -1708,13 +1716,13 @@ JS_NewArrayBuffer(JSContext* cx, uint32_t nbytes);
extern JS_FRIEND_API(bool)
JS_IsTypedArrayObject(JSObject* obj);
/*
/**
* Ditto for JS_GetSharedTypedArray* APIs.
*/
extern JS_FRIEND_API(bool)
JS_IsSharedTypedArrayObject(JSObject* obj);
/*
/**
* Check whether obj supports JS_GetArrayBufferView* APIs. Note that this may
* return false if a security wrapper is encountered that denies the
* unwrapping. If this test or one of the more specific tests succeeds, then it
@ -1958,7 +1966,7 @@ JS_IsArrayBufferObject(JSObject* obj);
extern JS_FRIEND_API(bool)
JS_IsSharedArrayBufferObject(JSObject* obj);
/*
/**
* Return the available byte length of an array buffer.
*
* |obj| must have passed a JS_IsArrayBufferObject test, or somehow be known
@ -1968,7 +1976,7 @@ JS_IsSharedArrayBufferObject(JSObject* obj);
extern JS_FRIEND_API(uint32_t)
JS_GetArrayBufferByteLength(JSObject* obj);
/*
/**
* Return true if the arrayBuffer contains any data. This will return false for
* ArrayBuffer.prototype and neutered ArrayBuffers.
*
@ -1979,7 +1987,7 @@ JS_GetArrayBufferByteLength(JSObject* obj);
extern JS_FRIEND_API(bool)
JS_ArrayBufferHasData(JSObject* obj);
/*
/**
* Check whether the obj is ArrayBufferObject and memory mapped. Note that this
* may return false if a security wrapper is encountered that denies the
* unwrapping.
@ -1987,7 +1995,7 @@ JS_ArrayBufferHasData(JSObject* obj);
extern JS_FRIEND_API(bool)
JS_IsMappedArrayBufferObject(JSObject* obj);
/*
/**
* Return the number of elements in a typed array.
*
* |obj| must have passed a JS_IsTypedArrayObject/JS_Is*Array test, or somehow
@ -1997,7 +2005,7 @@ JS_IsMappedArrayBufferObject(JSObject* obj);
extern JS_FRIEND_API(uint32_t)
JS_GetTypedArrayLength(JSObject* obj);
/*
/**
* Return the byte offset from the start of an array buffer to the start of a
* typed array view.
*
@ -2008,7 +2016,7 @@ JS_GetTypedArrayLength(JSObject* obj);
extern JS_FRIEND_API(uint32_t)
JS_GetTypedArrayByteOffset(JSObject* obj);
/*
/**
* Return the byte length of a typed array.
*
* |obj| must have passed a JS_IsTypedArrayObject/JS_Is*Array test, or somehow
@ -2018,7 +2026,7 @@ JS_GetTypedArrayByteOffset(JSObject* obj);
extern JS_FRIEND_API(uint32_t)
JS_GetTypedArrayByteLength(JSObject* obj);
/*
/**
* Check whether obj supports JS_ArrayBufferView* APIs. Note that this may
* return false if a security wrapper is encountered that denies the
* unwrapping.
@ -2026,7 +2034,7 @@ JS_GetTypedArrayByteLength(JSObject* obj);
extern JS_FRIEND_API(bool)
JS_IsArrayBufferViewObject(JSObject* obj);
/*
/**
* More generic name for JS_GetTypedArrayByteLength to cover DataViews as well
*/
extern JS_FRIEND_API(uint32_t)
@ -2086,14 +2094,14 @@ JS_GetSharedFloat32ArrayData(JSObject* obj, const JS::AutoCheckCannotGC&);
extern JS_FRIEND_API(double*)
JS_GetSharedFloat64ArrayData(JSObject* obj, const JS::AutoCheckCannotGC&);
/*
/**
* Same as above, but for any kind of ArrayBufferView. Prefer the type-specific
* versions when possible.
*/
extern JS_FRIEND_API(void*)
JS_GetArrayBufferViewData(JSObject* obj, const JS::AutoCheckCannotGC&);
/*
/**
* Return the ArrayBuffer underlying an ArrayBufferView. If the buffer has been
* neutered, this will still return the neutered buffer. |obj| must be an
* object that would return true for JS_IsArrayBufferViewObject().
@ -2106,7 +2114,7 @@ typedef enum {
KeepData
} NeuterDataDisposition;
/*
/**
* Set an ArrayBuffer's length to 0 and neuter all of its views.
*
* The |changeData| argument is a hint to inform internal behavior with respect
@ -2119,7 +2127,7 @@ extern JS_FRIEND_API(bool)
JS_NeuterArrayBuffer(JSContext* cx, JS::HandleObject obj,
NeuterDataDisposition changeData);
/*
/**
* Check whether the obj is ArrayBufferObject and neutered. Note that this
* may return false if a security wrapper is encountered that denies the
* unwrapping.
@ -2127,13 +2135,13 @@ JS_NeuterArrayBuffer(JSContext* cx, JS::HandleObject obj,
extern JS_FRIEND_API(bool)
JS_IsNeuteredArrayBufferObject(JSObject* obj);
/*
/**
* Check whether obj supports JS_GetDataView* APIs.
*/
JS_FRIEND_API(bool)
JS_IsDataViewObject(JSObject* obj);
/*
/**
* Create a new DataView using the given ArrayBuffer for storage. The given
* buffer must be an ArrayBuffer (or a cross-compartment wrapper of an
* ArrayBuffer), and the offset and length must fit within the bounds of the
@ -2143,7 +2151,7 @@ JS_IsDataViewObject(JSObject* obj);
JS_FRIEND_API(JSObject*)
JS_NewDataView(JSContext* cx, JS::HandleObject arrayBuffer, uint32_t byteOffset, int32_t byteLength);
/*
/**
* Return the byte offset of a data view into its array buffer. |obj| must be a
* DataView.
*
@ -2154,7 +2162,7 @@ JS_NewDataView(JSContext* cx, JS::HandleObject arrayBuffer, uint32_t byteOffset,
JS_FRIEND_API(uint32_t)
JS_GetDataViewByteOffset(JSObject* obj);
/*
/**
* Return the byte length of a data view.
*
* |obj| must have passed a JS_IsDataViewObject test, or somehow be known that
@ -2165,7 +2173,7 @@ JS_GetDataViewByteOffset(JSObject* obj);
JS_FRIEND_API(uint32_t)
JS_GetDataViewByteLength(JSObject* obj);
/*
/**
* Return a pointer to the beginning of the data referenced by a DataView.
*
* |obj| must have passed a JS_IsDataViewObject test, or somehow be known that
@ -2178,7 +2186,7 @@ JS_GetDataViewData(JSObject* obj, const JS::AutoCheckCannotGC&);
namespace js {
/*
/**
* Add a watchpoint -- in the Object.prototype.watch sense -- to |obj| for the
* property |id|, using the callable object |callable| as the function to be
* called for notifications.
@ -2190,7 +2198,7 @@ namespace js {
extern JS_FRIEND_API(bool)
WatchGuts(JSContext* cx, JS::HandleObject obj, JS::HandleId id, JS::HandleObject callable);
/*
/**
* Remove a watchpoint -- in the Object.prototype.watch sense -- from |obj| for
* the property |id|.
*
@ -2209,7 +2217,7 @@ enum class InlinableNative : uint16_t;
} // namespace js
/*
/**
* A class, expected to be passed by value, which represents the CallArgs for a
* JSJitGetterOp.
*/
@ -2229,7 +2237,7 @@ class JSJitGetterCallArgs : protected JS::MutableHandleValue
}
};
/*
/**
* A class, expected to be passed by value, which represents the CallArgs for a
* JSJitSetterOp.
*/
@ -2252,7 +2260,7 @@ class JSJitSetterCallArgs : protected JS::MutableHandleValue
struct JSJitMethodCallArgsTraits;
/*
/**
* A class, expected to be passed by reference, which represents the CallArgs
* for a JSJitMethodOp.
*/
@ -2299,11 +2307,6 @@ struct JSJitMethodCallArgsTraits
static const size_t offsetOfArgc = offsetof(JSJitMethodCallArgs, argc_);
};
/*
* This struct contains metadata passed from the DOM to the JS Engine for JIT
* optimizations on DOM property accessors. Eventually, this should be made
* available to general JSAPI users, but we are not currently ready to do so.
*/
typedef bool
(* JSJitGetterOp)(JSContext* cx, JS::HandleObject thisObj,
void* specializedThis, JSJitGetterCallArgs args);
@ -2314,6 +2317,11 @@ typedef bool
(* JSJitMethodOp)(JSContext* cx, JS::HandleObject thisObj,
void* specializedThis, const JSJitMethodCallArgs& args);
/**
* This struct contains metadata passed from the DOM to the JS Engine for JIT
* optimizations on DOM property accessors. Eventually, this should be made
* available to general JSAPI users, but we are not currently ready to do so.
*/
struct JSJitInfo {
enum OpType {
Getter,
@ -2353,24 +2361,31 @@ struct JSJitInfo {
static_assert(Any & Object, "Any must include Object.");
static_assert(Any & Null, "Any must include Null.");
/**
* An enum that describes what this getter/setter/method aliases. This
* determines what things can be hoisted past this call, and if this
* call is movable what it can be hoisted past.
*/
enum AliasSet {
// An enum that describes what this getter/setter/method aliases. This
// determines what things can be hoisted past this call, and if this
// call is movable what it can be hoisted past.
// Alias nothing: a constant value, getting it can't affect any other
// values, nothing can affect it.
/**
* Alias nothing: a constant value, getting it can't affect any other
* values, nothing can affect it.
*/
AliasNone,
// Alias things that can modify the DOM but nothing else. Doing the
// call can't affect the behavior of any other function.
/**
* Alias things that can modify the DOM but nothing else. Doing the
* call can't affect the behavior of any other function.
*/
AliasDOMSets,
// Alias the world. Calling this can change arbitrary values anywhere
// in the system. Most things fall in this bucket.
/**
* Alias the world. Calling this can change arbitrary values anywhere
* in the system. Most things fall in this bucket.
*/
AliasEverything,
// Must be last.
/** Must be last. */
AliasSetCount
};
@ -2403,7 +2418,7 @@ struct JSJitInfo {
JSJitGetterOp getter;
JSJitSetterOp setter;
JSJitMethodOp method;
/* A DOM static method, used for Promise wrappers */
/** A DOM static method, used for Promise wrappers */
JSNative staticMethod;
};
@ -2423,16 +2438,18 @@ struct JSJitInfo {
#define JITINFO_RETURN_TYPE_BITS 8
#define JITINFO_SLOT_INDEX_BITS 10
// The OpType that says what sort of function we are.
/** The OpType that says what sort of function we are. */
uint32_t type_ : JITINFO_OP_TYPE_BITS;
// The alias set for this op. This is a _minimal_ alias set; in
// particular for a method it does not include whatever argument
// conversions might do. That's covered by argTypes and runtime
// analysis of the actual argument types being passed in.
/**
* The alias set for this op. This is a _minimal_ alias set; in
* particular for a method it does not include whatever argument
* conversions might do. That's covered by argTypes and runtime
* analysis of the actual argument types being passed in.
*/
uint32_t aliasSet_ : JITINFO_ALIAS_SET_BITS;
// The return type tag. Might be JSVAL_TYPE_UNKNOWN.
/** The return type tag. Might be JSVAL_TYPE_UNKNOWN. */
uint32_t returnType_ : JITINFO_RETURN_TYPE_BITS;
static_assert(OpTypeCount <= (1 << JITINFO_OP_TYPE_BITS),
@ -2446,29 +2463,46 @@ struct JSJitInfo {
#undef JITINFO_ALIAS_SET_BITS
#undef JITINFO_OP_TYPE_BITS
uint32_t isInfallible : 1; /* Is op fallible? False in setters. */
uint32_t isMovable : 1; /* Is op movable? To be movable the op must
not AliasEverything, but even that might
not be enough (e.g. in cases when it can
throw or is explicitly not movable). */
uint32_t isEliminatable : 1; /* Can op be dead-code eliminated? Again, this
depends on whether the op can throw, in
addition to the alias set. */
/** Is op fallible? False in setters. */
uint32_t isInfallible : 1;
/**
* Is op movable? To be movable the op must
* not AliasEverything, but even that might
* not be enough (e.g. in cases when it can
* throw or is explicitly not movable).
*/
uint32_t isMovable : 1;
/**
* Can op be dead-code eliminated? Again, this
* depends on whether the op can throw, in
* addition to the alias set.
*/
uint32_t isEliminatable : 1;
// XXXbz should we have a JSValueType for the type of the member?
uint32_t isAlwaysInSlot : 1; /* True if this is a getter that can always
get the value from a slot of the "this"
object. */
uint32_t isLazilyCachedInSlot : 1; /* True if this is a getter that can
sometimes (if the slot doesn't contain
UndefinedValue()) get the value from a
slot of the "this" object. */
uint32_t isTypedMethod : 1; /* True if this is an instance of
JSTypedMethodJitInfo. */
uint32_t slotIndex : JITINFO_SLOT_INDEX_BITS; /* If isAlwaysInSlot or
isSometimesInSlot is true,
the index of the slot to
get the value from.
Otherwise 0. */
/**
* True if this is a getter that can always
* get the value from a slot of the "this" object.
*/
uint32_t isAlwaysInSlot : 1;
/**
* True if this is a getter that can sometimes (if the slot doesn't contain
* UndefinedValue()) get the value from a slot of the "this" object.
*/
uint32_t isLazilyCachedInSlot : 1;
/** True if this is an instance of JSTypedMethodJitInfo. */
uint32_t isTypedMethod : 1;
/**
* If isAlwaysInSlot or isSometimesInSlot is true,
* the index of the slot to get the value from.
* Otherwise 0.
*/
uint32_t slotIndex : JITINFO_SLOT_INDEX_BITS;
static const size_t maxSlotIndex = (1 << JITINFO_SLOT_INDEX_BITS) - 1;
@ -2563,7 +2597,7 @@ bool IdMatchesAtom(jsid id, JSAtom* atom);
} // namespace detail
} // namespace js
/*
/**
* Must not be used on atoms that are representable as integer jsids.
* Prefer NameToId or AtomToId over this function:
*
@ -2629,7 +2663,7 @@ IdToValue(jsid id)
return JS::UndefinedValue();
}
/*
/**
* If the embedder has registered a ScriptEnvironmentPreparer,
* PrepareScriptEnvironmentAndInvoke will call the preparer's 'invoke' method
* with the given |closure|, with the assumption that the preparer will set up
@ -2657,7 +2691,7 @@ JS_FRIEND_API(void)
SetScriptEnvironmentPreparer(JSRuntime* rt, ScriptEnvironmentPreparer*
preparer);
/*
/**
* To help embedders enforce their invariants, we allow them to specify in
* advance which JSContext should be passed to JSAPI calls. If this is set
* to a non-null value, the assertSameCompartment machinery does double-
@ -2681,7 +2715,7 @@ enum CTypesActivityType {
typedef void
(* CTypesActivityCallback)(JSContext* cx, CTypesActivityType type);
/*
/**
* Sets a callback that is run whenever js-ctypes is about to be used when
* calling into C.
*/
@ -2713,7 +2747,7 @@ class MOZ_RAII JS_FRIEND_API(AutoCTypesActivityCallback) {
typedef JSObject*
(* ObjectMetadataCallback)(JSContext* cx, JSObject* obj);
/*
/**
* Specify a callback to invoke when creating each JS object in the current
* compartment, which may return a metadata object to associate with the
* object.
@ -2721,7 +2755,7 @@ typedef JSObject*
JS_FRIEND_API(void)
SetObjectMetadataCallback(JSContext* cx, ObjectMetadataCallback callback);
/* Get the metadata associated with an object. */
/** Get the metadata associated with an object. */
JS_FRIEND_API(JSObject*)
GetObjectMetadata(JSObject* obj);
@ -2732,7 +2766,7 @@ GetElementsWithAdder(JSContext* cx, JS::HandleObject obj, JS::HandleObject recei
JS_FRIEND_API(bool)
ForwardToNative(JSContext* cx, JSNative native, const JS::CallArgs& args);
/*
/**
* Helper function for HTMLDocument and HTMLFormElement.
*
* These are the only two interfaces that have [OverrideBuiltins], a named
@ -2773,28 +2807,30 @@ typedef long
(*JitExceptionHandler)(void* exceptionRecord, // PEXECTION_RECORD
void* context); // PCONTEXT
// Windows uses "structured exception handling" to handle faults. When a fault
// occurs, the stack is searched for a handler (similar to C++ exception
// handling). If the search does not find a handler, the "unhandled exception
// filter" is called. Breakpad uses the unhandled exception filter to do crash
// reporting. Unfortunately, on Win64, JIT code on the stack completely throws
// off this unwinding process and prevents the unhandled exception filter from
// being called. The reason is that Win64 requires unwind information be
// registered for all code regions and JIT code has none. While it is possible
// to register full unwind information for JIT code, this is a lot of work (one
// has to be able to recover the frame pointer at any PC) so instead we register
// a handler for all JIT code that simply calls breakpad's unhandled exception
// filter (which will perform crash reporting and then terminate the process).
// This would be wrong if there was an outer __try block that expected to handle
// the fault, but this is not generally allowed.
//
// Gecko must call SetJitExceptionFilter before any JIT code is compiled and
// only once per process.
/**
* Windows uses "structured exception handling" to handle faults. When a fault
* occurs, the stack is searched for a handler (similar to C++ exception
* handling). If the search does not find a handler, the "unhandled exception
* filter" is called. Breakpad uses the unhandled exception filter to do crash
* reporting. Unfortunately, on Win64, JIT code on the stack completely throws
* off this unwinding process and prevents the unhandled exception filter from
* being called. The reason is that Win64 requires unwind information be
* registered for all code regions and JIT code has none. While it is possible
* to register full unwind information for JIT code, this is a lot of work (one
* has to be able to recover the frame pointer at any PC) so instead we register
* a handler for all JIT code that simply calls breakpad's unhandled exception
* filter (which will perform crash reporting and then terminate the process).
* This would be wrong if there was an outer __try block that expected to handle
* the fault, but this is not generally allowed.
*
* Gecko must call SetJitExceptionFilter before any JIT code is compiled and
* only once per process.
*/
extern JS_FRIEND_API(void)
SetJitExceptionHandler(JitExceptionHandler handler);
#endif
/*
/**
* Get the nearest enclosing with scope object for a given function. If the
* function is not scripted or is not enclosed by a with scope, returns the
* global.
@ -2802,7 +2838,7 @@ SetJitExceptionHandler(JitExceptionHandler handler);
extern JS_FRIEND_API(JSObject*)
GetNearestEnclosingWithScopeObjectForFunction(JSFunction* fun);
/*
/**
* Get the first SavedFrame object in this SavedFrame stack whose principals are
* subsumed by the cx's principals. If there is no such frame, return nullptr.
*
@ -2831,7 +2867,7 @@ JS_StoreStringPostBarrierCallback(JSContext* cx,
void (*callback)(JSTracer* trc, JSString* key, void* data),
JSString* key, void* data);
/*
/**
* Forcibly clear postbarrier callbacks queued by the previous two methods.
* This should be used when the object owning the postbarriered pointers is
* being destroyed outside of a garbage collection.