OLD | NEW |
1 # Blink IDL Extended Attributes | 1 # Blink IDL Extended Attributes |
2 | 2 |
3 [TOC] | 3 [TOC] |
4 | 4 |
5 ## Introduction | 5 ## Introduction |
6 | 6 |
7 The main interest in extended attributes are their _semantics_: Blink implements
many more extended attributes than the Web IDL standard, to specify various beh
avior. | 7 The main interest in extended attributes are their _semantics_: Blink implements
many more extended attributes than the Web IDL standard, to specify various beh
avior. |
8 | 8 |
9 The authoritative list of allowed extended attributes and values is [bindings/ID
LExtendedAttributes.txt](https://code.google.com/p/chromium/codesearch#chromium/
src/third_party/WebKit/Source/bindings/IDLExtendedAttributes.txt). This is compl
ete but not necessarily precise (there may be unused extended attributes or valu
es), since validation is run on build, but coverage isn't checked. | 9 The authoritative list of allowed extended attributes and values is [bindings/ID
LExtendedAttributes.txt](https://code.google.com/p/chromium/codesearch#chromium/
src/third_party/WebKit/Source/bindings/IDLExtendedAttributes.txt). This is compl
ete but not necessarily precise (there may be unused extended attributes or valu
es), since validation is run on build, but coverage isn't checked. |
10 | 10 |
(...skipping 112 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
123 * `[ImplementedAs]` is only necessary for these legacy files: otherwise the clas
s (C++) implementing (IDL) implemented interfaces does not need to be specified,
as this is handled in Blink C++. | 123 * `[ImplementedAs]` is only necessary for these legacy files: otherwise the clas
s (C++) implementing (IDL) implemented interfaces does not need to be specified,
as this is handled in Blink C++. |
124 | 124 |
125 * `[OriginTrialEnabled]` behaves as for partial interfaces. | 125 * `[OriginTrialEnabled]` behaves as for partial interfaces. |
126 | 126 |
127 * `[RuntimeEnabled]` behaves as for partial interfaces. | 127 * `[RuntimeEnabled]` behaves as for partial interfaces. |
128 | 128 |
129 * `[NoInterfaceObject]` is _always_ specified on implemented interfaces. | 129 * `[NoInterfaceObject]` is _always_ specified on implemented interfaces. |
130 | 130 |
131 ### Inheritance | 131 ### Inheritance |
132 | 132 |
133 Extended attributes are generally not inherited: only extended attributes on the
interface itself are consulted. However, there are a handful of extended attrib
utes that are inherited (applying them to an ancestor interface applies them to
the descendants). These are extended attributes that affect memory management, a
nd currently consists of `[DependentLifetime]`; the up-to-date list is [compute_
dependencies.INHERITED_EXTENDED_ATTRIBUTES](https://code.google.com/p/chromium/c
odesearch#chromium/src/third_party/WebKit/Source/bindings/scripts/compute_depend
encies.py&q=INHERITED_EXTENDED_ATTRIBUTES). | 133 Extended attributes are generally not inherited: only extended attributes on the
interface itself are consulted. However, there are a handful of extended attrib
utes that are inherited (applying them to an ancestor interface applies them to
the descendants). These are extended attributes that affect memory management, a
nd currently consists of `[DependentLifetime]` and `[ActiveScriptWrappable]`; th
e up-to-date list is [compute_dependencies.INHERITED_EXTENDED_ATTRIBUTES](https:
//code.google.com/p/chromium/codesearch#chromium/src/third_party/WebKit/Source/b
indings/scripts/compute_dependencies.py&q=INHERITED_EXTENDED_ATTRIBUTES). |
134 | 134 |
135 ## Standard Web IDL Extended Attributes | 135 ## Standard Web IDL Extended Attributes |
136 | 136 |
137 These are defined in the [ECMAScript-specific extended attributes](http://heycam
.github.io/webidl/#es-extended-attributes) section of the [Web IDL spec](http://
heycam.github.io/webidl/), and alter the binding behavior. | 137 These are defined in the [ECMAScript-specific extended attributes](http://heycam
.github.io/webidl/#es-extended-attributes) section of the [Web IDL spec](http://
heycam.github.io/webidl/), and alter the binding behavior. |
138 | 138 |
139 *** note | 139 *** note |
140 Unsupported: `[ArrayClass]`, `[ImplicitThis]`, `[LenientThis]`, `[NamedPropertie
sObject]`, `[TreatNonCallableAsNull]` | 140 Unsupported: `[ArrayClass]`, `[ImplicitThis]`, `[LenientThis]`, `[NamedPropertie
sObject]`, `[TreatNonCallableAsNull]` |
141 *** | 141 *** |
142 | 142 |
143 ### [Clamp] _(a, p)_ | 143 ### [Clamp] _(a, p)_ |
(...skipping 327 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
471 Standard: [Unscopeable](http://heycam.github.io/webidl/#Unscopeable) | 471 Standard: [Unscopeable](http://heycam.github.io/webidl/#Unscopeable) |
472 | 472 |
473 Summary: The interface member will not appear as a named property within `with`
statements. | 473 Summary: The interface member will not appear as a named property within `with`
statements. |
474 | 474 |
475 Usage: Can be specified on attributes or interfaces. | 475 Usage: Can be specified on attributes or interfaces. |
476 | 476 |
477 ## Common Blink-specific IDL Extended Attributes | 477 ## Common Blink-specific IDL Extended Attributes |
478 | 478 |
479 These extended attributes are widely used. | 479 These extended attributes are widely used. |
480 | 480 |
| 481 ### [ActiveScriptWrappable] _(i)_ |
| 482 |
| 483 Summary: `[ActiveScriptWrappable]` indicates that a given DOM object should be k
ept alive as long as the DOM object has pending activities. |
| 484 |
| 485 Usage: `[ActiveScriptWrappable]` can be specified on interfaces, and **is inheri
ted**: |
| 486 |
| 487 ```webidl |
| 488 [ |
| 489 ActiveScriptWrappable, |
| 490 ] interface Foo { |
| 491 ... |
| 492 }; |
| 493 ``` |
| 494 |
| 495 If an interface X has `[ActiveScriptWrappable]` and an interface Y inherits the
interface X, then the interface Y will also have `[ActiveScriptWrappable]`. For
example |
| 496 |
| 497 ```webidl |
| 498 [ |
| 499 ActiveScriptWrappable, |
| 500 ] interface Foo {}; |
| 501 ``` |
| 502 |
| 503 interface Bar : Foo {}; // inherits [ActiveScriptWrappable] from Foo |
| 504 If a given DOM object needs to be kept alive as long as the DOM object has pendi
ng activities, you need to specify `[ActiveScriptWrappable]` and `[DependentLife
time]`. For example, `[ActiveScriptWrappable]` can be used when the DOM object i
s expecting events to be raised in the future. |
| 505 |
| 506 If you use `[ActiveScriptWrappable]`, the corresponding Blink class needs to inh
erit ActiveScriptWrappable. For example, in case of XMLHttpRequest, core/xml/XML
HttpRequest.h would look like this: |
| 507 |
| 508 ```c++ |
| 509 class XMLHttpRequest : public ActiveScriptWrappable |
| 510 { |
| 511 ...; |
| 512 } |
| 513 ``` |
| 514 |
481 ### [PerWorldBindings] _(m, a)_ | 515 ### [PerWorldBindings] _(m, a)_ |
482 | 516 |
483 Summary: Generates faster bindings code by avoiding check for isMainWorld(). | 517 Summary: Generates faster bindings code by avoiding check for isMainWorld(). |
484 | 518 |
485 This optimization only makes sense for wrapper-types (i.e. types that have a cor
responding IDL interface), as we don't need to check in which world we are for o
ther types. | 519 This optimization only makes sense for wrapper-types (i.e. types that have a cor
responding IDL interface), as we don't need to check in which world we are for o
ther types. |
486 | 520 |
487 *** note | 521 *** note |
488 This optimization works by generating 2 separate code paths for the main world a
nd for isolated worlds. As a consequence, using this extended attribute will inc
rease binary size and we should refrain from overusing it. | 522 This optimization works by generating 2 separate code paths for the main world a
nd for isolated worlds. As a consequence, using this extended attribute will inc
rease binary size and we should refrain from overusing it. |
489 *** | 523 *** |
490 | 524 |
(...skipping 370 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
861 [ | 895 [ |
862 DependentLifetime, | 896 DependentLifetime, |
863 ] interface Foo { ... }; | 897 ] interface Foo { ... }; |
864 | 898 |
865 interface Bar : Foo { ... }; // inherits [DependentLifetime] | 899 interface Bar : Foo { ... }; // inherits [DependentLifetime] |
866 ``` | 900 ``` |
867 | 901 |
868 If a DOM object does not have `[DependentLifetime]`, V8's GC collects the wrappe
r of the DOM object | 902 If a DOM object does not have `[DependentLifetime]`, V8's GC collects the wrappe
r of the DOM object |
869 if the wrapper is unreachable on the JS side (i.e., V8's GC assumes that the wra
pper should not be | 903 if the wrapper is unreachable on the JS side (i.e., V8's GC assumes that the wra
pper should not be |
870 reachable in the DOM side). Use `[DependentLifetime]` to relax the assumption. | 904 reachable in the DOM side). Use `[DependentLifetime]` to relax the assumption. |
871 For example, if the DOM object implements hasPendingActivity(), it must be annot
ated with | 905 For example, if the DOM object has `[ActiveScriptWrappable]` and implements hasP
endingActivity(), it must be annotated with |
872 `[DependentLifetime]`. Otherwise, the wrapper will be collected regardless of th
e returned value | 906 `[DependentLifetime]`. Otherwise, the wrapper will be collected regardless of th
e returned value |
873 of the hasPendingActivity(). DOM objects that are pointed to by `[SetWrapperRefe
renceFrom]` and | 907 of the hasPendingActivity(). DOM objects that are pointed to by `[SetWrapperRefe
renceFrom]` and |
874 `[SetWrapperReferenceTo]` must be annotated with `[DependentLifetime]`. | 908 `[SetWrapperReferenceTo]` must be annotated with `[DependentLifetime]`. |
875 | 909 |
876 ### [DeprecateAs] _(m, a, c)_ | 910 ### [DeprecateAs] _(m, a, c)_ |
877 | 911 |
878 Summary: Measures usage of a deprecated feature via UseCounter, and notifies dev
elopers about deprecation via a console warning. | 912 Summary: Measures usage of a deprecated feature via UseCounter, and notifies dev
elopers about deprecation via a console warning. |
879 | 913 |
880 `[DeprecateAs]` can be considered an extended form of `[MeasureAs]`: it both mea
sures the feature's usage via the same UseCounter mechanism, and also sends out
a warning to the console (optionally with a message) in order to inform develope
rs that the code they've written will stop working at some point in the relative
ly near future. | 914 `[DeprecateAs]` can be considered an extended form of `[MeasureAs]`: it both mea
sures the feature's usage via the same UseCounter mechanism, and also sends out
a warning to the console (optionally with a message) in order to inform develope
rs that the code they've written will stop working at some point in the relative
ly near future. |
881 | 915 |
(...skipping 675 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1557 Copyright (C) 2009 Apple Inc. All rights reserved. | 1591 Copyright (C) 2009 Apple Inc. All rights reserved. |
1558 | 1592 |
1559 Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met: | 1593 Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met: |
1560 | 1594 |
1561 1. Redistributions of source code must retain the above copyright notice, this l
ist of conditions and the following disclaimer. | 1595 1. Redistributions of source code must retain the above copyright notice, this l
ist of conditions and the following disclaimer. |
1562 | 1596 |
1563 2. Redistributions in binary form must reproduce the above copyright notice, thi
s list of conditions and the following disclaimer in the documentation and/or ot
her materials provided with the distribution. | 1597 2. Redistributions in binary form must reproduce the above copyright notice, thi
s list of conditions and the following disclaimer in the documentation and/or ot
her materials provided with the distribution. |
1564 | 1598 |
1565 THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS “AS IS” AND ANY EXP
RESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIE
S OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, I
NCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMI
TED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFI
TS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHE
THER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSI
BILITY OF SUCH DAMAGE. | 1599 THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS “AS IS” AND ANY EXP
RESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIE
S OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, I
NCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMI
TED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFI
TS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHE
THER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSI
BILITY OF SUCH DAMAGE. |
1566 *** | 1600 *** |
OLD | NEW |