<commit_before>---

Copyright 2013 Mentor Graphics Corp.  All Rights Reserved.

---

Fix parameter handling for unique_ids in VIEC
### xtUML Project Design Note


1. Abstract
-----------
Verifier cannot export the values of parameters of type 'unique_id'. Instead
it throws a java runtime error. This note discusses the options for fixing
this.

2. Document References
----------------------
[1] dts0100936030 - Verifier execution breaks when VIEC synchronous operation
    with parameter of unique_id type is invoked.

[2] https://github.com/xtuml/internal/issues/78

[3] http://en.wikipedia.org/wiki/Universally_unique_identifier

3. Background
-------------
There are two types of unique ids, those internal to Verifier and externally
created ones. Internally, each running component instance allocates unique
ids as integers starting at 1 and incrementing for each unique id allocated.
Externally, unique_ids are assumed by Verifier to be based on an
implementation of the UUID (Universally Unique IDentifier) standard[3]. This
problem is caused by the impedance mismatch between Verifier's internal
implementation and the UUID standard. This impedance mismatch is a direct
result of the two implementations meeting different requirements. Since
instance populations in Verifier are partitioned by executing components, a
unique identifier need only be unique for the component instance that created
it. The UUID standard however meets a requirement much greater in scope,
that is, it is required to produce identifiers which are unique in a global,
fully asynchronous system. The only possible way to meet this is to create
very large pseudo-random numbers which have an astronomically low probability
of duplication. This fix for this issue must find a robust way of bridging
this impedance gap.

4. Requirements
---------------
4.1 Verifier must handle passing unique id's as parameter values in both
    directions.

4.2 A unique_id passed out must identify any internal element associated with
    it when it is passed back in.
    
4.3 Unique ID's created outside of Verifier and passed in must be passed back
    out unmodified.

5. Analysis
-----------
Looking at the code, Unique Id's must not have been part of the original data
set specified as supported. The code which marshals data values into and out
of Verifier has almost no explicit support for them.

This is the exception reported in the issue:

Exception in thread "Verifier (RealizedTestReportGenerator)"
java.lang.IllegalArgumentException: Invalid UUID string: 1
        at java.util.UUID.fromString(Unknown Source)
        at com.mentor.nucleus.bp.debug.java.access.VerifierInvocationHandler.
                  convertToRawJavaType(VerifierInvocationHandler.java:371)

This is thrown when an internal value of unique_id is passed out from Verifier.
The value passed in to the UUID constructor is '1', which does not conform to
the UUID statndard as implemented for Java so the exception is to be expected.

5.1 Fixes considered

One obvious way of fixing the headline issue is just taking the passed simple
unique_id integer allocated and forming it into the UUID format such that the
exception is not thrown. However, there are a couple issues with this approach
that need to be considered:

5.1.1 UUID format

When we moved to global data types, all global types had to have the same UUID
value in all workspaces. We did this by allocating the integer value into the
lower portion of the UUID and stamped the upper group with a semi human
readable digit sequence that would make it stand out as a fixed UUID value. We
might consider the same strategy here, but choose a different digit sequence.

5.1.2 ID Uniqueness

Section 3 called out the impedance mismatch between Verifier uniqueness and
UUID uniqueness. This is a bigger problem than it looks. Verifier's unique_id
implementation cannot hold a complete UUID internally so a major Verifier re-
write would be required. Further, such a rewrite would likely have to
wait until after removing dependency on the generator parser. There
is another reason why we might not want to simply use UUID's internally.
Currently Verifier displays the identifier of instances in the Session
Explorer and Variables views. Showing a UUID here is impractical, not to
mention illegible. This might be addressed by displaying a trucated portion of
the UUID, but all in all, using UUID's internally does not look to be an
attractive proposal. The conclusion is that we must produce some kind of
mapping between internal and external unique id's. This poses another problem;
the simple mapping proposed in 5.1.1 does not remotely meet the global UUID
standard in that such synthesized UUID's would not be unique between components
or workspaces.

5.1.2.1 Inter-component uniqueness

We could make unique_ids unique for their creating component by additionally
inserting the component instance id into the exported UUID. However this raises
the question of what to do if a UUID created in one component is passed into
another and used for locating an instance. The simplest response would be to
simply not find a match, but it might be desirable to report an error.

5.1.2.2 Inter-workspace uniqueness

This is only an issue if runtime data is shared between models running on
different machines and/or workspaces. Although Verifier does not support this
at present, it has been discussed as a future roadmap item. However, after this
fix, customers will be able to get unique_id values out into java and beyond,
so this possiblity must be considered now, even if we decide to specify that
inter-machine/workspace uniqueness will not be supported.

5.1.2.3 Proposal

Simple mapping, plus an origin stamp, plus component id stamp gives reasonable
uniqueness assurance for now. We should add a statement to the release notes
to manage customer expectation in the wider scope.

5.2 Handle incoming and outgoing unique ids

There is no point in addressing the headline issue without also addressing
incoming UUID values cleanly, more field issues are bound to follow. Out-
going ids are fully discussed in 5.1 above. Incoming id's pose another new
challenge. Given that we adopt the outgoing mappings proposed in 5.1, what
does Verifier do with incoming UUID's that were created externally? As
already observed, we cannot pass them around the running model, and we cannot
usefully display them. We could either construct a map, or add a string
attribute to store the UUID as it is passed around the Verifier runtime.

5.2.1 UUID map

The proposal here is that we hold a map of incoming UUID's which do not match
the signature proposed in 5.1.1. Then, a new internal unique_id value is
allocated and actually used within Verifier. The incoming UUID is placed in the
Map using the allocated unique_id as a key. When a unique id is output, the
map is consulted. If the key produces a match, the original UUID is pulled from
the Map and output. If it is not found in the map, the UUID synthesis policy
proposed in 5.1 is followed. 

5.2.2 String attribute

This alternative is that an incoming UUID is converted to a unique_id value as
before, but rather than creating a map, the UUID is stored in anew string
attibute of Runtime value. On output, this string is used to recreate the UUID
if it contains a valid value.

5.2.3 Conclusion

It is more diffiult to make a choice here, the Map solution is the simpler of
the two, but it would be difficult to show the actual UUID value in the UI during
debugging. The second proposal adds a lot of data to be shifted around during
Verifier runtime, and even if the UUID is present, it is not clear that the
current UI design would make it easy to show the actual UUID value even if it was
easily accessible. On balance, the proposal in 5.2.1 is selected for its
simplicity.

6. Design
---------
Note that input here means any value coming into the Verifier runtime, this
includes parameter values and the return values of outgoing interface operations.
Conversely output means any parameter value passed to an outgoing call from
Verifier, together with the return value of any interface call made on Verifier
from external code.

6.1 UUID output format

6.1.1 Verifier originated unique_id values

The format of UUID values output by Verifier shall be:

idee-da7a-c0c0-c0c0-idididididid

Where:
- The first two groups are a fixed stamp analogous to ba5e-da7a for built in
  data types.
- The third and fourth groups shall be the component instance id rendered as
  8 hexadecimal digits and split between the two groups, high word first, lower
  word second.
- The final group shall be the unique identifier value rendered as 12 hexadecimal
  digits.

6.1.2 Externally originated UUID values

A private map shall be maintained in VerifierInvocationHandler. When an
externally created UUID is passed to Verifier, an internally generated unique_id
will be created for it. The UUID value will be added to the map using the
new unique_id value as the retrieval key. When the unique_id value is processed
for output, the key is used to extract the original UUID from the map. If the map
does not contain a value for the unique_id value, we assume that it originated
internal to Verifier and output it using the policy specified in 6.1.


6.2 UUID input policy

6.2.1 Verifier originated unique_id values

When a UUID value is passed into Verifier, the UUID is examined as a string. If
it matches the format described in 6.1.1, the unique_id value is extracted from
the last group of 12 digits and passed into the Verifier runtime.

6.2.2 Externally originated UUID values

When an externally originated UUID arrives which does not conform to the format
defined in 6.1, the map is checked to see if the UUID has been seen before.
If it has, then the corresponding unique_id is extracted from the map and passed to<commit_msg>Job: dts0100936030 GH #78 Correct proposed UUID format.<commit_after>---

Copyright 2013 Mentor Graphics Corp.  All Rights Reserved.

---

Fix parameter handling for unique_ids in VIEC
### xtUML Project Design Note


1. Abstract
-----------
Verifier cannot export the values of parameters of type 'unique_id'. Instead
it throws a java runtime error. This note discusses the options for fixing
this.

2. Document References
----------------------
[1] dts0100936030 - Verifier execution breaks when VIEC synchronous operation
    with parameter of unique_id type is invoked.

[2] https://github.com/xtuml/internal/issues/78

[3] http://en.wikipedia.org/wiki/Universally_unique_identifier

3. Background
-------------
There are two types of unique ids, those internal to Verifier and externally
created ones. Internally, each running component instance allocates unique
ids as integers starting at 1 and incrementing for each unique id allocated.
Externally, unique_ids are assumed by Verifier to be based on an
implementation of the UUID (Universally Unique IDentifier) standard[3]. This
problem is caused by the impedance mismatch between Verifier's internal
implementation and the UUID standard. This impedance mismatch is a direct
result of the two implementations meeting different requirements. Since
instance populations in Verifier are partitioned by executing components, a
unique identifier need only be unique for the component instance that created
it. The UUID standard however meets a requirement much greater in scope,
that is, it is required to produce identifiers which are unique in a global,
fully asynchronous system. The only possible way to meet this is to create
very large pseudo-random numbers which have an astronomically low probability
of duplication. This fix for this issue must find a robust way of bridging
this impedance gap.

4. Requirements
---------------
4.1 Verifier must handle passing unique id's as parameter values in both
    directions.

4.2 A unique_id passed out must identify any internal element associated with
    it when it is passed back in.
    
4.3 Unique ID's created outside of Verifier and passed in must be passed back
    out unmodified.

5. Analysis
-----------
Looking at the code, Unique Id's must not have been part of the original data
set specified as supported. The code which marshals data values into and out
of Verifier has almost no explicit support for them.

This is the exception reported in the issue:

Exception in thread "Verifier (RealizedTestReportGenerator)"
java.lang.IllegalArgumentException: Invalid UUID string: 1
        at java.util.UUID.fromString(Unknown Source)
        at com.mentor.nucleus.bp.debug.java.access.VerifierInvocationHandler.
                  convertToRawJavaType(VerifierInvocationHandler.java:371)

This is thrown when an internal value of unique_id is passed out from Verifier.
The value passed in to the UUID constructor is '1', which does not conform to
the UUID statndard as implemented for Java so the exception is to be expected.

5.1 Fixes considered

One obvious way of fixing the headline issue is just taking the passed simple
unique_id integer allocated and forming it into the UUID format such that the
exception is not thrown. However, there are a couple issues with this approach
that need to be considered:

5.1.1 UUID format

When we moved to global data types, all global types had to have the same UUID
value in all workspaces. We did this by allocating the integer value into the
lower portion of the UUID and stamped the upper group with a semi human
readable digit sequence that would make it stand out as a fixed UUID value. We
might consider the same strategy here, but choose a different digit sequence.

5.1.2 ID Uniqueness

Section 3 called out the impedance mismatch between Verifier uniqueness and
UUID uniqueness. This is a bigger problem than it looks. Verifier's unique_id
implementation cannot hold a complete UUID internally so a major Verifier re-
write would be required. Further, such a rewrite would likely have to
wait until after removing dependency on the generator parser. There
is another reason why we might not want to simply use UUID's internally.
Currently Verifier displays the identifier of instances in the Session
Explorer and Variables views. Showing a UUID here is impractical, not to
mention illegible. This might be addressed by displaying a trucated portion of
the UUID, but all in all, using UUID's internally does not look to be an
attractive proposal. The conclusion is that we must produce some kind of
mapping between internal and external unique id's. This poses another problem;
the simple mapping proposed in 5.1.1 does not remotely meet the global UUID
standard in that such synthesized UUID's would not be unique between components
or workspaces.

5.1.2.1 Inter-component uniqueness

We could make unique_ids unique for their creating component by additionally
inserting the component instance id into the exported UUID. However this raises
the question of what to do if a UUID created in one component is passed into
another and used for locating an instance. The simplest response would be to
simply not find a match, but it might be desirable to report an error.

5.1.2.2 Inter-workspace uniqueness

This is only an issue if runtime data is shared between models running on
different machines and/or workspaces. Although Verifier does not support this
at present, it has been discussed as a future roadmap item. However, after this
fix, customers will be able to get unique_id values out into java and beyond,
so this possiblity must be considered now, even if we decide to specify that
inter-machine/workspace uniqueness will not be supported.

5.1.2.3 Proposal

Simple mapping, plus an origin stamp, plus component id stamp gives reasonable
uniqueness assurance for now. We should add a statement to the release notes
to manage customer expectation in the wider scope.

5.2 Handle incoming and outgoing unique ids

There is no point in addressing the headline issue without also addressing
incoming UUID values cleanly, more field issues are bound to follow. Out-
going ids are fully discussed in 5.1 above. Incoming id's pose another new
challenge. Given that we adopt the outgoing mappings proposed in 5.1, what
does Verifier do with incoming UUID's that were created externally? As
already observed, we cannot pass them around the running model, and we cannot
usefully display them. We could either construct a map, or add a string
attribute to store the UUID as it is passed around the Verifier runtime.

5.2.1 UUID map

The proposal here is that we hold a map of incoming UUID's which do not match
the signature proposed in 5.1.1. Then, a new internal unique_id value is
allocated and actually used within Verifier. The incoming UUID is placed in the
Map using the allocated unique_id as a key. When a unique id is output, the
map is consulted. If the key produces a match, the original UUID is pulled from
the Map and output. If it is not found in the map, the UUID synthesis policy
proposed in 5.1 is followed. 

5.2.2 String attribute

This alternative is that an incoming UUID is converted to a unique_id value as
before, but rather than creating a map, the UUID is stored in anew string
attibute of Runtime value. On output, this string is used to recreate the UUID
if it contains a valid value.

5.2.3 Conclusion

It is more diffiult to make a choice here, the Map solution is the simpler of
the two, but it would be difficult to show the actual UUID value in the UI during
debugging. The second proposal adds a lot of data to be shifted around during
Verifier runtime, and even if the UUID is present, it is not clear that the
current UI design would make it easy to show the actual UUID value even if it was
easily accessible. On balance, the proposal in 5.2.1 is selected for its
simplicity.

6. Design
---------
Note that input here means any value coming into the Verifier runtime, this
includes parameter values and the return values of outgoing interface operations.
Conversely output means any parameter value passed to an outgoing call from
Verifier, together with the return value of any interface call made on Verifier
from external code.

6.1 UUID output format

6.1.1 Verifier originated unique_id values

The format of UUID values output by Verifier shall be:

ideeda7a-0000-c0c0-c0c0-idididididid

Where:
- The first group is a fixed stamp analogous to ba5eda7a for built in
  data types.
- The second group is all zero.
- The third and fourth groups shall be the component instance id rendered as
  8 hexadecimal digits and split between the two groups, high word first, lower
  word second.
- The final group shall be the unique identifier value rendered as 12 hexadecimal
  digits.

6.1.2 Externally originated UUID values

A private map shall be maintained in VerifierInvocationHandler. When an
externally created UUID is passed to Verifier, an internally generated unique_id
will be created for it. The UUID value will be added to the map using the
new unique_id value as the retrieval key. When the unique_id value is processed
for output, the key is used to extract the original UUID from the map. If the map
does not contain a value for the unique_id value, we assume that it originated
internal to Verifier and output it using the policy specified in 6.1.


6.2 UUID input policy

6.2.1 Verifier originated unique_id values

When a UUID value is passed into Verifier, the UUID is examined as a string. If
it matches the format described in 6.1.1, the unique_id value is extracted from
the last group of 12 digits and passed into the Verifier runtime.

6.2.2 Externally originated UUID values

When an externally originated UUID arrives which does not conform to the format
defined in 6.1, the map is checked to see if the UUID has been seen before.
If it has, then the corresponding unique_id is extracted from the map and passed to
{'fraction_non_alphanumeric': 0.036552733881960925, 'fraction_numerical': 0.012924723582571818, 'mean_word_length': 4.105154639175257, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 6, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '931303', 'n_tokens_mistral': 5094, 'n_tokens_neox': 4795, 'n_words': 3119}