From 8ad3e20c05e4e3aeffb95758f09b36626a71c18f Mon Sep 17 00:00:00 2001 From: Heejin Ahn Date: Thu, 10 Jun 2021 23:59:33 -0700 Subject: [PATCH 1/5] Replace 'event' with 'tag' in explainer It was suggested to change the term 'event' to 'tag' to reference the section name and the entries within the section. The suggested reasons were they can be used something other than events in future, and the term event can be confusing with other concepts on the web. Closes #159. --- proposals/exception-handling/Exceptions.md | 64 ++++++++++------------ 1 file changed, 28 insertions(+), 36 deletions(-) diff --git a/proposals/exception-handling/Exceptions.md b/proposals/exception-handling/Exceptions.md index 3714751c..f0901709 100644 --- a/proposals/exception-handling/Exceptions.md +++ b/proposals/exception-handling/Exceptions.md @@ -45,12 +45,12 @@ instruction. Thrown exceptions are handled as follows: 1. If the call stack is exhausted without any enclosing try blocks, the embedder defines how to handle the uncaught exception. -### Event handling +### Exception handling This proposal adds exception handling to WebAssembly. Part of this proposal is to define a new section to declare exceptions. However, rather than limiting this new section to just defining exceptions, it defines a more general format -that allows the declaration of other forms of events. +that allows the declaration of other forms of events in future. In general, an event handler allows one to process an event generated by a block of code. Events suspend the current execution and look for a corresponding event @@ -62,22 +62,21 @@ Exceptions are a special case of an event in that they never resume. Similarly, a `throw` instruction is the suspending event of an exception. The catch block associated with a try block defines how to handle the throw. -WebAssembly events (i.e. exceptions) are defined by a new `event` section of a -WebAssembly module. The event section is a list of declared events associated -with the module. +WebAssembly exceptions tags are defined in a new `tag` section of a WebAssembly +module. The tag section is a list of declared tags associated with the module. -Each event has an `attribute` and a `type`. Currently, the attribute can only -specify that the event is an exception. In the future, additional attribute +Each tag has an `attribute` and a `type`. Currently, the attribute can only +specify that the tag is for an exception. In the future, additional attribute values may be added when other events are added to WebAssembly. To allow for such a future extension possibility, we reserve a byte in the binary format of an exception definition, set to 0 to denote an exception -attribute, but for the moment we won't use the term event in the formal spec. +attribute. ### Exceptions An `exception` is an internal construct in WebAssembly. WebAssembly exceptions -are defined in the event and import sections of a module. +are defined in the tag and import sections of a module. The type of an exception is denoted by an index to a function signature defined in the `type` section. The parameters of the function signature define the list @@ -418,28 +417,21 @@ Each exception type has the fields: A single-byte unsigned integer indicating the kind of definition being imported or defined: -* `0` indicating a `Function` [import](Modules.md#imports) or -[definition](Modules.md#function-and-code-sections) -* `1` indicating a `Table` [import](Modules.md#imports) or -[definition](Modules.md#table-section) -* `2` indicating a `Memory` [import](Modules.md#imports) or -[definition](Modules.md#linear-memory-section) -* `3` indicating a `Global` [import](Modules.md#imports) or -[definition](Modules.md#global-section) -* `4` indicating an `Event` [import](#import-section) or -[definition](#event-section) +* `4` indicating a `Tag` +[import](https://github.com/WebAssembly/design/blob/main/BinaryEncoding.md#import-section) or +[definition](#tag-section) ### Module structure #### High-level structure -A new `event` section is introduced and is named `event`. If included, it must -appear immediately after the memory section. +A new `tag` section is introduced. If included, it must appear immediately after +the memory section. -##### Exception section +##### Tag section -The `event` section is the named section 'exception'. For ease of validation, -this section comes after the [memory +The `tag` section is the named section 'tag'. For ease of validation, this +section comes after the [memory section](https://github.com/WebAssembly/design/blob/master/BinaryEncoding.md#memory-section) and before the [global section](https://github.com/WebAssembly/design/blob/master/BinaryEncoding.md#global-section). @@ -452,7 +444,7 @@ So the list of all sections will be: | Function | `3` | Function declarations | | Table | `4` | Indirect function table and other tables | | Memory | `5` | Memory attributes | -| Event | `13` | Event declarations | +| Tag | `13` | Tag declarations | | Global | `6` | Global declarations | | Export | `7` | Exports | | Start | `8` | Start function declaration | @@ -460,34 +452,34 @@ So the list of all sections will be: | Code | `10` | Function bodies (code) | | Data | `11` | Data segments | -The event section declares a list of event types as follows: +The tag section declares a list of tag types as follows: | Field | Type | Description | |-------|------|-------------| -| count | `varuint32` | count of the number of event to follow | -| type | `event_type*` | The definitions of the event types | +| count | `varuint32` | count of the number of tags to follow | +| type | `tag_type*` | The definitions of the tag types | ##### Import section The import section is extended to include exception definitions by extending an `import_entry` as follows: -If the `kind` is `Event`: +If the `kind` is `Tag`: | Field | Type | Description | |-------|------|-------------| -| `type` | `event_type` | the event being imported | +| `type` | `tag_type` | the tag being imported | ##### Export section The export section is extended to reference exception types by extending an `export_entry` as follows: -If the `kind` is `Event`: +If the `kind` is `Tag`: | Field | Type | Description | |-------|------|-------------| -| `index` | `varuint32` | the index into the corresponding event index space | +| `index` | `varuint32` | the index into the corresponding exception index space | ##### Name section @@ -498,12 +490,12 @@ follows: | --------- | ---- | ----------- | | [Function](#function-names) | `1` | Assigns names to functions | | [Local](#local-names) | `2` | Assigns names to locals in functions | -| [Event](#event-names) | `3` | Assigns names to event types | +| [Tag](#tag-names) | `3` | Assigns names to tag types | -###### Event names +###### Tag names -The event names subsection is a `name_map` which assigns names to a subset of -the exception indices (Used for both imports and module-defined). +The tag names subsection is a `name_map` which assigns names to a subset of +the tag indices (Used for both imports and module-defined). ### Control flow operators From ff98af9d529e38792f5947a0668f0181e1588c2d Mon Sep 17 00:00:00 2001 From: Heejin Ahn Date: Tue, 15 Jun 2021 00:20:33 -0700 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Thomas Lively <7121787+tlively@users.noreply.github.com> --- proposals/exception-handling/Exceptions.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/proposals/exception-handling/Exceptions.md b/proposals/exception-handling/Exceptions.md index f0901709..75e3c1b8 100644 --- a/proposals/exception-handling/Exceptions.md +++ b/proposals/exception-handling/Exceptions.md @@ -50,7 +50,7 @@ instruction. Thrown exceptions are handled as follows: This proposal adds exception handling to WebAssembly. Part of this proposal is to define a new section to declare exceptions. However, rather than limiting this new section to just defining exceptions, it defines a more general format -that allows the declaration of other forms of events in future. +that allows the declaration of other forms of typed tags in future. In general, an event handler allows one to process an event generated by a block of code. Events suspend the current execution and look for a corresponding event @@ -67,7 +67,7 @@ module. The tag section is a list of declared tags associated with the module. Each tag has an `attribute` and a `type`. Currently, the attribute can only specify that the tag is for an exception. In the future, additional attribute -values may be added when other events are added to WebAssembly. +values may be added when other tags are added to WebAssembly. To allow for such a future extension possibility, we reserve a byte in the binary format of an exception definition, set to 0 to denote an exception @@ -430,8 +430,7 @@ the memory section. ##### Tag section -The `tag` section is the named section 'tag'. For ease of validation, this -section comes after the [memory +The `tag` section comes after the [memory section](https://github.com/WebAssembly/design/blob/master/BinaryEncoding.md#memory-section) and before the [global section](https://github.com/WebAssembly/design/blob/master/BinaryEncoding.md#global-section). @@ -479,7 +478,7 @@ If the `kind` is `Tag`: | Field | Type | Description | |-------|------|-------------| -| `index` | `varuint32` | the index into the corresponding exception index space | +| `index` | `varuint32` | the index into the corresponding tag index space | ##### Name section From 681306e4596413848fe82ed6c9df351dc10b95c6 Mon Sep 17 00:00:00 2001 From: Heejin Ahn Date: Tue, 15 Jun 2021 00:53:29 -0700 Subject: [PATCH 3/5] Fixes --- proposals/exception-handling/Exceptions.md | 100 +++++++++------------ 1 file changed, 44 insertions(+), 56 deletions(-) diff --git a/proposals/exception-handling/Exceptions.md b/proposals/exception-handling/Exceptions.md index 75e3c1b8..d9d9c9c7 100644 --- a/proposals/exception-handling/Exceptions.md +++ b/proposals/exception-handling/Exceptions.md @@ -50,24 +50,14 @@ instruction. Thrown exceptions are handled as follows: This proposal adds exception handling to WebAssembly. Part of this proposal is to define a new section to declare exceptions. However, rather than limiting this new section to just defining exceptions, it defines a more general format -that allows the declaration of other forms of typed tags in future. +`tag` that allows the declaration of other forms of typed tags in future. -In general, an event handler allows one to process an event generated by a block -of code. Events suspend the current execution and look for a corresponding event -handler. If found, the corresponding event handler is run. Some event handlers -may send values back to the suspended instruction, allowing the originating code -to resume. - -Exceptions are a special case of an event in that they never resume. Similarly, -a `throw` instruction is the suspending event of an exception. The catch block -associated with a try block defines how to handle the throw. - -WebAssembly exceptions tags are defined in a new `tag` section of a WebAssembly -module. The tag section is a list of declared tags associated with the module. +WebAssembly tags are defined in a new `tag` section of a WebAssembly module. The +tag section is a list of declared tags associated with the module. Each tag has an `attribute` and a `type`. Currently, the attribute can only specify that the tag is for an exception. In the future, additional attribute -values may be added when other tags are added to WebAssembly. +values may be added when other kinds of tags are added to WebAssembly. To allow for such a future extension possibility, we reserve a byte in the binary format of an exception definition, set to 0 to denote an exception @@ -75,19 +65,20 @@ attribute. ### Exceptions -An `exception` is an internal construct in WebAssembly. WebAssembly exceptions -are defined in the tag and import sections of a module. +An `exception tag` is a value to distinguish different exceptions, while an +`exception tag index` is a numeric name to refer to an (imported or defined) +exception tag within a module (see [tag index space](#tag-index-space) for +details). Exception tags are defined in the tag and import sections of a module. -The type of an exception is denoted by an index to a function signature defined -in the `type` section. The parameters of the function signature define the list -of values associated with the exception. The result type must be empty. +An `exception` is an internal construct in WebAssembly that represents a runtime +object that can be thrown. A WebAssembly exception is defined by an exception +tag and its runtime arguments. -An `exception tag` is a value to distinguish different exceptions, while an -`exception index` is a numeric name to refer to an (imported or defined) -exception tag within a module (see [exception index -space](#exception-index-space) for details). +The type of an exception tag is denoted by an index to a function signature +defined in the `type` section. The parameters of the function signature define +the list of values associated with the tag. The result type must be empty. -Exception indices are used by: +Exception tag indices are used by: 1. The `throw` instruction which creates a WebAssembly exception with the corresponding exception tag, and then throws it. @@ -137,9 +128,9 @@ are considered _tagged_ catch blocks. The last catching instruction of a try-catch block can be the `catch_all` instruction. If it begins with the `catch_all` instruction, it defines the -_default_ catch block. The default catch block has no exception type, and is -used to catch all exceptions not caught by any of the tagged catch blocks. The -term 'catch block' refers to both `catch` and `catch_all` blocks. +_default_ catch block. The default catch block has no tag index, and is used to +catch all exceptions not caught by any of the tagged catch blocks. The term +'catch block' refers to both `catch` and `catch_all` blocks. When the program runs `br` within `catch` or `catch_all` blocks, the rest of the catching blocks will not run and the program control will branch to the @@ -153,13 +144,13 @@ targets for branches (`br` and `br_if`) as well. ### Throwing an exception -The `throw` instruction takes an exception index as an immediate argument. That -index is used to identify the exception tag to use to create and throw the +The `throw` instruction takes an exception tag index as an immediate argument. +That index is used to identify the exception tag to use to create and throw the corresponding exception. The values on top of the stack must correspond to the type associated with the -exception. These values are popped off the stack and are used (along with the -corresponding exception tag) to create the corresponding exception. That +exception tag. These values are popped off the stack and are used (along with +the corresponding exception tag) to create the corresponding exception. That exception is then thrown. When an exception is thrown, the embedder searches for the nearest enclosing try @@ -186,7 +177,7 @@ after possible block parameters were popped. Then in case of a try-catch block, tagged catch blocks are tried in the order they appear in the catching try block, until one matches. If a matched tagged catch block is found, control is transferred to the body of the catch block, and -the data fields of the exception are pushed back onto the stack. +the arguments of the exception are pushed back onto the stack. Otherwise, control is transferred to the body of the `catch_all` block, if any. However, unlike tagged catch blocks, the constructor arguments are not copied @@ -357,9 +348,9 @@ document](https://github.com/WebAssembly/spec/blob/master/document/core/text/ins The following rules are added to *instructions*: ``` - try blocktype instruction* (catch instruction*)* (catch_all instruction*)? end | + try blocktype instruction* (catch tag_index instruction*)* (catch_all instruction*)? end | try blocktype instruction* delegate label | - throw (exception except_index) | + throw tag_index argument* | rethrow label | ``` @@ -367,28 +358,26 @@ Like the `block`, `loop`, and `if` instructions, the `try` instruction is *structured* control flow instruction, and can be labeled. This allows branch instructions to exit try blocks. -The `except_index` of the `throw` and `catch` instructions defines the exception -(and hence, exception tag) to create/extract from. See [exception index -space](#exception-index-space) for further clarification of exception tags. +The `tag_index` of the `throw` and `catch` instructions denotes the exception +tag to use when creating/extract from an exception. See [tag index +space](#tag-index-space) for further clarification of exception tags. ## Changes to Modules document This section describes change in the [Modules document](https://github.com/WebAssembly/design/blob/master/Modules.md). -### Exception index space +### Tag index space -The `exception index space` indexes all imported and internally-defined -exceptions, assigning monotonically-increasing indices based on the order -defined in the import and exception sections. Thus, the index space starts at -zero with imported exceptions, followed by internally-defined exceptions in the -[exception section](#exception-section). +The `tag index space` indexes all imported and internally-defined exception +tags, assigning monotonically-increasing indices based on the order defined in +the import and tag sections. Thus, the index space starts at zero with imported +tags, followed by internally-defined tags in the [tag section](#tag-section). -The exception index space defines the (module) static version of runtime -exception tags. For exception indices that are not imported/exported, the -corresponding exception tag is guaranteed to be unique over all loaded modules. -Exceptions that are imported or exported alias the respective exceptions defined -elsewhere, and use the same tag. +For tag indices that are not imported/exported, the corresponding exception tag +is guaranteed to be unique over all loaded modules. Exceptions that are imported +or exported alias the respective exceptions defined elsewhere, and use the same +tag. ## Changes to the binary model @@ -397,7 +386,7 @@ document](https://github.com/WebAssembly/design/blob/master/BinaryEncoding.md). #### Other Types -##### exception_type +##### tag_type We reserve a bit to denote the exception attribute: @@ -405,11 +394,11 @@ We reserve a bit to denote the exception attribute: |-----------|-------| | Exception | 0 | -Each exception type has the fields: +Each tag type has the fields: | Field | Type | Description | |-------|------|-------------| -| `attribute` | `varuint32` | The attribute of an exception. | +| `attribute` | `varuint32` | The attribute of a tag. | | `type` | `varuint32` | The type index for its corresponding type signature | ##### external_kind @@ -425,8 +414,7 @@ or defined: #### High-level structure -A new `tag` section is introduced. If included, it must appear immediately after -the memory section. +A new `tag` section is introduced. ##### Tag section @@ -460,7 +448,7 @@ The tag section declares a list of tag types as follows: ##### Import section -The import section is extended to include exception definitions by extending an +The import section is extended to include tag definitions by extending an `import_entry` as follows: If the `kind` is `Tag`: @@ -471,7 +459,7 @@ If the `kind` is `Tag`: ##### Export section -The export section is extended to reference exception types by extending an +The export section is extended to reference tag types by extending an `export_entry` as follows: If the `kind` is `Tag`: @@ -507,7 +495,7 @@ throws, and rethrows as follows: | `catch` | `0x07` | index : `varint32` | begins the catch block of the try block | | `catch_all` | `0x19` | | begins the catch_all block of the try block | | `delegate` | `0x18` | relative_depth : `varuint32` | begins the delegate block of the try block | -| `throw` | `0x08` | index : `varint32` | Creates an exception defined by the exception `index`and then throws it | +| `throw` | `0x08` | index : `varint32` | Creates an exception defined by the tag and then throws it | | `rethrow` | `0x09` | relative_depth : `varuint32` | Pops the `exnref` on top of the stack and throws it | The *sig* fields of `block`, `if`, and `try` operators are block signatures From f12debd8636bae3ec751af29054c3e2f6a3f6479 Mon Sep 17 00:00:00 2001 From: Heejin Ahn Date: Tue, 15 Jun 2021 13:45:43 -0700 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: Andreas Rossberg --- proposals/exception-handling/Exceptions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/exception-handling/Exceptions.md b/proposals/exception-handling/Exceptions.md index d9d9c9c7..31d1ca6f 100644 --- a/proposals/exception-handling/Exceptions.md +++ b/proposals/exception-handling/Exceptions.md @@ -53,7 +53,7 @@ this new section to just defining exceptions, it defines a more general format `tag` that allows the declaration of other forms of typed tags in future. WebAssembly tags are defined in a new `tag` section of a WebAssembly module. The -tag section is a list of declared tags associated with the module. +tag section is a list of declared tags that are created fresh each time the module is instantiated. Each tag has an `attribute` and a `type`. Currently, the attribute can only specify that the tag is for an exception. In the future, additional attribute @@ -68,15 +68,15 @@ attribute. An `exception tag` is a value to distinguish different exceptions, while an `exception tag index` is a numeric name to refer to an (imported or defined) exception tag within a module (see [tag index space](#tag-index-space) for -details). Exception tags are defined in the tag and import sections of a module. +details). Exception tags are declared in the tag and import sections of a module. An `exception` is an internal construct in WebAssembly that represents a runtime -object that can be thrown. A WebAssembly exception is defined by an exception +object that can be thrown. A WebAssembly exception consists of an exception tag and its runtime arguments. The type of an exception tag is denoted by an index to a function signature defined in the `type` section. The parameters of the function signature define -the list of values associated with the tag. The result type must be empty. +the list of argument values associated with the tag. The result type must be empty. Exception tag indices are used by: From 895df8fe6cde483a19cc1f47dd60fbf1cd14ae58 Mon Sep 17 00:00:00 2001 From: Heejin Ahn Date: Tue, 15 Jun 2021 13:46:51 -0700 Subject: [PATCH 5/5] 80 cols --- proposals/exception-handling/Exceptions.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/proposals/exception-handling/Exceptions.md b/proposals/exception-handling/Exceptions.md index 31d1ca6f..b299e8e3 100644 --- a/proposals/exception-handling/Exceptions.md +++ b/proposals/exception-handling/Exceptions.md @@ -53,7 +53,8 @@ this new section to just defining exceptions, it defines a more general format `tag` that allows the declaration of other forms of typed tags in future. WebAssembly tags are defined in a new `tag` section of a WebAssembly module. The -tag section is a list of declared tags that are created fresh each time the module is instantiated. +tag section is a list of declared tags that are created fresh each time the +module is instantiated. Each tag has an `attribute` and a `type`. Currently, the attribute can only specify that the tag is for an exception. In the future, additional attribute @@ -68,15 +69,17 @@ attribute. An `exception tag` is a value to distinguish different exceptions, while an `exception tag index` is a numeric name to refer to an (imported or defined) exception tag within a module (see [tag index space](#tag-index-space) for -details). Exception tags are declared in the tag and import sections of a module. +details). Exception tags are declared in the tag and import sections of a +module. An `exception` is an internal construct in WebAssembly that represents a runtime -object that can be thrown. A WebAssembly exception consists of an exception -tag and its runtime arguments. +object that can be thrown. A WebAssembly exception consists of an exception tag +and its runtime arguments. The type of an exception tag is denoted by an index to a function signature defined in the `type` section. The parameters of the function signature define -the list of argument values associated with the tag. The result type must be empty. +the list of argument values associated with the tag. The result type must be +empty. Exception tag indices are used by: