Title: [148974] trunk/Source/_javascript_Core
- Revision
- 148974
- Author
- [email protected]
- Date
- 2013-04-23 11:00:33 -0700 (Tue, 23 Apr 2013)
Log Message
Objective-C API: Update public header documentation
https://bugs.webkit.org/show_bug.cgi?id=114841
Reviewed by Geoffrey Garen.
Added documentation for the newly added object lifetime-related stuff.
* API/JSManagedValue.h:
* API/JSVirtualMachine.h:
Modified Paths
Diff
Modified: trunk/Source/_javascript_Core/API/JSManagedValue.h (148973 => 148974)
--- trunk/Source/_javascript_Core/API/JSManagedValue.h 2013-04-23 17:50:01 UTC (rev 148973)
+++ trunk/Source/_javascript_Core/API/JSManagedValue.h 2013-04-23 18:00:33 UTC (rev 148974)
@@ -33,13 +33,30 @@
@class JSValue;
@class JSContext;
+// JSManagedValue represents a "conditionally retained" JSValue.
+// "Conditionally retained" means that as long as either the JSManagedValue
+// _javascript_ value is reachable through the _javascript_ object graph
+// or the JSManagedValue object is reachable through the external Objective-C
+// object graph as reported to the JSVirtualMachine using
+// addManagedReference:withOwner:, the corresponding _javascript_ value will
+// be retained. However, if neither of these conditions are true, the
+// corresponding JSValue will be released and set to nil.
+//
+// The primary use case for JSManagedValue is for safely referencing JSValues
+// from the Objective-C heap. It is incorrect to store a JSValue into an
+// Objective-C heap object, as this can very easily create a reference cycle,
+// keeping the entire JSContext alive.
NS_CLASS_AVAILABLE(10_9, NA)
@interface JSManagedValue : NSObject
+// Convenience method for creating JSManagedValues from JSValues.
+ (JSManagedValue *)managedValueWithValue:(JSValue *)value;
+// Create a JSManagedValue.
- (id)initWithValue:(JSValue *)value;
+// Get the JSValue to which this JSManagedValue refers. If the _javascript_ value has been collected,
+// this method returns nil.
- (JSValue *)value;
@end
Modified: trunk/Source/_javascript_Core/API/JSVirtualMachine.h (148973 => 148974)
--- trunk/Source/_javascript_Core/API/JSVirtualMachine.h 2013-04-23 17:50:01 UTC (rev 148973)
+++ trunk/Source/_javascript_Core/API/JSVirtualMachine.h 2013-04-23 18:00:33 UTC (rev 148974)
@@ -35,8 +35,21 @@
NS_CLASS_AVAILABLE(10_9, NA)
@interface JSVirtualMachine : NSObject
+// Create a new JSVirtualMachine.
- (id)init;
+// addManagedReference:withOwner and removeManagedReference:withOwner allow
+// clients of JSVirtualMachine to make the _javascript_ runtime aware of
+// arbitrary external Objective-C object graphs. The runtime can then use
+// this information to retain any _javascript_ values that are referenced
+// from somewhere in said object graph.
+//
+// For correct behavior clients must make their external object graphs
+// reachable from within the _javascript_ runtime. If an Objective-C object is
+// reachable from within the _javascript_ runtime, all managed references
+// transitively reachable from it as recorded with
+// addManagedReference:withOwner: will be scanned by the garbage collector.
+//
- (void)addManagedReference:(id)object withOwner:(id)owner;
- (void)removeManagedReference:(id)object withOwner:(id)owner;
Modified: trunk/Source/_javascript_Core/ChangeLog (148973 => 148974)
--- trunk/Source/_javascript_Core/ChangeLog 2013-04-23 17:50:01 UTC (rev 148973)
+++ trunk/Source/_javascript_Core/ChangeLog 2013-04-23 18:00:33 UTC (rev 148974)
@@ -1,3 +1,15 @@
+2013-04-18 Mark Hahnenberg <[email protected]>
+
+ Objective-C API: Update public header documentation
+ https://bugs.webkit.org/show_bug.cgi?id=114841
+
+ Reviewed by Geoffrey Garen.
+
+ Added documentation for the newly added object lifetime-related stuff.
+
+ * API/JSManagedValue.h:
+ * API/JSVirtualMachine.h:
+
2013-04-22 Mark Lam <[email protected]>
Fix a typo in MacroAssemblerARMv7.h.
_______________________________________________
webkit-changes mailing list
[email protected]
https://lists.webkit.org/mailman/listinfo/webkit-changes
