Web IDL in Blink
Blink developers (non-bindings development): for general IDL use, see Web IDL interfaces; for configuring bindings, see Blink IDL Extended Attributes; for IDL dictionaries use, see IDL dictionaries in Blink.
Overview?Web IDL is a language that defines how Blink interfaces are bound to V8. You need to write IDL files (e.g. xml_http_request.idl, element.idl, etc) to expose Blink interfaces to those external languages. When Blink is built, the IDL files are parsed, and the code to bind Blink implementations to V8 interfaces automatically generated. This document describes practical information about how the IDL bindings work and how you can write IDL files in Blink. The syntax of IDL files is fairly well documented in the ?Web IDL spec, but it is too formal to read :-) and there are several differences between the Web IDL spec and the Blink IDL due to implementation issues. For design docs on bindings generation, see IDL build and IDL compiler. For Blink developers, the main details of IDLs are the extended attributes, which control implementation-specific behavior: see Blink IDL Extended Attributes for extensive details. Our goal is to converge Blink‘s IDL and Web IDL. The grammar is almost identical; see below. Basics of IDLHere is an example of IDL files: [CustomToV8] interface Node { const unsigned short ELEMENT_NODE = 1; attribute Node parentNode; [TreatReturnedNullStringAs=Null] attribute DOMString nodeName; [Custom] Node appendChild(Node newChild); void addEventListener(DOMString type, EventListener listener, optional boolean useCapture); };
Let us introduce some terms:
The key points are as follows:
The valid extended attributes depend on where they attach: interfaces and methods have different extended attributes. A simple IDL file template looks like: interface INTERFACE_NAME { const unsigned long value = 12345; attribute Node node; void func(long argument, ...); };
With extended attributes, this looks like: [ EXTATTR, EXTATTR, ..., ] interface INTERFACE_NAME { const unsigned long value = 12345; [EXTATTR, EXTATTR, ...] attribute Node node; [EXTATTR, EXTATTR, ...] void func([EXTATTR, EXTATTR, ...] optional [EXTATTR] long argument, ...); };
SyntaxBlink IDL is a dialect of Web IDL. The lexical syntax is identical, but the phrase syntax is slightly different. Implementation-wise, the lexer and parser are written in PLY (Python lex-yacc), an implementation of lex and yacc for Python. A standard-compliant lexer is used (Chromium tools/idl_parser/idl_lexer.py). The parser (Blink bindings/scripts/blink_idl_parser.py) derives from a standard-compliant parser (Chromium tools/idl_parser/idl_parser.py). Blink deviations from the Web IDL standard can be seen as the BNF production rules in the derived parser. Style Style guidelines are to generally follow Blink style for C++, with a few points highlighted, addenda, and exceptions. These are not enforced by a pre-submit test, but do assist legibility:
[ A, B /* No trailing commas on the last extended attribute */ ] interface Foo { ... }; interface Bar { ... };
getter DOMString (unsigned long index); // Not: DOMString(unsigned long index)
// Indexed property operations getter DOMString (unsigned long index); setter DOMString (unsigned long index, DOMString value); deleter boolean (unsigned long index); // Named property operations getter DOMString (DOMString name); setter DOMString (DOMString name, DOMString value); deleter boolean (DOMString name);
SemanticsWeb IDL exposes an interface to JavaScript, which is implemented in C++. Thus its semantics bridge these two languages, though it is not identical to either. Web IDL‘s semantics are much closer to C++ than to JavaScript – in practice, it is a relatively thin abstraction layer over C++. Thus C++ implementations are quite close to the IDL spec, though the resulting interface is somewhat unnatural from a JavaScript perspective: it behaves differently from normal JavaScript libraries.
TypesSee: Web IDL types.
Primitive types in Web IDL are very close to fundamental types in C++ (booleans, characters, integers, and floats), though note that there is no
int type in Web IDL (specs usually use long instead).undefined and nullJavaScript has two special values,
undefined and null , which are often confusing and do not fit easily into C++. Indeed, precise behavior of undefined in Web IDL has varied over time and is under discussion (see W3C Bug 23532 - Dealing with undefined).Behavior on
undefined and null MUST be tested in web tests, as these can be passed and are easy to get wrong. If these tests are omitted, there may be crashes (which will be caught by ClusterFuzz) or behavioral bugs (which will show up as web pages or JavaScript libraries breaking).For the purposes of Blink, behavior can be summarized as follows:
Function resolutionWeb IDL has required arguments and optional arguments. JavaScript does not: omitted arguments have Thus if you have the following Web IDL function declaration: interface A { void foo(long x); };
...the JavaScript However, in JavaScript the corresponding function can be called without arguments: function foo(x) { return x } foo() // undefined
Note that To get similar behavior in Web IDL, the argument can be explicitly specified as For example, given an optional argument such as: interface A { void foo(optional long x); };
This results in a = new A(); a.foo() being legal, and calling the underlying Blink C++ function implementing For overloaded operations, the situation is more complicated, and not currently implemented in Blink (Bug 293561). See the overload resolution algorithm in the spec for details. Pragmatically, passing Passing interface A { void foo(optional long x); void foo(Node x); };
This results in a = new A(); a.foo(undefined) resolving to the first Note that Blink code implementing a function can also check arguments, and similarly, JavaScript functions can check arguments, and access the number of arguments via Warning: File organizationThe Web IDL spec treats the Web API as a single API, spread across various IDL fragments. In practice these fragments are
.idl files, stored in the codebase alongside their implementation, with basename equal to the interface name. Thus for example the fragment defining the Node interface is written in node.idl , which is stored in the third_party/blink/renderer/core/dom directory, and is accompanied by node.h and node.cc in the same directory. In some cases the implementation has a different name, in which case there must be an [ImplementedAs=...] extended attribute in the IDL file, and the .h/.cc files have basename equal to the value of the [ImplementedAs=...] .For simplicity, each IDL file contains a single interface or dictionary, and contains all information needed for that definition, except for dependencies (below), notably any enumerations, implements statements, typedefs, and callback functions.
DependenciesIn principle (as a matter of the Web IDL spec) any IDL file can depend on any other IDL file, and thus changing one file can require rebuilding all the dependents. In practice there are 4 kinds of dependencies (since other required definitions, like enumerations and typedefs, are contained in the IDL file for the interface):
In practice, what happens is that, when compiling a given interfaces, its partial interfaces and the other interfaces it implements are merged into a single data structure, and that is compiled. There is a small amount of data recording where exactly a member came from (so the correct C++ class can be called), and a few other extended attributes for switching the partial/implemented interface on or off, but otherwise it is as if all members were specified in a single
interface statement. This is a deep dependency relationship: any change in the partial/implemented interface changes the bindings for the overall (merged) interface, since all the data is in fact used.Bindings for interfaces in general do not depend on their ancestors, beyond the name of their immediate parent. This is because the bindings just generate a class, which refers to the parent class, but otherwise is subject to information hiding. However, in a few cases bindings depend on whether the interface inherits from some other interface (notably EventHandler or Node), and in a few cases bindings depend on the extended attributes of ancestors (these extended attributes are "inherited"; the list is compute_dependencies.INHERITED_EXTENDED_ATTRIBUTES, and consists of extended attributes that affect memory management). There is thus a shallow dependency on ancestors, specifically only on the ancestor chain and on inherited extended attributes, not on the other contents of ancestors. On the other hand, the dependencies on used interfaces – so-called cross dependencies – are generally shallow dependency relationships: the using interface does not need to know much about the used interface (currently just the name of the implementing class, and whether the interface is a callback interface or not). Thus almost all changes in the used interface do not change the bindings for the using interface: the public information used by other bindings is minimal. There is one exception, namely the IDL extended attribute validatorTo avoid bugs caused by typos in extended attributes in IDL files, the extended attribute validator was introduced to the Blink build flow to check if all the extended attributes used in IDL files are implemented in the code generator. If you use an extended attribute not implemented in code generators, the extended attribute validator fails, and the Blink build fails. A list of IDL attributes implemented in code generators is described in IDLExtendedAttributes.txt. If you want to add a new IDL attribute, you need to
Note that the validator checks for known extended attributes and their arguments (if any), but does not enforce correct use of the the attributes. A warning will not be issued if, for example,
[Clamp] is specified on an interface.TestsReference tests (run-bindings-tests)third_party/blink/tools/run_bindings_tests.py tests the code generator, including its treatment of extended attributes. Specifically, run_bindings_tests.py compiles the IDL files in bindings/tests/idls, and then compares the results against reference files in bindings/tests/results. For example, run_bindings_tests.py reads test_object.idl, and then compares the generated results against v8_test_object.h and v8_test_object.cc, reporting any differences. If you change the behavior of the code generator or add a new extended attribute, please add suitable test cases, preferably reusing existing IDL files (this is to minimize size of diffs when making changes to overall generated bindings). You can reset the run-bindings-tests results using the --reset-results option: third_party/blink/tools/run_bindings_tests.py --reset-results run_bindings_tests.py is run in a presubmit script for any changes to Source/bindings: this requires you to update test results when you change the behavior of the code generator, and thus if test results get out of date, the presubmit test will fail: you won‘t be able to upload your patch via git-cl, and the CQ will refuse to process the patch. The objective of run-bindings-tests is to show you and reviewers how the code generation is changed by your patch. If you change the behavior of code generators, you need to update the results of run-bindings-tests. Despite these checks, sometimes the test results can get out of date; this is primarily due to dcommitting or changes in real IDL files (not in Source/bindings) that are used in test cases. If the results are out of date prior to your CL, please rebaseline them separately, before committing your CL, as otherwise it will be difficult to distinguish which changes are due to your CL and which are due to rebaselining due to older CLs. Note that using real interfaces in test IDL files means changes to real IDL files can break run-bindings-tests (e.g., Blink r174804/CL 292503006: Oilpan: add [WillBeGarbageCollected] for Node., since Node is inherited by test files). This is ok (we‘re not going to run run_bindings_tests.py on every IDL edit, and it‘s easy to fix), but something to be aware of. It is also possible for run_bindings_tests.py to break for other reasons, since it use the developer‘s local tree: it thus may pass locally but fail remotely, or conversely. For example, renaming Python files can result in outdated bytecode (.pyc files) being used locally and succeeding, even if run_bindings_tests.py is incompatible with current Python source (.py), as discussed and fixed in CL 301743008.
Behavior testsTo test behavior, use web tests, most simply actual interfaces that use the behavior you‘re implementing. If adding new behavior, it‘s preferable to make code generator changes and the first actual use case in the same CL, so that it is properly tested, and the changes appear in the context of an actual change. If this makes the CL too large, these can be split into a CG-only CL and an actual use CL, committed in sequence, but unused features should not be added to the CG.
For general behavior, like type conversions, there are some internal tests, like bindings/webidl-type-mapping.html, which uses testing/type_conversions.idl. There are also some other IDL files in testing, like testing/internals.idl.
Where is the bindings code generated?By reading this document you can learn how extended attributes work. However, the best practice to understand extended attributes is to try to use some and watch what kind of bindings code is generated. If you change an IDL file and rebuild (e.g., with ninja or Make), the bindings for that IDL file (and possibly others, if there are dependents) will be rebuilt. If the bindings have changed (in ninja), or even if they haven‘t (in other build systems), it will also recompile the bindings code. Regenerating bindings for a single IDL file is very fast, but regenerating all of them takes several minutes of CPU time. In case of xxx.idl in the Release build, the bindings code is generated in the following files ("Release" becomes "Debug" in the Debug build). out/Release/gen/third_party/blink/renderer/bindings/{core,modules}/v8_xxx.{h,cc} Limitations and improvementsA few parts of the Web IDL spec are not implemented; features are implemented on an as-needed basis. See component:Blink>Bindings for open bugs; please feel free to file bugs or contact bindings developers (members of blink-reviews-bindings, or bindings/OWNERS) if you have any questions, problems, or requests. Bindings generation can be controlled in many ways, generally by adding an extended attribute to specify the behavior, sometimes by special-casing a specific type, interface, or member. If the existing extended attributes are not sufficient (or buggy), please file a bug and contact bindings developers! Some commonly encountered limitations and suitable workarounds are listed below. Generally limitations can be worked around by using custom bindings, but these should be avoided if possible. If you need to work around a limitation, please put a
TODO with the bug number (as demonstrated below) in the IDL so that we can remove the hack when the feature is implemented.Syntax error causes infinite loopSome syntax errors cause the IDL parser to enter an infinite loop (Bug 363830). Until this is fixed, if the compiler hangs, please terminate the compiler and check your syntax.
Type checkingThe bindings do not do full type checking (Bug 321518). They do some type checking, but not all. Notably nullability is not strictly enforced. See Bindings developmentMailing ListIf working on bindings, you likely wish to join the blink-reviews-bindings mailing list.See also
|
Web IDL interfaces
To implement a new Web IDL interface in Blink:
IDL
See Blink IDL: Style for style guide.
IDL files contain two types of data:
Note that if Blink behavior differs from the spec, the Blink IDL file should reflect Blink behavior. This makes interface differences visible, rather than hiding them in the C++ implementation or bindings generator.
Also as a rule, nop data should not be included: if Blink (bindings generator) ignores an IDL keyword or extended attribute, do not include it, as it suggests a difference in behavior when there is none. If this results in a difference from the spec, this is good, as it makes the difference in behavior visible.
Nulls and non-finite numbersTwo points to be careful of, and which are often incorrect in specs, particularly older specs, are nullability and non-finite values (infinities and NaN). These are both to ensure correct type checking. If these are incorrect in the spec – for example, a prose specifying behavior on non-finite values, but the IDL not reflecting this – please file a spec bug upstream, and link to it in the IDL file.
If null values are valid (for attributes, argument types, or method return values), the type MUST be marked with a ? to indicate nullable, as in
attribute Foo? foo;
Note that for arguments (but not attributes or method return values), optional is preferred to nullable (see Re: removeEventListener with only one passed parameter...).
Similarly, IEEE floating point allows non-finite numbers (infinities and NaN); if these are valid, the floating point type –
float or double – MUST be marked as unrestricted as in unrestricted float or unrestricted double – the bare float or double means finite floating point.Union typesMany older specs use overloading when a union type argument would be clearer. Please match spec, but file a spec bug for these and link to it. For example:
// FIXME: should be void bar((long or Foo) foo); https://www.w3.org/Bugs/Public/show_bug.cgi?id=123 void bar(long foo); void bar(Foo foo); Also, beware that you can‘t have multiple nullable arguments in the distinguishing position in an overload, as these are not distinguishing (what does
null resolve to?). This is best resolved by using a union type if possible; otherwise make sure to mark only one overload as having a nullable argument in that position.Don‘t do this:
void zork(Foo? x); void zork(Bar? x); // What does zork(null) resolve to? Instead do this:
void zork(Foo? x); void zork(Bar x); ...but preferably this:
void zork((Foo or Bar)? x); Extended attributesYou will often need to add Blink-specific extended attributes to specify implementation details.
Please comment extended attributes – why do you need special behavior?
BindingsSee Web IDL in Blink.
C++Bindings code assumes that a C++ class exists, with methods for each attribute or operation (with some exceptions). Attributes are implemented as properties, meaning that while in the JavaScript interface these are read and written as attributes, in C++ these are read and written by getter and setter methods.
For cases where an IDL attribute reflects a content attribute, you do not need to write boilerplate methods to call
getAttribute() and setAttribute(). Instead, use the [Reflect] extended attribute, and these calls will automatically be generated inline in the bindings code, with optimizations in some cases. However, if you wish to access these attributes from C++ code (say in another class), not just from JavaScript, you will need to write a getter and/or a setter, as necessary.NamesThe class and methods have default names, which can be overridden by the
[ImplementedAs] extended attribute; this is strongly discouraged, and method names should align with the spec unless there is very good reason for them to differ (this is sometimes necessary when there is a conflict, say when inheriting another interface).Given an IDL file Foo.idl:
interface Foo { attribute long a; attribute DOMString cssText; void f(); void f(long arg); void g(optional long arg); }; ...a minimal header file Foo.h illustrating this is:
class Foo { public: int a(); void setA(int); String cssText(); void setCSSText(const String&); void f(); void f(int); void g(); void g(int); // Alternatively, can use default arguments: // void f(int arg=0); };
Type information ("ScriptWrappable")Blink objects that are visible in JavaScript need type information, fundamentally because JavaScript is dynamically typed (so values have type), concretely because the bindings code uses type introspection for dynamic dispatch (function resolution of bindings functions): given a C++ object (representing the implementation of a JavaScript object), accessing it from V8 requires calling the correct C++ binding methods, which requires knowing its JavaScript type (i.e., the IDL interface type).
Blink does not use C++ run-time type information (RTTI), and thus the type information must be stored separately.
There are various ways this is done, most simply (for Blink developers) by the C++ class inheriting
ScriptWrappable and placing DEFINE_WRAPPERTYPEINFO in the class declaration. Stylistically ScriptWrappable should be the last class, or at least after more interesting classes, and should be directly inherited by the class (not indirectly from a more distant ancestor).Explicitly:
Foo.h:
#ifndef Foo_h #define Foo_h #include "bindings/v8/ScriptWrappable.h" namespace WebCore { class Foo FINAL : /* maybe others */ public ScriptWrappable { DEFINE_WRAPPERTYPEINFO();
// ... }; } // namespace WebCore #endif Foo_h In case of C++ inheritance, it‘s preferable to avoid inheriting ScriptWrappable indirectly, most simply because this creates overhead on a redundant write. In many cases this can be avoided by having an abstract base class that both concrete classes inherit. Stylistically, FIXME
However, in some cases – notably if both a base class and a derived class implement JS interface types (say, if there is IDL inheritance and the C++ inheritance is the same) – you will need to call
ScriptWrappable::init both in the base class and the derived class.Thus, to avoid this:
Foo.h:
class Foo FINAL : public Bar, public ScriptWrappable { /* ... */ };Bar.h:
class Bar : public ScriptWrappable { /* ... */ }; ...instead use an abstract base class, and have both concrete classes inherit
ScriptWrappable directly:Foo.h:
class Foo FINAL : public FooBarBase, public ScriptWrappable { /* ... */ };Bar.h:
class Bar FINAL : public FooBarBase, public ScriptWrappable { /* ... */ };FooBarBase.h:
class FooBarBase { /* ... */ }; History (ScriptWrappable)
Garbage CollectionBuildYou need to list the
.idl file and .h/.cpp files in the correct GN variable so that they will be built (bindings generated, Blink code compiled.) IDL files to be processed are listed in .gni (GN Include) files. For core files, this is core_idl_files.gni.There are 3 dichotomies in these
.idl files, which affect where you list them in the build:
For core interfaces, the IDL files are listed in the
core_idl_files variable or in the core_dependency_idl_files variable, if the IDL file is a partial interface or the target (right side of) an implements statement. This distinction is because partial interfaces and implemented interfaces do not have their own bindings generated, so these IDL files are not directly compiled.Testing files are listed in the
core_testing_idl_files variable instead; there are currently no core testing dependency files.The C++ files should be listed in the
core_files variable or an appropriate core_*_files variable, depending on directory, or core_testing_files if a testing interface.Modules files are analogous, and placed in modules_idl_files.gni. There are currently no modules testing interface files, but there are modules testing dependency files, which are listed in
modules_dependency_idl_files and modules_testing_files .TestsMake sure to test:
SubtypingThere are three mechanisms for subtyping in IDL:
The corresponding C++ implementations are as follows, here illustrated for
attribute T foo;
IDL files SHOULD agree with spec, and almost always MUST do so. It is not ok to change the kind of subtyping or move members between interfaces, and violations SHOULD or MUST be fixed:
Technical detailsWhile members of an interface definition, members of implemented interface, and members of partial interfaces are identical for JavaScript, partial interface members – and members of certain implemented interfaces, namely those with the
[TreatAsPartial] extended attribute – are treated differently internally in Blink (see below).Inheritance and implements are both interface inheritance. JavaScript has single inheritance, and IDL inheritance corresponds to JavaScript inheritance, while IDL
implements provides multiple inheritance in IDL, which does not correspond to inheritance in JavaScript.In both cases, by spec, members of the inherited or implemented interface must be implemented on the JavaScript object implementing the interface. Concretely, members of inherited interfaces are implemented as properties on the prototype object of the parent interface, while members of implemented interfaces are implemented as properties of the implementing interface.
In C++, members of an interface definition and members of implemented interfaces are implemented on the C++ object (referred to as the parameter or variable
impl ) implementing the JavaScript object. Specifically this is done in the Blink class corresponding to the IDL interface or a base class – the C++ hierarchy is invisible to both JavaScript and the bindings.Implementation-wise, inheritance and implements differ in two ways:
If (IDL) interface A inherits from interface B, then usually (C++) class A inherits from class B, meaning that:
interface A : B { /* ... */ }; class A : B { /* ... */ }; class A : C { /* ... */ }; class C : B { /* ... */ }; However, the bindings are agnostic about this, and simply set the prototype in the wrapper object to be the inherited interface (concretely, sets the parentClass attribute in the WrapperTypeInfo of the class‘s bindings). Dispatch is thus done in JavaScript.
"A implements B;"
should mean that members declared in (IDL) interface B
are members of (C++) classes implementing A.
impl.
Partial interfaces formally are type extension (external type extension, since specified in a separate place from the original definition), and in principle are simply part of the interface, just defined separately, as a convenience for spec authors. However in practice, members of partial interfaces are not assumed to be implemented on the C++ object (
impl ), and are not defined in the Blink class implementing the interface. Instead, they are implemented as static members of a separate class, which take impl as their first argument. This is done because in practice, partial interfaces are type extensions, which often only used in subtypes or are deactivated (via conditionals or as runtime enabled features), and we do not want to bloat the main Blink class to include these.Further, in some cases we must use type extension (static methods) for implemented interfaces as well. This is due to componentization in Blink (see Browser Components), currently
core versus modules. Code in core cannot inherit from code in modules, and thus if an interface in core implements an interface in modules, this must be implemented via type extension (static methods in modules ). This is an exceptional case, and indicates that Blink‘s internal layering (componentization) disagrees with the layering implied by the IDL specs, and formally should be resolved by moving the relevant interface from modules to core. This is not always possible or desirable (for internal implementation reasons), and thus static methods can be specified via the [TreatAsPartial] extended attribute on the implemented interface.Inheritance and code reuseIDL has single inheritance, which maps directly to JavaScript inheritance (prototype chain). C++ has multiple inheritance, and the two hierarchies need not be related.
FIXME: There are issues if a C++ class inherits from another C++ class that implements an IDL interface, as .
downcasting
IDL has 3 mechanisms for combining interfaces:
Sharing code with a legacy interface (unprefixing)...
Changing inheritance → implementsConverting a parent to the target of an implements
See alsoOther Blink interfaces, not standard Web IDL interfaces:
External linksFor reference, documentation by other projects.
|