Using IDL union types in Blink is a bit tricky. Here are some tips to use union types correctly.
For each union type, the code generator creates a C++ class which is used like an “impl” class of a normal interface type. The name of a generated class is a type name of the union type. For example, the code generator will create StringOrFloat
class for (DOMString or float)
.
The code generator puts generated classes into separate files. You need to include generated header files when you use union types in core/modules.
The file name for a generated class is basically the same as its class name, but we use some aliases to avoid too-long file names (See http://crbug.com/611437 why we need to avoid long file names). Currently we use following alias(es).
CanvasRenderingContext2DOrWebGLRenderingContextOrWebGL2RenderingContextOrImageBitmapRenderingContext -> RenderingContext
The paths for generated classes depend on the places union types are used. If a union type is used only by IDL files under modules/, the include path is bindings/modules/v8/FooOrBar.h
. Otherwise, the include path is bindings/core/v8/FooOrBar.h
. For example, given following definitions:
// core/fileapi/FileReader.idl readonly attribute (DOMString or ArrayBuffer)? result; // dom/CommonDefinitions.idl typedef (ArrayBuffer or ArrayBufferView) BufferSource; // modules/encoding/TextDecoder.idl DOMString decode(optional BufferSource input, optional TextDecodeOptions options); // modules/fetch/Request.idl typedef (Request or USVString) RequestInfo;
The include paths will be:
Note that ArrayBufferOrArrayBufferView
is located under core/ even it is used by Request.idl
which is located under modules/.
Special NOTE: If you are going to use a union type under core/ and the union type is currently used only under modules/, you will need to update the include path for the union type under modules/.
TODO(bashi): Mitigate the pain of updating GN/GYP files.
Due to the requirements of GN/GYP, we need to put generated file names in gni/gypi files. Please update bindings/core/v8/generated.{gni,gypi}
and/or bindings/modules/v8/generated.{gni,gypi}
accordingly.