Changes between Version 50 and Version 51 of WebKitIDL


Ignore:
Timestamp:
Feb 20, 2012, 1:25:03 AM (13 years ago)
Author:
haraken@chromium.org
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WebKitIDL

    v50 v51  
    517517==  [ReturnNewObject](m,a) == #ReturnNewObject
    518518
    519 Summary: [ReturnNewObject] controls whether WebCore can return a cached wrapper object or WebCore needs to return a newly created wrapper object every time.
     519Summary: [ReturnNewObject] controls whether WebCore can return a cached wrapped object or WebCore needs to return a newly created wrapped object every time.
    520520
    521521Usage: [ReturnNewObject] can be specified on methods or attributes:
    … …  
    525525}}}
    526526
    527 Without [ReturnNewObject], JavaScriptCore and V8 cache a wrapper object for performance.
     527Without [ReturnNewObject], JavaScriptCore and V8 cache a wrapped object for performance.
    528528For example, consider the case where node.firstChild is accessed:
    529529
    530530 1. Node::firstChild() is called in WebCore.
    531531 1. The result of Node::firstChild() is passed to toJS() or toV8().
    532  1. toJS() or toV8() checks if a wrapper object of the result is already cached on the node.
    533  1. If cached, the cached wrapper object is returned. That's it.
    534  1. Otherwise, toJS() or toV8() creates the wrapper object of the result.
    535  1. The created wrapper object is cached on the node.
    536  1. The wrapper object is returned.
    537 
    538 On the other hand, if you do not want to cache the wrapper object and want to create the wrapper object every time,
     532 1. toJS() or toV8() checks if a wrapped object of the result is already cached on the node.
     533 1. If cached, the cached wrapped object is returned. That's it.
     534 1. Otherwise, toJS() or toV8() creates the wrapped object of the result.
     535 1. The created wrapped object is cached on the node.
     536 1. The wrapped object is returned.
     537
     538On the other hand, if you do not want to cache the wrapped object and want to create the wrapped object every time,
    539539you can specify [ReturnNewObject].
    540540
    … …  
    565565ADD EXPLANATIONS
    566566
    567 ==  [Replaceable](a) == #Replaceable
    568 
    569  * [http://dev.w3.org/2006/webapi/WebIDL/#Replaceable The spec of replaceable]
    570 
    571 Summary: It controls if a given attribute is "replaceable" or not.
     567== [Replaceable](a) == #Replaceable
     568
     569 * [http://dev.w3.org/2006/webapi/WebIDL/#Replaceable The spec of Replaceable]
     570
     571Summary: [Replaceable] controls if a given attribute is "replaceable" or not.
    572572
    573573Usage: [Replaceable] can be specified on attributes:
    … …  
    578578}}}
    579579
    580 Intuitively, "replaceable" means that you can set a new value to the attribute without overwriting the current value.
    581 If you delete the new value, then the old value still remains.
     580Intuitively, "replaceable" means that you can set a new value to the attribute without overwriting the original value.
     581If you delete the new value, then the original value still remains.
    582582
    583583Specifically, without [Replaceable], the attribute behaves as follows:
    … …  
    587587    window.screenX; // Evaluates to "foo"
    588588    delete window.screenX;
    589     window.screenX; // Evaluates to undefined
     589    window.screenX; // Evaluates to undefined. 0 is lost.
    590590}}}
    591591
    … …  
    596596    window.screenX; // Evaluates to "foo"
    597597    delete window.screenX;
    598     window.screenX; // Evaluates to 0
    599 }}}
    600 
    601 Whether you should specify [Replaceable] or not depends on the spec of each attribute.
    602 
     598    window.screenX; // Evaluates to 0. 0 remains.
     599}}}
     600
     601Whether [Replaceable] should be specified or not depends on the spec of each attribute.
    603602
    604603==  [Deletable](a), [NotEnumerable](a), [V8ReadOnly](a) == #Deletable
    605604
    606  * [http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf The spec of Writable, Enumerable and Configurable (8.6.1)]
     605 * [http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf The spec of Writable, Enumerable and Configurable (Section 8.6.1)]
    607606
    608607Summary: They control Writability, Enumerability and Configurability of attributes.
    … …  
    617616By default, non-"readonly" attributes are enumerable, writable and not deletable. "readonly" attributes are enumerable, not writable and not deletable. You can change the default behavior using [Deletable], [NotEnumerable] or [V8ReadOnly].
    618617
    619 [Deletable] indicates that the attribute is deletable. [NotEnumerable] indicates that the attribute is not enumerable. [V8ReadOnly] indicates that the attribute is readonly in V8 even if the attribute is not prefixed by "readonly".
    620 
    621 ==  [CachedAttribute](a) == #CachedAttribute
    622 
    623 Summary: For performance optimization, it indicates to cache a wrapped object in a DOM object.
     618 * [Deletable] indicates that the attribute is deletable.
     619 * [NotEnumerable] indicates that the attribute is not enumerable.
     620 * [V8ReadOnly] indicates that the attribute is readonly in V8 even if the attribute is not prefixed by "readonly".
     621
     622== [CachedAttribute](a) == #CachedAttribute
     623
     624Summary: For performance optimization, [CachedAttribute] indicates that a wrapped object should be cached on a DOM object.
    624625
    625626Usage: [CachedAttribute] can be specified on attributes:
    … …  
    633634Without [CachedAttribute], the normalValue getter works in the following way:
    634635
    635  * HTMLFoo::normalValue() is called.
    636  * The result is passed to toJS() or toV8(), and is converted to a wrapper object.
    637  * The wrapper object is returned.
    638 
    639 In case where HTMLFoo::normalValue() and wrapping the result is weight,
    640 you can cache the wrapped object in the DOM object by using [CachedAttribute].
     636 1. HTMLFoo::normalValue() is called in WebCore.
     637 1. The result of HTMLFoo::normalValue() is passed to toJS() or toV8(), and is converted to a wrapped object.
     638 1. The wrapped object is returned.
     639
     640In case where HTMLFoo::normalValue() or the operation to wrap the result is weight,
     641you can cache the wrapped object onto the DOM object.
    641642With [CachedAttribute], the normalValue getter works in the following way:
    642643
    643  * If the wrapper object is cached, the cached wrapper object is returned.
    644  * Otherwise, HTMLFoo::normalValue() is called.
    645  * The result is passed to toJS() or toV8(), and is converted to a wrapped object.
    646  * The wrapped object is cached.
    647  * The wrapped object is returned.
    648 
    649 In particular, [CachedAttribute] will be helpful for serialized values.
     644 1. If the wrapped object is cached, the cached wrapped object is returned. That's it.
     645 1. Otherwise, HTMLFoo::normalValue() is called in WebCore.
     646 1. The result of HTMLFoo::normalValue() is passed to toJS() or toV8(), and is converted to a wrapped object.
     647 1. The wrapped object is cached.
     648 1. The wrapped object is returned.
     649
     650In particular, [CachedAttribute] will be useful for serialized values, since deserialization can be weight.
    650651Without [CachedAttribute], the serializedValue getter works in the following way:
    651652
    652  * HTMLFoo::serializedValue() is called.
    653  * The result is deserialized.
    654  * The deserialized result is passed to toJS() or toV8(), and is converted to a wrapped object.
    655  * The wrapped object is returned.
    656 
    657 In case where HTMLFoo::serializedValue(), deserializing and wrapping the result is weight,
    658 you can cache the wrapped object to the DOM object by specifying [CachedAttribute].
     653 1. HTMLFoo::serializedValue() is called in WebCore.
     654 1. The result of HTMLFoo::serializedValue() is deserialized.
     655 1. The deserialized result is passed to toJS() or toV8(), and is converted to a wrapped object.
     656 1. The wrapped object is returned.
     657
     658In case where HTMLFoo::serializedValue(), the deserialization or the operation to wrap the result is weight,
     659you can cache the wrapped object onto the DOM object.
    659660With [CachedAttribute], the serializedValue getter works in the following way:
    660661
    661  * If the wrapper object is cached, the cached wrapper object is returned.
    662  * Otherwise, HTMLFoo::serializedValue() is called.
    663  * The result is deserialized.
    664  * The deserialized result is passed to toJS() or toV8(), and is converted to a wrapped object.
    665  * The wrapped object is cached.
    666  * The wrapped object is returned.
     662 1. If the wrapped object is cached, the cached wrapped object is returned. That's it.
     663 1. Otherwise, HTMLFoo::serializedValue() is called in WebCore.
     664 1. The result of HTMLFoo::serializedValue() is deserialized.
     665 1. The deserialized result is passed to toJS() or toV8(), and is converted to a wrapped object.
     666 1. The wrapped object is cached.
     667 1. The wrapped object is returned.
    667668
    668669Note that you should cache attributes if and only if it is really important for performance.
    669670Not only does caching increase the DOM object size,
    670 but also it increases the overhead of "cache-miss"ed getters and setters (Setters always need to invalidate the caches).
     671but also it increases the overhead of "cache-miss"ed getters.
     672In addition, setters always need to invalidate the cache.
    671673
    672674==  [V8Unforgeable](m,a), [V8OnProto](m,a) == #V8Unforgeable
    … …  
    674676 * [http://dev.w3.org/2006/webapi/WebIDL/#Unforgeable The spec of Unforgeable]
    675677
    676 Summary: They control where a given attribute getter/setter is defined.
    677 
    678 Usage: They can be specified on attributes:
    679 {{{
    680     attribute [V8Unforgeable] DOMString str1;
    681     attribute [V8OnProto] DOMString str2;
     678Summary: They control where a getter/setter of a given attribute is defined.
     679
     680Usage: They can be specified on methods or attributes:
     681{{{
     682    [V8Unforgeable] void func();
     683    attribute [V8OnProto] DOMString str;
    682684}}}
    683685
    … …  
    687689If you want to explicitly control where an attribute getter/setter or a method is defined in V8,
    688690you can use [V8Unforgeable] or [V8OnProto].
    689 [V8Unforgeable] indicates that the attribute getter/setter or the method should be defined on a DOM object.
    690 On the other hand, [V8OnProto] indicates that the attribute getter/setter or the method should be defined on a chain.
     691
     692 * [V8Unforgeable] indicates that an attribute getter/setter or a method should be defined on a DOM object.
     693 * [V8OnProto] indicates that an attribute getter/setter or a method should be defined on a prototype chain.
    691694
    692695Note: As explained above, the current implementation of JSC and V8 is wrong with the Web IDL spec,
    … …  
    694697You should not use them unless you have a strong reason to use them.
    695698
    696 ==  [URL](a) == #URL
    697 
    698 Summary: It indicates that a given DOMString is a URL.
    699 
    700 Usage: [URL] can be specified on DOMString attributes:
    701 {{{
    702     attribute [Reflect, V8URL] DOMString url;
    703 }}}
    704 
    705 You must specify [URL] if the DOMString represents URL,
    706 since URL attribute getters are realized in a special routine in WebKit, i.e. Element::getURLAttribute().
     699== [URL](a) == #URL
     700
     701Summary: [URL] indicates that a given DOMString represents a URL.
     702
     703Usage: [URL] can be specified on DOMString attributes only:
     704{{{
     705    attribute [Reflect, URL] DOMString url;
     706}}}
     707
     708You need to specify [URL] if a given DOMString represents a URL,
     709since getters of URL attributes need to be realized in a special routine in WebKit, i.e. Element::getURLAttribute(...).
    707710If you forgot to specify [URL], then the attribute getter might cause a bug.
    708711
    709 ==  [JSWindowEventListener](a) FIXME == #JSWindowEventListener
     712== [JSWindowEventListener](a) FIXME == #JSWindowEventListener
    710713
    711714Summary: ADD SUMMARY
    712715
    713 Usage: [JSWindowEventListener] can be specified on EventListener attributes.
     716Usage: [JSWindowEventListener] can be specified on EventListener attributes only:
    714717{{{
    715718    attribute [JSWindowEventListener] EventListener onload;