Changeset 15484 in webkit for trunk/JavaScriptCore/API/JSObjectRef.h

Timestamp:

Jul 17, 2006, 3:49:28 AM (19 years ago)

Author:

ggaren

Message:

Reviewed by Maciej.

• Removed the exception parameter from the initialize callback and, by extension, JSObjectMake. We have never had a need for exceptions when iniitializing, so the parameter seemed likely to "get in the way."

Also, an exception in JavaScript is thrown in response to input --
"invalid URL", "index not a number", etc., so it's the job of the
constructor function, not the initialize method, to throw.

If initialize *really* wants to throw, it can communicate the throw to
the constructor through the constructed object's private data (e.g., set
it to NULL, signaling to the consntructor that initialization failed.)

• Added JSObjectMakeWithData, which enables a constructor to set private data on an object *before* it has been initialized. That way, the initialize methods can properly operate on the data.

• API/JSNode.c: Moved ref into the initialize method, for better encapsulation, now that it's possible.
• API/JSNodeList.c: ditto
• API/minidom.c: (main): Do more aggressive garbage collection to test ref/deref and initialize/finalize.
• API/minidom.js: store childNodes in a temporary so it doesn't get re-created like a thousand times. This makes debugging ref/deref easier

File:

• trunk/JavaScriptCore/API/JSObjectRef.h (modified) (5 diffs)

trunk/JavaScriptCore/API/JSObjectRef.h

@@ -63 +63 @@
 @param ctx The execution context to use.
 @param object The JSObject being created.
-@param exception A pointer to a JSValueRef in which to return an exception, if any.
 @discussion If you named your function Initialize, you would declare it like this:
 
-void Initialize(JSContextRef ctx, JSObjectRef object, JSValueRef* exception);
+void Initialize(JSContextRef ctx, JSObjectRef object);
 
 Unlike the other object callbacks, the initialize callback is called on the least
@@ -72 +71 @@
 */
 typedef void
-(*JSObjectInitializeCallback) (JSContextRef ctx, JSObjectRef object, JSValueRef* exception);
+(*JSObjectInitializeCallback) (JSContextRef ctx, JSObjectRef object);
 
 /*! 
@@ -380 +379 @@
 /*!
 @function
-@abstract Creates a JavaScript object with a given class and prototype.
+@abstract Creates a JavaScript object.
 @param ctx The execution context to use.
 @param jsClass The JSClass to assign to the object. Pass NULL to use the default object class.
 @param prototype The prototype to assign to the object. Pass NULL to use the default object prototype.
-@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
-@result A JSObject with the given class and prototype.
-*/
-JSObjectRef JSObjectMake(JSContextRef ctx, JSClassRef jsClass, JSValueRef prototype, JSValueRef* exception);
+@result A JSObject with the given class, prototype, and private data.
+@discussion The default object class does not allocate storage for private data, so you must provide a non-NULL JSClass if you want your object to be able to store private data.
+*/
+JSObjectRef JSObjectMake(JSContextRef ctx, JSClassRef jsClass, JSValueRef prototype);
+
+/*!
+@function
+@abstract Creates a JavaScript object.
+@param ctx The execution context to use.
+@param jsClass The JSClass to assign to the object. Pass NULL to use the default object class.
+@param prototype The prototype to assign to the object. Pass NULL to use the default object prototype.
+@param data A void* to set as the object's private data. Pass NULL to specify no private data.
+@param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
+@result A JSObject with the given class, prototype, and private data.
+@discussion The default object class does not allocate storage for private data, so you must provide a non-NULL JSClass if you want your object to be able to store private data.
+ 
+data will be set on the created object before the intialize methods in its class chain are called. This enables the initialize methods to retrieve and manipulate data through JSObjectGetPrivate.
+*/
+JSObjectRef JSObjectMakeWithData(JSContextRef ctx, JSClassRef jsClass, JSValueRef prototype, void* data);
 
 /*!
@@ -512 +526 @@
 /*!
 @function
-@abstract Gets a pointer to private data from an object.
+@abstract Gets an object's private data.
 @param object A JSObject whose private data you want to get.
-@result A void* that points to the object's private data, if the object has private data, otherwise NULL.
+@result A void* that is the object's private data, if the object has private data, otherwise NULL.
 */
 void* JSObjectGetPrivate(JSObjectRef object);
@@ -522 +536 @@
 @abstract Sets a pointer to private data on an object.
 @param object A JSObject whose private data you want to set.
-@param data A void* that points to the object's private data.
+@param data A void* to set as the object's private data.
 @result true if the object can store private data, otherwise false.
-@discussion Only custom objects created with a JSClass can store private data.
+@discussion The default object class does not allocate storage for private data. Only objects created with a non-NULL JSClass can store private data.
 */
 bool JSObjectSetPrivate(JSObjectRef object, void* data);