Recent changes to Unions

Unions modified by Will Pittenger

Will Pittenger — Sun, 16 Feb 2014 10:40:37 -0000

--- v11
+++ v12
@@ -14,6 +14,7 @@
 It's unknown if this type of union will default to by reference or by value.

 ~~~~
+:::text
 union MyUnion.ControllingType MyUnion
   public enum ControllingType
     left = 0
@@ -44,6 +45,7 @@
 In order to use a union, you need to declare an instance.  Syntactically, an instance can be treated as an instance of the controlling enum type.  You can compare it as needed.  You can also set it by setting the union's identifier to an instance of the enum type.  The following code users the union declared above.

 ~~~~
+:::text
 var MyUnion myUnionInstance = new MyUnion

 if myUnionInstance = left
@@ -65,6 +67,7 @@
 ------------------------------------------------------------
 Unions of this type have a built-in event.  Even though you can treat the union's instance as though it were the actual controlling enum member, the **[++](operators-inc)** and **[--](operators-dec)** get mapped to the event, not the controlling member.  (It doesn't make sense to increment or decrement the value of the controlling member anyway.)  The handler should be a command takes an instance of the controlling type (which has the old value of the controlling member) and can throw no exceptions.  If you need to know the new value of the controlling member, just reference the union instance's identifier.
 ~~~~
+:::text
 command myHandler var MyUnion.ControllingType oldValue
   ' Do something in response to the event.

Unions modified by Will Pittenger

Will Pittenger — Sun, 16 Feb 2014 09:06:31 -0000

--- v10
+++ v11
@@ -63,7 +63,7 @@

 Requesting notification of changes to the controlling member
 ------------------------------------------------------------
-Unions of this type have a built-in event.  Even though you can treat the union's instance as though it were the actual controlling enum member, the **[++](Operators-inc)** and **[--](Operators-dec)** get mapped to the event, not the controlling member.  (It doesn't make sense to increment or decrement the value of the controlling member anyway.)  The handler should be a command takes an instance of the controlling type (which has the old value of the controlling member) and can throw no exceptions.  If you need to know the new value of the controlling member, just reference the union instance's identifier.
+Unions of this type have a built-in event.  Even though you can treat the union's instance as though it were the actual controlling enum member, the **[++](operators-inc)** and **[--](operators-dec)** get mapped to the event, not the controlling member.  (It doesn't make sense to increment or decrement the value of the controlling member anyway.)  The handler should be a command takes an instance of the controlling type (which has the old value of the controlling member) and can throw no exceptions.  If you need to know the new value of the controlling member, just reference the union instance's identifier.
 ~~~~
 command myHandler var MyUnion.ControllingType oldValue
   ' Do something in response to the event.

Unions modified by Will Pittenger

Will Pittenger — Sun, 16 Feb 2014 08:48:12 -0000

--- v9
+++ v10
@@ -75,3 +75,7 @@
 Methods and properties inside a union
 -------------------------------------
 Unions can have methods and properties.  However, it's methods and properties must be members of the bitfields and structures inside the union, not directly inside the union itself.  (The union can however declare constructors, destructors, and creators.)  Those methods or properties can only be accessed when the controlling member allows access to those fields.
+
+Errors to be caught and things for an auto-complete tool to take into account
+-----------------------------------------------------------------------------
+All editors and compilers should warn about access of fields/methods/properties when the value of the controlling member isn't known or is wrong for the field/method/property being accessed.  By the same token, if the value of the controlling member has been established, an auto-complete tool should only list members of that part of the union.

Unions modified by Will Pittenger

Will Pittenger — Sun, 16 Feb 2014 08:23:26 -0000

--- v8
+++ v9
@@ -1,13 +1,10 @@
 [TOC]

 Overview
-========
+--------
 Unions are sometimes needed for communicating with C/C++ programs.  They're also how ASIL implements [Variants].  ASIL ensures the data is valid for the fields you're trying to access with a [control member](Appendices-Terms-Control member).  The control member is an instance of an primitive-based enum type.  (Structure-based enums can't be used with unions.)  The enum type must have explicit or implied values for each entry.  Unlike [Bitfields], unions don't have to be nested inside another type.

 All members of a union must be either a bitfield or a structure (except members of the union's members).  The immediate members of the union (the bitfields and structures) are all public to all code with access to the union.  These immediate members have no name or type associated with it.  Think of them as anonymous structures from C++.  Variants in ASIL are implemented as unions.  See the section on [Variants] for more information.
-
-Unions with an internal controlling member
-==========================================
 Declaring the union
 -------------------
 Unions in ASIL are the controlling member as far as syntax is concerned.  It declares a type, not an instance.  The syntax is union enumtype identifier \[= defaultvalue\] where enumtype is the type of the controlling member.  If you leave out the default value, you should set it in the union's constructor.
@@ -66,7 +63,7 @@

 Requesting notification of changes to the controlling member
 ------------------------------------------------------------
-Unions of this type have a built-in event.  Even though you can treat the union's instance as though it were the actual controlling enum member, the [**++**] and [**--**] get mapped to the event, not the controlling member.  (It doesn't make sense to increment or decrement the value of the controlling member anyway.)  The handler should be a command takes an instance of the controlling type (which has the old value of the controlling member) and can throw no exceptions.  If you need to know the new value of the controlling member, just reference the union instance's identifier.
+Unions of this type have a built-in event.  Even though you can treat the union's instance as though it were the actual controlling enum member, the **[++](Operators-inc)** and **[--](Operators-dec)** get mapped to the event, not the controlling member.  (It doesn't make sense to increment or decrement the value of the controlling member anyway.)  The handler should be a command takes an instance of the controlling type (which has the old value of the controlling member) and can throw no exceptions.  If you need to know the new value of the controlling member, just reference the union instance's identifier.
 ~~~~
 command myHandler var MyUnion.ControllingType oldValue
   ' Do something in response to the event.
@@ -76,5 +73,5 @@
 ~~~~

 Methods and properties inside a union
-=====================================
+-------------------------------------
 Unions can have methods and properties.  However, it's methods and properties must be members of the bitfields and structures inside the union, not directly inside the union itself.  (The union can however declare constructors, destructors, and creators.)  Those methods or properties can only be accessed when the controlling member allows access to those fields.

Unions modified by Will Pittenger

Will Pittenger — Sun, 16 Feb 2014 08:21:34 -0000

--- v7
+++ v8
@@ -2,64 +2,22 @@

 Overview
 ========
-Unions are sometimes needed for communicating with C/C++ programs.  They're also how ASIL implements [Variants].  Unions in ASIL are available in two forms: With an external control member and with an internal control member.  A control member is how ASIL ensure the data is valid for the fields you're trying to access.  The control member is an instance of an primitive-based enum type.  (Structure-based enums can't be used with unions.)  The enum type must have explicit or implied values for each entry.  Unlike [Bitfields], some unions can be non-nested types.
+Unions are sometimes needed for communicating with C/C++ programs.  They're also how ASIL implements [Variants].  ASIL ensures the data is valid for the fields you're trying to access with a [control member](Appendices-Terms-Control member).  The control member is an instance of an primitive-based enum type.  (Structure-based enums can't be used with unions.)  The enum type must have explicit or implied values for each entry.  Unlike [Bitfields], unions don't have to be nested inside another type.

-All members of a union must be either a bitfield or a structure.  All unions are required to list an access qualifier (except global unions in DASIL).  The immediate members of the union (the bitfields and structures) are all public to all code with access to the union.  If the member is a structure, it has no name or type associated with it.  Think of such structures as anonymous structures from C++.
-
-Unions with an external control member
-======================================
-Declaring the union
--------------------
-This type of union must be a type inside a structure (but not a structure-based enum).  You can declare your own instance of the controlling enum type if you choose.  The syntax is (public|protected|private) union enumtype controlmember where enumtype is the controlling type and controlmember is the instance of enumtype that will be the controlling member.  Declare and initialize controlmember separately, but it must be a sibling member (in the same enclosing type).  If the union's controlling member might be changed by code in another module, consider marking the instance of the controlling member with the [**volatile**] keyword.  This form of union declares the instance of the union, but not a type.  You only get once instance of the union.
-
-~~~~
-structure EnclosingType
-  public enum MyEnum
-    left = 0 ' This ensures all entries either have explicit values or implicit values
-    right ' Implied value is 1
-
-  public MyEnum controllingMember = MyEnum.left
-
-  public union MyEnum controllingMember
-    struct = MyEnum.left ' This syntax associates the members of this struct with MyENum.left
-      public constructor
-        s$ = "test"
-
-      public var s$
-
-    bitfield = MyEnum.right ' The syntax for a bitfield that's a member of a union is the same as for normal bitfields except we need to associate the bitfield with a entry from MyEnum.
-      public 8 first = 3
-      public 8 second = 5
-      public 8 third = 6
-      public 8 fourth = 9 ' If a reference pointer is 32-bits long, this would be the same length
-
-    ~ ' One tilde causes all members of the union to be padded to the length of the longest member--and no longer.  Two tildes (~~ causes all members of the union to be padded as the compiler sees fit (that is, whatever is considered optimal).  No tildes prevents padding.
-~~~~
-
-Accessing the union's fields
-----------------------------
-With this type of union, when you set the value stored in the controlling member, you're changing which fields are accessible.  The compiler should add code to call the destructor for the previously selected field and then the constructor for the newly selected field when the controlling member's value changes.  You may want those calls to trigger events.  If you try to access a field at the wrong time, ASIL will throw a InvalidUnionFieldError (which doesn't need to be caught or declared).  The code below continues the previous samplle.
-
-~~~~
-public EnclosingType test
-
-test.controllingMember = MyEnum.left
-test.s% = "swfs" ' Valid, no error thrown
-test.first = 5 ' Invalid, throws InvalidUnionFieldError as the controlling member is set to MyEnum.left
-~~~~
+All members of a union must be either a bitfield or a structure (except members of the union's members).  The immediate members of the union (the bitfields and structures) are all public to all code with access to the union.  These immediate members have no name or type associated with it.  Think of them as anonymous structures from C++.  Variants in ASIL are implemented as unions.  See the section on [Variants] for more information.

 Unions with an internal controlling member
 ==========================================
 Declaring the union
 -------------------
-This type of union merges the controlling member with the union itself.  It also declares a type, not an instance.  The syntax is union enumtype \-\ identifier \[= defaultvalue\] where enumtype is the type of the controlling member.  If you leave out the default value, you should set it in your constructor.  (As you will see, this type of union can have it's own constructor, but if you nest it, you don't need one.)
+Unions in ASIL are the controlling member as far as syntax is concerned.  It declares a type, not an instance.  The syntax is union enumtype identifier \[= defaultvalue\] where enumtype is the type of the controlling member.  If you leave out the default value, you should set it in the union's constructor.

-You have a choice of putting the bits used for the controlling member's values at the start of the union (before it's members) or after the union's members.  That's controlled by the @ line shown below.  It's required.  This type of union doesn't need to be a nested type.  In fact, this is how the Variant type is declared.  See the section on [Variants] for how the Variant type is declared.  The type of the controlling member can be nested within the union type.
+You have a choice of putting the bits used for the controlling member's values at the start of the union (before it's members) or after the union's members.  That's controlled by the @ line shown below.  It's required.  The type of the controlling member can be nested within the union type.

 It's unknown if this type of union will default to by reference or by value.

 ~~~~
-union MyUnion.ControllingType - MyUnion
+union MyUnion.ControllingType MyUnion
   public enum ControllingType
     left = 0
     right
@@ -86,7 +44,7 @@

 Accessing the union's fields
 ----------------------------
-Accessing this type of union is different in only two ways: You need to declare an instance and how you change which fields are current.  Syntactically, an instance can be treated as an instance of the controlling enum type.  You can compare it as needed.  You can also set it by setting the union's identifier to an instance of the enum type.  The following code users the union declared above.
+In order to use a union, you need to declare an instance.  Syntactically, an instance can be treated as an instance of the controlling enum type.  You can compare it as needed.  You can also set it by setting the union's identifier to an instance of the enum type.  The following code users the union declared above.

 ~~~~
 var MyUnion myUnionInstance = new MyUnion
@@ -100,21 +58,23 @@

 Generic unions
 --------------
-Unions of this type can be generic.  The syntax is the same as with other generic types.
+Unions can be generic.  The syntax is the same as with other generic types.

 Dealing with changes by external code
 -------------------------------------
-If you need external code to change part of the union, mark your instance of the union's type with the [**volatile**] keyword.
+If you need external code to change part of the union, mark your instance of the union's type with the **[volatile](keywords-volatile) keyword.

 Requesting notification of changes to the controlling member
 ------------------------------------------------------------
-Unions of this type have a built-in event.  Even though you can treat the union's instance as though it were the actual controlling enum member, the [**++**] and [**--**] get mapped to the event, not the controlling member.  (It doesn't make sense to increment or decrement the value of the controlling member anyway.
+Unions of this type have a built-in event.  Even though you can treat the union's instance as though it were the actual controlling enum member, the [**++**] and [**--**] get mapped to the event, not the controlling member.  (It doesn't make sense to increment or decrement the value of the controlling member anyway.)  The handler should be a command takes an instance of the controlling type (which has the old value of the controlling member) and can throw no exceptions.  If you need to know the new value of the controlling member, just reference the union instance's identifier.
+~~~~
+command myHandler var MyUnion.ControllingType oldValue
+  ' Do something in response to the event.

-~~~~
 myUnionInstance ++ &myHandler
 myUnionInstance -- &myHandler
 ~~~~

 Methods and properties inside a union
 =====================================
-Both types of unions can have methods and properties.  However, if the union uses an external controlling member, it's methods and properties must be members of the bitfields and structures inside the union, not directly inside the union itself.  If the method or property lives directly in the union, it can be called at any time.  If it is placed inside one of the bitfields or structures, that method or property can only be access when the controlling member allows access to those fields.
+Unions can have methods and properties.  However, it's methods and properties must be members of the bitfields and structures inside the union, not directly inside the union itself.  (The union can however declare constructors, destructors, and creators.)  Those methods or properties can only be accessed when the controlling member allows access to those fields.

Discussion for Unions page

Will Pittenger — Tue, 11 Feb 2014 09:11:51 -0000

I don't yet know how to solve this problem: If external code changes the controlling member, the [volatile] keyword might not be enough. The problem is firing the event and calling destructors/constructors. I see some options:

Have a timer periodically fire to look for changes (volatile unions only)
Lazily look for changes—This would check for changes to the controlling member only before a member was accessed; works best for DASIL
Hope the remote code calls fires the event for us (I hate this)

Unions modified by Will Pittenger

Will Pittenger — Tue, 11 Feb 2014 08:58:31 -0000

--- v6
+++ v7
@@ -108,11 +108,11 @@

 Requesting notification of changes to the controlling member
 ------------------------------------------------------------
-Unions of this type have a built-in event.  Even though you can treat the union's instance as though it were the actual controlling enum member, the [**++**] and [**--**] get mapped to the event, not the controlling member.  (To doesn't make sense to increment or decrement the value of the controlling member anyway.
+Unions of this type have a built-in event.  Even though you can treat the union's instance as though it were the actual controlling enum member, the [**++**] and [**--**] get mapped to the event, not the controlling member.  (It doesn't make sense to increment or decrement the value of the controlling member anyway.

 ~~~~
 myUnionInstance ++ &myHandler
-myUnionInstance -- &mmyHandler
+myUnionInstance -- &myHandler
 ~~~~

 Methods and properties inside a union

Unions modified by Will Pittenger

Will Pittenger — Tue, 11 Feb 2014 08:57:00 -0000

--- v5
+++ v6
@@ -10,7 +10,7 @@
 ======================================
 Declaring the union
 -------------------
-This type of union must be a type inside a structure (but not a structure-based enum).  You can declare your own instance of the controlling enum type if you choose.  The syntax is (public|protected|private) union enumtype controlmember where enumtype is the controlling type and controlmember is the instance of enumtype that will be the controlling member.  Declare and initialize controlmember separately, but it must be a sibling member (in the same enclosing type).  This form of union declares the instance of 
+This type of union must be a type inside a structure (but not a structure-based enum).  You can declare your own instance of the controlling enum type if you choose.  The syntax is (public|protected|private) union enumtype controlmember where enumtype is the controlling type and controlmember is the instance of enumtype that will be the controlling member.  Declare and initialize controlmember separately, but it must be a sibling member (in the same enclosing type).  If the union's controlling member might be changed by code in another module, consider marking the instance of the controlling member with the [**volatile**] keyword.  This form of union declares the instance of the union, but not a type.  You only get once instance of the union.

 ~~~~
 structure EnclosingType
@@ -102,6 +102,19 @@
 --------------
 Unions of this type can be generic.  The syntax is the same as with other generic types.

+Dealing with changes by external code
+-------------------------------------
+If you need external code to change part of the union, mark your instance of the union's type with the [**volatile**] keyword.
+
+Requesting notification of changes to the controlling member
+------------------------------------------------------------
+Unions of this type have a built-in event.  Even though you can treat the union's instance as though it were the actual controlling enum member, the [**++**] and [**--**] get mapped to the event, not the controlling member.  (To doesn't make sense to increment or decrement the value of the controlling member anyway.
+
+~~~~
+myUnionInstance ++ &myHandler
+myUnionInstance -- &mmyHandler
+~~~~
+
 Methods and properties inside a union
 =====================================
 Both types of unions can have methods and properties.  However, if the union uses an external controlling member, it's methods and properties must be members of the bitfields and structures inside the union, not directly inside the union itself.  If the method or property lives directly in the union, it can be called at any time.  If it is placed inside one of the bitfields or structures, that method or property can only be access when the controlling member allows access to those fields.

Unions modified by Will Pittenger

Will Pittenger — Sun, 09 Feb 2014 12:56:24 -0000

--- v4
+++ v5
@@ -84,8 +84,8 @@
   ~ ' One tilde causes all members of the union to be padded to the length of the longest member--and no longer.  Two tildes (~~ causes all members of the union to be padded as the compiler sees fit (that is, whatever is considered optimal).  No tildes prevents padding.  Must be last.
 ~~~~

-Accessing the union
--------------------
+Accessing the union's fields
+----------------------------
 Accessing this type of union is different in only two ways: You need to declare an instance and how you change which fields are current.  Syntactically, an instance can be treated as an instance of the controlling enum type.  You can compare it as needed.  You can also set it by setting the union's identifier to an instance of the enum type.  The following code users the union declared above.

 ~~~~
@@ -98,6 +98,10 @@
 myUnionInstance.first = 34
 ~~~~

+Generic unions
+--------------
+Unions of this type can be generic.  The syntax is the same as with other generic types.
+
 Methods and properties inside a union
 =====================================
 Both types of unions can have methods and properties.  However, if the union uses an external controlling member, it's methods and properties must be members of the bitfields and structures inside the union, not directly inside the union itself.  If the method or property lives directly in the union, it can be called at any time.  If it is placed inside one of the bitfields or structures, that method or property can only be access when the controlling member allows access to those fields.

Unions modified by Will Pittenger

Will Pittenger — Sun, 09 Feb 2014 12:51:24 -0000

--- v3
+++ v4
@@ -97,3 +97,7 @@
 myUnionInstance = MyUnion.ControllingType.right ' Destroys s$ and creates the bitfield
 myUnionInstance.first = 34
 ~~~~
+
+Methods and properties inside a union
+=====================================
+Both types of unions can have methods and properties.  However, if the union uses an external controlling member, it's methods and properties must be members of the bitfields and structures inside the union, not directly inside the union itself.  If the method or property lives directly in the union, it can be called at any time.  If it is placed inside one of the bitfields or structures, that method or property can only be access when the controlling member allows access to those fields.