diff options
Diffstat (limited to 'utils/ipc/mojo/public/tools/bindings/README.md')
| -rw-r--r-- | utils/ipc/mojo/public/tools/bindings/README.md | 187 |
1 files changed, 126 insertions, 61 deletions
diff --git a/utils/ipc/mojo/public/tools/bindings/README.md b/utils/ipc/mojo/public/tools/bindings/README.md index 1a3d5c58..43882450 100644 --- a/utils/ipc/mojo/public/tools/bindings/README.md +++ b/utils/ipc/mojo/public/tools/bindings/README.md @@ -113,8 +113,8 @@ for message parameters. Every Mojom file may optionally specify a single **module** to which it belongs. -This is used strictly for aggregaging all defined symbols therein within a -common Mojom namespace. The specific impact this has on generated binidngs code +This is used strictly for aggregating all defined symbols therein within a +common Mojom namespace. The specific impact this has on generated bindings code varies for each target language. For example, if the following Mojom is used to generate bindings: @@ -132,7 +132,7 @@ Generated C++ bindings will define a class interface `MoneyGenerator` in the bindings at this time are unaffected by module declarations. **NOTE:** By convention in the Chromium codebase, **all** Mojom files should -declare a module name with at least (and preferrably exactly) one top-level name +declare a module name with at least (and preferably exactly) one top-level name as well as an inner `mojom` module suffix. *e.g.*, `chrome.mojom`, `business.mojom`, *etc.* @@ -271,7 +271,7 @@ code, see ### Unions Mojom supports tagged unions using the **union** keyword. A union is a -collection of fields which may taken the value of any single one of those fields +collection of fields which may take the value of any single one of those fields at a time. Thus they provide a way to represent a variant value type while minimizing storage requirements. @@ -320,7 +320,7 @@ enum definition. By default, values are based at zero and increment by 1 sequentially. The effect of nested definitions on generated bindings varies depending on the -target language. See [documentation for individual target languages](#Generated-Code-For-Target-Languages) +target language. See [documentation for individual target languages](#Generated-Code-For-Target-Languages). ### Constants @@ -346,7 +346,7 @@ struct Employee { ``` The effect of nested definitions on generated bindings varies depending on the -target language. See [documentation for individual target languages](#Generated-Code-For-Target-Languages) +target language. See [documentation for individual target languages](#Generated-Code-For-Target-Languages). ### Interfaces @@ -379,58 +379,82 @@ Mojom definitions may have their meaning altered by **attributes**, specified with a syntax similar to Java or C# attributes. There are a handle of interesting attributes supported today. -**`[Sync]`** -: The `Sync` attribute may be specified for any interface method which expects - a response. This makes it so that callers of the method can wait - synchronously for a response. See - [Synchronous Calls](/mojo/public/cpp/bindings/README.md#Synchronous-Calls) - in the C++ bindings documentation. Note that sync methods are only actually - synchronous when called from C++. - -**`[Extensible]`** -: The `Extensible` attribute may be specified for any enum definition. This - essentially disables builtin range validation when receiving values of the - enum type in a message, allowing older bindings to tolerate unrecognized - values from newer versions of the enum. - -**`[Native]`** -: The `Native` attribute may be specified for an empty struct declaration to - provide a nominal bridge between Mojo IPC and legacy `IPC::ParamTraits` or - `IPC_STRUCT_TRAITS*` macros. - See - [Repurposing Legacy IPC Traits](/docs/mojo_ipc_conversion.md#repurposing-and-invocations) - for more details. Note support for this attribute is strictly limited to C++ - bindings generation. - -**`[MinVersion=N]`** -: The `MinVersion` attribute is used to specify the version at which a given - field, enum value, interface method, or method parameter was introduced. - See [Versioning](#Versioning) for more details. - -**`[Stable]`** -: The `Stable` attribute specifies that a given mojom type or interface - definition can be considered stable over time, meaning it is safe to use for - things like persistent storage or communication between independent - version-skewed binaries. Stable definitions may only depend on builtin mojom - types or other stable definitions, and changes to such definitions MUST - preserve backward-compatibility through appropriate use of versioning. - Backward-compatibility of changes is enforced in the Chromium tree using a - strict presubmit check. See [Versioning](#Versioning) for more details on - backward-compatibility constraints. - -**`[EnableIf=value]`** -: The `EnableIf` attribute is used to conditionally enable definitions when - the mojom is parsed. If the `mojom` target in the GN file does not include - the matching `value` in the list of `enabled_features`, the definition - will be disabled. This is useful for mojom definitions that only make - sense on one platform. Note that the `EnableIf` attribute can only be set - once per definition. +* **`[Sync]`**: + The `Sync` attribute may be specified for any interface method which expects a + response. This makes it so that callers of the method can wait synchronously + for a response. See [Synchronous + Calls](/mojo/public/cpp/bindings/README.md#Synchronous-Calls) in the C++ + bindings documentation. Note that sync methods are only actually synchronous + when called from C++. + +* **`[NoInterrupt]`**: + When a thread is waiting for a reply to a `Sync` message, it's possible to be + woken up to dispatch other unrelated incoming `Sync` messages. This measure + helps to avoid deadlocks. If a `Sync` message is also marked as `NoInterrupt` + however, this behavior is disabled: instead the calling thread will only wake + up for the precise message being waited upon. This attribute must be used with + extreme caution, because it can lead to deadlocks otherwise. + +* **`[Default]`**: + The `Default` attribute may be used to specify an enumerator value that + will be used if an `Extensible` enumeration does not deserialize to a known + value on the receiver side, i.e. the sender is using a newer version of the + enum. This allows unknown values to be mapped to a well-defined value that can + be appropriately handled. + +* **`[Extensible]`**: + The `Extensible` attribute may be specified for any enum definition. This + essentially disables builtin range validation when receiving values of the + enum type in a message, allowing older bindings to tolerate unrecognized + values from newer versions of the enum. + + Note: in the future, an `Extensible` enumeration will require that a `Default` + enumerator value also be specified. + +* **`[Native]`**: + The `Native` attribute may be specified for an empty struct declaration to + provide a nominal bridge between Mojo IPC and legacy `IPC::ParamTraits` or + `IPC_STRUCT_TRAITS*` macros. See [Repurposing Legacy IPC + Traits](/docs/mojo_ipc_conversion.md#repurposing-and-invocations) for more + details. Note support for this attribute is strictly limited to C++ bindings + generation. + +* **`[MinVersion=N]`**: + The `MinVersion` attribute is used to specify the version at which a given + field, enum value, interface method, or method parameter was introduced. + See [Versioning](#Versioning) for more details. + +* **`[Stable]`**: + The `Stable` attribute specifies that a given mojom type or interface + definition can be considered stable over time, meaning it is safe to use for + things like persistent storage or communication between independent + version-skewed binaries. Stable definitions may only depend on builtin mojom + types or other stable definitions, and changes to such definitions MUST + preserve backward-compatibility through appropriate use of versioning. + Backward-compatibility of changes is enforced in the Chromium tree using a + strict presubmit check. See [Versioning](#Versioning) for more details on + backward-compatibility constraints. + +* **`[Uuid=<UUID>]`**: + Specifies a UUID to be associated with a given interface. The UUID is intended + to remain stable across all changes to the interface definition, including + name changes. The value given for this attribute should be a standard UUID + string representation as specified by RFC 4122. New UUIDs can be generated + with common tools such as `uuidgen`. + +* **`[EnableIf=value]`**: + The `EnableIf` attribute is used to conditionally enable definitions when the + mojom is parsed. If the `mojom` target in the GN file does not include the + matching `value` in the list of `enabled_features`, the definition will be + disabled. This is useful for mojom definitions that only make sense on one + platform. Note that the `EnableIf` attribute can only be set once per + definition. ## Generated Code For Target Languages When the bindings generator successfully processes an input Mojom file, it emits corresponding code for each supported target language. For more details on how -Mojom concepts translate to a given target langauge, please refer to the +Mojom concepts translate to a given target language, please refer to the bindings API documentation for that language: * [C++ Bindings](/mojo/public/cpp/bindings/README.md) @@ -441,7 +465,7 @@ bindings API documentation for that language: Regardless of target language, all interface messages are validated during deserialization before they are dispatched to a receiving implementation of the -interface. This helps to ensure consitent validation across interfaces without +interface. This helps to ensure consistent validation across interfaces without leaving the burden to developers and security reviewers every time a new message is added. @@ -555,25 +579,37 @@ struct Employee { }; ``` -and you would like to add a birthday field. You can do: +and you would like to add birthday and nickname fields. You can add them as +optional types with a `MinVersion` like so: ``` cpp struct Employee { uint64 employee_id; string name; [MinVersion=1] Date? birthday; + [MinVersion=1] string? nickname; }; ``` +*** note +**NOTE:** Mojo object or handle types added with a `MinVersion` **MUST** be +optional (nullable). See [Primitive Types](#Primitive-Types) for details on +nullable values. +*** + By default, fields belong to version 0. New fields must be appended to the struct definition (*i.e*., existing fields must not change **ordinal value**) with the `MinVersion` attribute set to a number greater than any previous existing versions. +The value of `MinVersion` is unrelated to ordinals. The choice of a particular +version number is arbitrary. All its usage means is that a field isn't present +before the numbered version. + *** note **NOTE:** do not change existing fields in versioned structs, as this is not backwards-compatible. Instead, rename the old field to make its -deprecation clear and add a new field with the new version number. +deprecation clear and add a new field with a new `MinVersion` number. *** **Ordinal value** refers to the relative positional layout of a struct's fields @@ -602,14 +638,10 @@ struct Employee { uint64 employee_id@0; [MinVersion=1] Date? birthday@2; string name@1; + [MinVersion=1] string? nickname@3; }; ``` -*** note -**NOTE:** Newly added fields of Mojo object or handle types MUST be nullable. -See [Primitive Types](#Primitive-Types). -*** - ### Versioned Interfaces There are two dimensions on which an interface can be extended @@ -706,6 +738,39 @@ values and will need to deal with them gracefully. See [C++ Versioning Considerations](/mojo/public/cpp/bindings/README.md#Versioning-Considerations) for details. +### Renaming versioned structs +It's possible to rename versioned structs by using the `[RenamedFrom]` attribute. +RenamedFrom + +``` cpp +module asdf.mojom; + +// Old version: +[Stable] +struct OldStruct { +}; + +// New version: +[Stable, RenamedFrom="asdf.mojom.OldStruct"] +struct NewStruct { +}; +``` + +## Component targets + +If there are multiple components depending on the same mojom target within one binary, +the target will need to be defined as `mojom_component` instead of `mojom`. +Since `mojom` targets are generated `source_set` targets and `mojom_component` targets +are generated `component` targets, you would use `mojom_component` in the same cases +where you would use `component` for non-mojom files. +*** note +**NOTE**: by default, components for both blink and non-blink bindings are generated. +Use the `disable_variants` target parameter to generate only non-blink bindings. +You can also generate a `source_set` for one of the variants by defining +[export_*](https://source.chromium.org/chromium/chromium/src/+/main:mojo/public/tools/bindings/mojom.gni;drc=739b9fbce50310c1dd2b59c279cd90a9319cb6e8;l=318) +parameters for the `mojom_component` target. +*** + ## Grammar Reference Below is the (BNF-ish) context-free grammar of the Mojom language: |