Check-in [bc5f85b499]
Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Checkpoint on the how to translate with micca document.
Timelines: family | ancestors | descendants | both | micca-develop
Files: files | file ages | folders
SHA1:bc5f85b499372e6f5df8219bca1b1cc4f2937fac
User & Date: andrewm 2019-03-13 16:59:32
Context
2019-03-14
16:09
Checkpoint on how to translate with micca document. check-in: a3d130ad8e user: andrewm tags: micca-develop
2019-03-13
16:59
Checkpoint on the how to translate with micca document. check-in: bc5f85b499 user: andrewm tags: micca-develop
2019-03-11
19:44
Checkpoint on how to translate document. check-in: 00c9bc755a user: andrewm tags: micca-develop
Changes

Changes to micca/doc/howto/Makefile.

20
21
22
23
24
25
26

27
28
29
30
31
32
33
DOCPARTS =\
	intro.txt\
	marking.txt\
	syntax.txt\
	data.txt\
	dynamics.txt\
	processing.txt\

	bridge.txt\
	codeorg.txt\
	bibliography.txt\
	$(NULL)

DIAGRAMS =\
	micca-translation.uxf\







>







20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
DOCPARTS =\
	intro.txt\
	marking.txt\
	syntax.txt\
	data.txt\
	dynamics.txt\
	processing.txt\
	lesser.txt\
	bridge.txt\
	codeorg.txt\
	bibliography.txt\
	$(NULL)

DIAGRAMS =\
	micca-translation.uxf\

Changes to micca/doc/howto/data.txt.

5
6
7
8
9
10
11


















































12
13



14
15
16
17




18
19
20
21
22
23




24
25
26
27








28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46





47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65


66
67
68
69
70
71
72
73






74
75
76
77
78
79
80
81
82
83
84
85
86
87

88
89
90
91
92
93
94
..
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
...
130
131
132
133
134
135
136

137


















138

139

140




141
























































































































































































































142
143
144


145
146

































































147
148
149
first and that you insure that `micca` reads the DSL contining just
the data specifications without error.
In subsequent additions to the domain configuration,
state models and domain activities are added.
Getting the foundations in data correct are essential to the
remaining parts of the translation and so they must be done first.



















































=== How memory is handled




`Micca` assumes that all domain data is held in the primary memory of
a processor and the memory is directly addressable.
This is a common situation, but it is important to realize that
there is no assumption of secondary storage such as a disk drive.





`Micca` also assumes that the maximum number of instances of each class
is defined at compile time.
The `micca` run-time does no no dynamic allocation of memory space
off of a system heap, _i.e._ there are no calls to `malloc()`.
Each class has its own pool of memory from which instances are created.




That pool must be sized for the worst case number of instances the
class will ever have and that size is known when the ``C'' code
for the translation is compiled.
Memory is handled in this way to make it more deterministic.









For programmers who are more accustomed to dynamic memory allocation,
worst case memory sizing may seem restrictive or sub-optimal.
In practice,
it is slightly more work to consider the number of instances a class
may have,
but rarely are _arbitrary_ numbers of class instances required.

For example,
one may consider wanting an arbitrary number of network connections.
In truth,
operating systems do not allow processes to consume extremely large
numbers of resources and even if the resources were available,
at some time the ability service connections runs up against the
compute power of the processor.
It may seem like an arbitrary number are required, but what if that
number were 7 million?
In practice,
the number of instances of a class are typically small.






Because all data is held in primary memory and the size of that
memory is known at compile time,
the platform specific model that `micca` targets has two characteristics
that significantly help the implementation.

. All class instances have an architecturally generated identifier
    that consists of its address in primary memory.
    This identifier is used internal to the domain for all references
    to the class instances.
. All class instances have an architecturally generated identifier
    that can be used outside of the domain in order to specify
    the identify of class instances requesting or receiving services.
    The external identifier is the index in the storage pool array
    of a class.
    It is integer valued and unique within a given class.
    To uniquely identify a class instance outside of a domain,
    we must know both the class to which the instance belongs and its
    external identifying integer value.



Neither of the previous characteristics is profound.
Most programs that use data from primary memory use a _pointer_ or
_object id_ as a reference handle.
Accessing the class indirectly through a reference is a fundamental
mechanism supported by the addressing modes of all modern processors.
The mechanism is so common that we often forget that we are imposing
an identification scheme on the underlying classes.







=== Translating data types

* strings are special
* sizing integers

=== Translating classes

In our usage here,
we are overloading the term _class_ to have different meanings.
A model class and a platform-specific class are two distinct things.
They are related.
They are counterparts of each other in the model and platform realms,
but they are very different entities, logically.

In this section,
we discuss how to transform the logic of a model class into the
specifications of an platform-specific class.
To be clear,
we will refer to _model class_ when we are discussing the class
characteristics as they are presented in the data model and
_platform class_ when we are discussing how the implementation
................................................................................
==== Purely descriptive attributes

Attributes that are descriptive in nature and play no other role in the
model class are declared using `attribute` commands.
For example,
a model class might appear as:

["plantuml",title="Pump class in a model"]
----
@startuml
hide methods
hide circle
skinparam class {
    BackgroundColor yellow
    BorderColor black
................................................................................
class Pump {
    attribute Max_pressure MPa_t
    attribute Min_pressure MPa_t
    attribute Flow_rate LpM_t
}
----


Note, attribute names must be value ``C'' identifiers and we assume


















that the `MPa_t` and `LpM_t` type aliases have been defined.

































































































































































































































=== Translating relationships

* names as "C" identifiers



* data type translation



































































// vim:syntax=asciidoc:







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|

>
>
>

|
|
|
>
>
>
>

|

|
|
|
>
>
>
>
|
|


>
>
>
>
>
>
>
>






|
<





|





>
>
>
>
>




|











|


>
>

|






>
>
>
>
>
>













|
>







 







|







 







>
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
>

>

>
>
>
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>


<
>
>

<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>



5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
...
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
...
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466

467
468
469

470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
first and that you insure that `micca` reads the DSL contining just
the data specifications without error.
In subsequent additions to the domain configuration,
state models and domain activities are added.
Getting the foundations in data correct are essential to the
remaining parts of the translation and so they must be done first.

A `micca` domain specification starts with the `domain` command.
For brevity,
the examples in this section assume they are placed in the
domain script definition of a `domain` command.
The following shows a sketch of how a domain script could be structured.
The order of commands in a domain configuration script is arbitrary.
`Micca` reads and parses the entire script before attempting to generate
code.
Consequently,
you need not be concerned about forward declarations or insuring that
things are some how _defined_ before they are _used_.
The `micca` DSL is a specification language and not an executable language.

.Domain command example
==============
----
domain atc {
    # Domain commands define the characteristics of a domain.
    # These are:
    #       class
    #       association
    #       generalization
    #       domainop
    #       eentity
    #       typealias
    #       interface
    #       prologue
    #       epilogue

    class Controller {
        # Class commands define the implementation classes.
        # These are:
        #       attribute
        #       classop
        #       instop
        #       statemodel
        #       polymorphic
        #       constructor
        #       destructor
    }

    association R1 Station 0..1--1 Controller

    # ...
    # and so on, giving the platform specific description of the domain
}
----
==============


=== How memory is managed

When translating the data portion of an XUML model,
it is helpful to understand the platform specifics on which the
translated code is run.
`Micca` assumes that all domain data is held in the primary memory of
a processor and, consequently, the memory is directly addressable.
This is a common situation, but it is important to emphasize that
there is no assumption of secondary storage such as a disk drive
and no presumed persistance as might be provided by a database
management system.
The execution architecture provide by `micca` is _not_ targeted
at the class of applications which would require external data storage.

`Micca` also insists that the maximum number of instances of each class
is defined at compile time.
The `micca` run-time does no dynamic memory allocation
from a system heap, _i.e._ there are no calls to `malloc()`.
Each class has its own pool of memory where instances are either part of
the initial instance population or are created at run-time.
The memory pool is declared as a ``C'' variable of array type.
Initial instances differ from dynamically created instances by
providing initial values for each attribute.
The memory pool for a class must be sized for the worst case number of
instances the class will ever have and that size is known when the ``C'' code
for the translation is compiled.
Memory is handled in this way to make it more deterministic.

The most important concepts about how data is structured by `micca` are:

. Each implementation class definition is converted into a ``C'' structure
    definition.
. The instances of a class are stored in an array of structures corresponding
    to the implementation class definition and the size of the
    array is fixed at compile time.

For programmers who are more accustomed to dynamic memory allocation,
worst case memory sizing may seem restrictive or sub-optimal.
In practice,
it is slightly more work to consider the number of instances a class
may have,
but rarely are an _arbitrary_ number of class instances required.

For example,
one may consider wanting an arbitrary number of network connections.
In truth,
operating systems do not allow processes to consume extremely large
numbers of resources and even if the resources were available,
at some time the ability to service connections runs up against the
compute power of the processor.
It may seem like an arbitrary number are required, but what if that
number were 7 million?
In practice,
the number of instances of a class are typically small.
Furthermore,
if your application truly makes demands for very large numbers of class
instances,
them you should choose a different target translation platform
than `micca` provides.

Because all data is held in primary memory and the size of that
memory is known at compile time,
the platform specific model that `micca` targets has two characteristics
that are particularly helpful to the implementation.

. All class instances have an architecturally generated identifier
    that consists of its address in primary memory.
    This identifier is used internal to the domain for all references
    to the class instances.
. All class instances have an architecturally generated identifier
    that can be used outside of the domain in order to specify
    the identify of class instances requesting or receiving services.
    The external identifier is the index in the storage pool array
    of a class.
    It is integer valued and unique within a given class.
    To uniquely identify an instance outside of a domain,
    we must know both the class to which the instance belongs and its
    external identifying integer value.
    `Micca` automatically generates pre-processor symbols for this
    information.

Neither of the previous characteristics is particularly profound.
Most programs that use data from primary memory use a _pointer_ or
_object id_ as a reference handle.
Accessing the class indirectly through a reference is a fundamental
mechanism supported by the addressing modes of all modern processors.
The mechanism is so common that we often forget that we are imposing
an identification scheme on the underlying classes.
However,
it is important to note that the use of a memory address as a class
instance identifier does _not_ enforce any identity constraints
imposed by identifying attributes of a class.
This limitation is considered below when we discuss the processing
associated with instance creation.

=== Translating data types

* strings are special
* sizing integers

=== Translating classes

In our usage here,
we are overloading the term _class_ to have different meanings.
A model class and a platform-specific class are two distinct things.
They are related.
They are counterparts of each other in the model and platform realms,
but they are logically different entities
and that distinction must be clear in the translators thinking.
In this section,
we discuss how to transform the logic of a model class into the
specifications of an platform-specific class.
To be clear,
we will refer to _model class_ when we are discussing the class
characteristics as they are presented in the data model and
_platform class_ when we are discussing how the implementation
................................................................................
==== Purely descriptive attributes

Attributes that are descriptive in nature and play no other role in the
model class are declared using `attribute` commands.
For example,
a model class might appear as:

["plantuml",title="Pump model class"]
----
@startuml
hide methods
hide circle
skinparam class {
    BackgroundColor yellow
    BorderColor black
................................................................................
class Pump {
    attribute Max_pressure MPa_t
    attribute Min_pressure MPa_t
    attribute Flow_rate LpM_t
}
----

[NOTE]
Class names and attribute names must be valid ``C''
identifiersfootnote:[A valid ``C'' identifier must start with a
letter or underscore and be followed by any number of letters,
underscores or decimal digits.
Note, some ``C'' compilers may limit the number of characters
in an identifier that are considered significant.
Most modern ``C'' compilers to not have such limitations.].
These names are passed along to the ``C'' compiler to name structures
and structure members.
Analysts may name entities as they wish for the clarity of the analytical
model.
Translation must take the names and make them suitable for the
target platform.
In this case,
it usually suffices to replace any characters that cannot be in a
``C'' identifier with the underscore (`_`) character.
It is important *not* to obfuscate the correspondence between the
attribute name in the model and the one used in the implementation.
We also assume
that the `MPa_t` and `LpM_t` type aliases have been defined as discussed
previously.

===== Default attribute values

An attribute may be given a default value.
If the analyst provides a default value specification in the model
it can be used as a default value for the translation by
given the `attribute` command the `-default` option.

For the previous example,
if the class had appeared as:

["plantuml",title="Pump model class with default attribute"]
----
@startuml
hide methods
hide circle
skinparam class {
    BackgroundColor yellow
    BorderColor black
}

class Pump {
    Pump ID : ID    {I}
    Max pressure : MPa
    Min pressure : MPa   = 15
    Flow rate : Liters per minute
}
@enduml
----

We can specify the default value as:

.Pump platform class 
----
class Pump {
    attribute Max_pressure MPa_t
    attribute Min_pressure MPa_t -default 15
    attribute Flow_rate LpM_t
}
----

Attributes which have a default value can be omitted when creating
an instance, either at run-time or as part of the initial instance population.

===== Zero initialized attributes

The `attribute` command also takes an optional `-zeroinit` option
which gives the attribute a default value of all bits being zero.
Like an attribute with a default value,
an attribute declared as `-zeroinit` need not have a value provided when
it is created.

===== Dependent attributes

An `attribute` may be modeled as _mathematically dependent_.
For those attributes,
the analysis model must provide a _formula_ in action language that
computes the value of the attribute.
The formula must then be translated into ``C''.
The following is a brief example of a dependent attribute translation.

["plantuml",title="Model class with dependent attribute"]
----
@startuml
hide methods
hide circle
skinparam class {
    BackgroundColor yellow
    BorderColor black
}
skinparam note {
    BackgroundColor white
    BorderColor black
}

class Extent {
    ID : unique        {I}
    Height : numeric
    Width : numeric
    Area : numeric   {M}
}

note bottom : Area = Height * Width
@enduml
----

We can specify the attribute as dependent and supply the
code necessary to compute the formula.

.Pump platform class 
----
class Extent {
    attribute Height unsigned
    attribute Width unsigned
    attribute Area -dependent {
        *Area = self->Height * self->Width ;
    }
}
----

We consider how the ``C'' code is specified in a following section.

==== Identifying attributes

Since `micca` is providing an identifier for each instance,
our goal is to eliminate identifying attributes whenever possible.
Attributes that are system generated and serve only an
identifying or referential role may simply be elided.
In the previous examples,
the model attributes, *Pump.Pump ID* and *Extent.ID* were not
present in the corresponding specifications for the platform class.

In the following situations identifying attributes may *not* be eliminated:

* The attribute serves a descriptive role for the processing and it's value
    is read and used in a computation.
* The attribute value is needed to insure an identity constraint.

In both these cases, the attribute,
with an appropriate ``C'' data type,
must be included in the platform class definition.

==== Referential attributes

Once again, the platform specific choice of `micca` to provide an
identifier for a class instance,
means that identifier can be used in place of referential attributes
to manage relationships.
As we see in the following section,
`micca` is able to provide the necessary storage and operations
on class instance references to implement relationships.
So, again our intent is to eliminate referential attributes when possible.

There is a situation where this is _not_ possible.

* If the model reads a referential attribute and treats it descriptively,
  _i.e._ uses the attribute value in some computation,
  then it is necessary to translate that attribute access into a
  relationship navigation that ultimately terminates at the identifier
  value to which the attribute refers.

Consider the following class model fragment.

["plantuml",title="Model class with referential attribute"]
----
@startuml
hide methods
hide circle
skinparam class {
    BackgroundColor yellow
    BorderColor black
}

class Part {
    Manufacturer : name    {I,R1}
    Model Number : name   {I,R1}
    Serial Number : string  {I}
}

class "Part Description" {
    Manufacturer : name  {I}
    Model Number : name {I}
    Color : color
}

Part "1..*" -- "1" "Part Description" : R1

@enduml
----

Assume that there is an activity in the model which determines the
the serial numbers of all the *Parts* manufactured by the Acme company.
That activity is a search of the *Part* instances finding those
whose *Manufacturer* attribute equals "Acme".
In this situation,
*Part.Manufacturer* can be eliminated from the platform class,
but *Part Description.Manufacturer* must be retained.
The search must then be coded to navigate the *R1* association
to obtain the value of the *Manufacturer* attribute.
We know that referential attributes refer to identifying attributes and
by following the relationship (perhaps multiple relationships) we must
eventually arrive at an identifying attribute value.

So the above situation might be translated as:

----
class Part_Description {
    attribute Manufacturer : {char[25]}
    attribute Model_Number : {char[25]}
    attribute Color : unsigned
}

class Part {
    attribute Serial_Number {char[25]}

    classop MRT_InstSet findByManufacturer {manuf {char const *}} {
    <%  Part instset matchedParts                                       %>
    <%  Part foreachInstance partRef                                    %>
            // This statement navigates R1 from Part to Part Description
    <%      instance partRef findOneRelated descRef R1                  %>
            if (strcmp(descRef->Manufacturer, manuf) == 0) {
    <%          instset matchedParts add partRef                        %>
            }
    <%  end                                                             %>
        return matchedParts ;
    }
}

association R1 Part 1..*--1 Part_Description
----

For the moment,
don't be startled by the contents of the `classop`.
We will cover translating actions into ``C'' later.
For now,
we want to emphasize that the search for *Part* instances to match a given
manufacture's name does not use a *Part* attribute.
Rather,
the value of the *Manufacturer* is obtained from the *Part Description*
by navigating the *R1* association.
So, no *Manufacturer* attribute is stored in a *Part* and any
time the *Manufacture* attribute value is needed,
it is obtained by navigating the relationship.

=== Translating relationships


* no NULLs and the necessity of associative classes
* one-to-many associations as composition


=== Populating the data

The final step in translating the data model for a domain is to
specify its population.
Populating the data model consists of specifying _initial instances_
and the amount of storage to allocate for each platform class.
Initial instances are those class instances that exist before the
domain runs.
As dicussed previously,
each platform class has its own storage pool for instances.
In addition to initial instances,
you can specify the number of additional slots to allocate to the
storage pool.
The total number of instances is then the sum of the initial instances
and the number of additional slots allocated for run-time usage.
Note, if an initial instance is deleted at run-time, then
its storage slot becomes available for subsequent use by a run-time
create instance.

It is advisable to keep the population of a domain in a file separate
from its configuration.
As translated domains are tested,
it is convenient to use a variety of different populations
to drive the code execution paths for testing.
`Micca` will read multiple files for a domain, so keeping
test populations separate from production populations is convenient.

The analytical materials supply for translation must include
a population of the data model.
The recommended practice is to supply the population in
tabular notation, one set of class instances per page,
similar to a page in a spreadsheet.
Values for all attributes are supplied.
It is possible to specify the model level population purely by
data values.

The `micca` `population` command is used to define the storage
requirements and any initial instances for the domain.
One of the few command ordering requirements for `micca` is that
the `population` command must follow the domain definition given
by the `domain` command.
The following shows a brief sketch of a population.

.Domain command example
==============
----
population atc {
    # Population commands define the data values in a domain
    # These are:
    #       class
    #       assigner

    class Controller {
        # Class commands the instances of a single class.
        # These are:
        #       instance
        #       table
        #       allocate
    }

    # ...
    # and so on, giving the population of the domain
}
----
==============


// vim:syntax=asciidoc:

Changes to micca/doc/howto/dynamics.txt.

1
2
3
4
5


6
7






































































































































































8
9
10
11
12
13
14
..
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
...
104
105
106
107
108
109
110


111
112
113
114
115
116
117
...
143
144
145
146
147
148
149


150
151
152
153
154
155
156
...
158
159
160
161
162
163
164
165

166
167
168
169
170
171
172
...
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
...
322
323
324
325
326
327
328

329
330
331
332
333
334
335
...
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
...
489
490
491
492
493
494
495
496





497
498
499
500
501
502
503
...
533
534
535
536
537
538
539


540
541
542
543
544
545
546
547
548
549
550

551
552
553
554
555
556
557
...
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
== Translating dynamics

The second facet of the model to translate is that of the dynamics.
Translating the dynamics of the model requires the least amount of
transformation of the three model facets.


The semantics of the Moore state models used in XUML are directly
mapped to `micca` commands.







































































































































































Note at this stage we are _not_ translating the action language of the
activities associated with any state model.
State model activities should be left empty at this time so we can
focus on getting the correct structure of states and transitions.
We discuss the translation of the processing in a subsequent section.

................................................................................

. The states must be defined.
    The code to execute when the state is entered is part of that definition,
    however we defer that until the skeleton of the state model is
    constructed.
. The transitions between states must be associated to the events which
    cause those transitions.
    When an event is recieved, it causes:
    .. A transition to a state (possibly the same state receiving the event).
    .. Is ignored. This is given the symbol, *IG*.
    .. Is an error conditions because it is logically impossible for
        the event to be received in the state, _i.e._ it can't happen.
        This is given the symbol *CH*.

In this section,
we do not discuss translating the code for state activities.
We consider that in the next section.

=== Defining states

To specify a state,
`micca` uses the `state` command.

Consider a simple light bulb.

................................................................................

=== Defining transitions

The other aspect of a state model translation is to specify all the state
transitions.
The starting point for translating the state transitions is,
naturally enough, the transition matrix of each state model.


Consider the transition matrix for our simple light bulb model.
Each state has a row in the matrix.
Each event has a column in the matrix.

[options="header",cols="3*^",title="Light Bulb State Transitions",width="50%"]
|=====
|State / Event  |Turn off       |Turn on
................................................................................
[NOTE]
Note that `micca` does not have any ordering requirements on the
`state` or `transition` commands.
You can put all the `transition` command first or mix them around
in any way you wish.
One common organization is to list the _outgoing_ transitions
for a state immediately after the `state` command defining the state.



=== Default transitions

A state model diagram typically only shows transitions from one state
to another.
It does not show ignored (IG) or can't happen (CH) pseudo-transitions.
In our translation of the example,
................................................................................
This can be tedious if there are a lot of these types of transitions
to encode.
So, `micca` allows you to set a default transition.
Any transition _not_ mentioned in a `transition` command is assigned
the default transition.

Normally, the default transition is *CH* (for some very good reasons
a default of *CH* catches many errors).

However,
some state models, assigners in particular, 
ignore most events that do not cause an explicit transition to a state.
Our light bulb example also ignores events.
To change the default transition,
use the `defaulttrans` command.
Our light bulb example might have been written as:
................................................................................
        # code to execute when the On state is entered.
    }
    transition On - Turn_off -> Off
}
----
<1> Note the spaces around the `-` and `->` characters.
This is _syntactic sugar_ intended to be mnemonic of the transition
and is required.

Some find this manner of specifying the state model clearer.
Note also the `defaulttrans` command may appear anywhere and need not
be the first command in the state model definition.

=== Initial state

................................................................................
by the run-time code.
To indicate a final state,
`micca` uses the `final` command.

----
statemodel {
    # state and transition definitions


    final Finished
}
----

It is possible to have multiple final states.
It is also possible to use the `final` command several times or
................................................................................
modeled by state models.
We do not discuss all the aspects of polymorphic events here since
our concern is translation.

The usual convention in model diagrams marks polymorphic events by
pre-pending an asterisk, _i.e._ **Run*.
This is done as an aid in keeping track of things in the model.
`Micca` does not use such conventions.

`Micca` requires that a polymorphic event be defined as part of the
class specification for the superclass.
The event can be given any name
(as long as it can be turned into a ``C'' identifier).
When an event by the same name is consumed
(_i.e._ appears in a transition statement)
................................................................................
    # other commands to specify a Torpedo
}
----

Defining a polymorphic event is similar in syntax to defining an ordinary
event.
The main difference is that the polymorphic event is defined as part of
the `class` command script and _not_ as part of the `statemodel`.





A child class consumes the polymorphic event,
when an event of the same name as the polymorphic event is used in a
`transition` command within a `statemodel` script.

`Micca` understands that in multi-level generalizations,
polymorphic events not consumed by intermediate level classes are
deferred to child classes.
................................................................................
There is nothing particularly special about the *Go* event in this example.
It is signaled to a newly created instance when an asynchronous
instance creation is requested in an activity.
The name of the creation event must be supplied as part of
the process of asynchronously creating an instance.
The event may have parameters or not depending upon what the analytical
model has specified.



=== Assigner state models [[assigner-state-models]]

The nature of some associations between classes is competitive.
The concurrency rules of XUML imply that instances of the relationship
must be created by serializing the actions involved.
This is accomplished by associating a state model to the relationship
itself and those state models are called _assigner_ state models.
The archetypal example for assigner state models is the assignment
of store clerks to service customers:



["plantuml",title="Clerk / Customer Association"]
----
@startuml
skinparam class {
    BackgroundColor yellow
    BorderColor black
................................................................................
Clerk "0..1" - "0..1" Customer
(Clerk, Customer) .. Service : R16
@enduml
----

Since the state model is bound to the association,
it is specified as part of the association definition.
For the previous example:

----
domain operations {
    # commands to specify domain characteristics
    # ...

    association R16 -associator Service Clerk 0..1-0..1 Customer {





>
>
|

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







|






<
<
<
<







 







>
>







 







>
>







 







|
>







 







|







 







>







 







|







 







|
>
>
>
>
>







 







>
>




|






>







 







|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
...
202
203
204
205
206
207
208
209
210
211
212
213
214
215




216
217
218
219
220
221
222
...
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
...
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
...
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
...
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
...
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
...
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
...
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
...
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
...
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
== Translating dynamics

The second facet of the model to translate is that of the dynamics.
Translating the dynamics of the model requires the least amount of
transformation of the three model facets.
The semantics of the
https://en.wikipedia.org/wiki/Moore_machine[Moore]
state models used in XUML are directly
mapped to `micca` commands.

=== How execution sequencing works

Just as in translating data,
it is helpful to understand the platform specifics of execution
sequencing when constructing the translation of the state models.
In this section we give a overview of the major concepts in how
`micca` sequences execution.
This section is not a complete description of the execution run-time.
That may be found in the `micca`
http://repos.modelrealization.com/cgi-bin/fossil/mrtools/doc/trunk/micca/doc/micca.pdf[literate program]
document.
Here we only present the concepts that help in understanding the
intent of the translation commands.

Broadly speaking,
there are three forms of execution sequencing that happen when
a `micca` translated model runs.

Synchronous execution::
    A domain activity may invoke an ordinary ``C'' function.
    Control is transferred to the function and when it returns
    execution continues where it left off.
    Synchronous execution is the usual, familiar, sequential flow of control.
    We don't discuss this any further since it is fully supported
    by ``C'' language primitives.
    When invoking a function in ``C'',
    the compiler arranges to pass control to the function and arranges
    for the function to return back to the subsequent code.
    The `micca` run-time is not involved.
Asynchronous execution::
    A domain activity executes until it needs to wait on other
    actions in the domain.
    Other actions use _events_ to signal synchronization points
    and these signals can cause an activity to resume executing
    in a particular location.
    Asynchronous execution is accomplished by a state machine dispatch
    mechanism.
    We explain the details of how the `micca` run-time performs
    state machine dispatch in the following section.
Preemptive execution::
    During the execution of any domain activity,
    it is possible to suspend the execution of the activity, preemptively,
    run a body of code, and return to the preempted activity to continue.
    Preemptive execution is non-deterministic in that you don't
    know when it may happen and have only limited means to control
    periods of time when it is _not_ allowed to happen.
    Preemptive execution corresponds to _interrupts_ when running natively
    on a computer or _signals_ footnote:[The POSIX version of the
    `micca` run-time treats the change of state of a file descriptor
    in the same manner as signals.]
    in a POSIX environment.
    The `micca` run-time provides a means to synchronize preemptive
    execution with the other forms.
    We discuss this aspect when we take up bridging of domains.

The `micca` run-time supports a single thread of execution on which
both synchronous and asynchronous domain activities execute.
The nature of the execution architecture is completely event-driven.
Any domain activity that blocks waiting for some condition,
prevents all but preemptive execution from running.
This approach is well suited to applications which react to external
conditions by performing a time-bound computation.
Clearly,
there are certain types of applications for which this execution
model is not well suited.
The `micca` run-time is not _universal_ in the sense of applicable
to every conceivable application,
but an event-driven, reactive execution model accomodates a broad
class of applications well.

=== How state machine dispatch works

The execution rules of XUML require that domain activities exhibit
_run-to-completion_ semantics.
This means the execution of an activity _appears_ as if it
runs to its natural end without being preempted by other activities
that may also be running.
When state models interact,
they _signal_ an _event_ to indicate the need to synchronize with
another condition.
Consequently when an activity signals an event,
it continues to run and the act of signaling has no perceived effect on current
execution of the activity.
Since `micca` only has a single execution context on which anything
runs,
there is no real parallel execution that must accounted for.
The `micca` run-time uses the conventional mechanism of _queuing_ signaled
events to allow the signaling activity to continue to its completion.
Only after an activity which signals an event completes is an
event considered for dispatch.

Event dispatch follows Moore semantics.
A transition table is used as a transfer function.
The current state of the instance receiving the event and the event itself
determine the new state into which the receiving instance is placed.
Upon entry into a state,
any activity associated with the state is executed.
The transition table is a matrix containing one row for each
state of the state model and one column for each event to which
the state model responds.
The same transition table is used for all instances of a given class
since all instances of a class exhibit the same behavior.
The entry at the intersection of state rows and event columns is the
new state into which the transition is made.
XUML semantics also support the notion that an event can be ignored
or is an error condition and these situations are also encoded
in the transition matrix cell.

The `micca` run-time distinguishes between two contexts in which
an event may be signaled.

. The event is signaled from within a state activity, _i.e._ one
    state machine is signaling and event to another state machine
    (potentially signaling an event to itself).
. The event is signaled outside a state activity either as a signal
    from outside the domain or as a result of requesting the system
    to signal the event at some future time (a _delayed_ signal).

This distinction defines the concept of a _thread of control_ as follows:

* An event signaled from outside the domain starts a thread of control.
* The thread of control continues until all the events (if any)
  signaled by state activities initiated by the thread of control
  are delivered.
* After all the events precipitated by the thread of control event
  are dispatched,
  the next thread of control event is considered.

So, the `micca` run-time actually as two event queues.
One queue is used to store events that come from outside of a state
machine context and start a thread of control
The other queue is used to store events that arise during the
execution of a single thread of control.

All the effects of a signaled event which starts a thread of control
are realized before starting another thread of control.
This is important because at the end of each thread of control,
the `micca` run-time will check the referential integrity
of the data model.
The associations and generalizations defined by the class model
and encoded in the data translation define a set of constraints
on whether and how many class instances are related to each other.
Any activity that either creates or deletes instances or
otherwise rearranges the related instances must insure that
the data model is consistent with the constraints implied by the
associations and generalizations of the class model.
This means that any activity that modifies relationships must:

.. perform any compensitory action required to make the data model consistent
    within in the same activity that modified the relationship instances, or
.. signal an event that when dispatched will eventually cause some state
    activity to run which makes the data model consistent before the
    thread of control ends.

The archetypical example of data consistency is two classes which
participate in a one-to-one unconditional association.
Creating an instance of one class necessarily implies that an instance of
the other class must also be created.
The creation of the second class instance is the compensitory action
required to make the data model consistent.
That instance creation may happen in the same state activity or an event
may be signaled which results in another state activity eventually creating the
required class instance.

=== Translating state models

Note at this stage we are _not_ translating the action language of the
activities associated with any state model.
State model activities should be left empty at this time so we can
focus on getting the correct structure of states and transitions.
We discuss the translation of the processing in a subsequent section.

................................................................................

. The states must be defined.
    The code to execute when the state is entered is part of that definition,
    however we defer that until the skeleton of the state model is
    constructed.
. The transitions between states must be associated to the events which
    cause those transitions.
    When an event is received, it causes:
    .. A transition to a state (possibly the same state receiving the event).
    .. Is ignored. This is given the symbol, *IG*.
    .. Is an error conditions because it is logically impossible for
        the event to be received in the state, _i.e._ it can't happen.
        This is given the symbol *CH*.





=== Defining states

To specify a state,
`micca` uses the `state` command.

Consider a simple light bulb.

................................................................................

=== Defining transitions

The other aspect of a state model translation is to specify all the state
transitions.
The starting point for translating the state transitions is,
naturally enough, the transition matrix of each state model.
The analytical model must provide a complete state transition
matrix in addition to the state model diagram for each state model.
Consider the transition matrix for our simple light bulb model.
Each state has a row in the matrix.
Each event has a column in the matrix.

[options="header",cols="3*^",title="Light Bulb State Transitions",width="50%"]
|=====
|State / Event  |Turn off       |Turn on
................................................................................
[NOTE]
Note that `micca` does not have any ordering requirements on the
`state` or `transition` commands.
You can put all the `transition` command first or mix them around
in any way you wish.
One common organization is to list the _outgoing_ transitions
for a state immediately after the `state` command defining the state.
Project should decide their own conventions for specifying
the states and transitions.

=== Default transitions

A state model diagram typically only shows transitions from one state
to another.
It does not show ignored (IG) or can't happen (CH) pseudo-transitions.
In our translation of the example,
................................................................................
This can be tedious if there are a lot of these types of transitions
to encode.
So, `micca` allows you to set a default transition.
Any transition _not_ mentioned in a `transition` command is assigned
the default transition.

Normally, the default transition is *CH* (for some very good reasons
a default of *CH* catches many errors and generally the default
transition should be kept as *CH*).
However,
some state models, assigners in particular, 
ignore most events that do not cause an explicit transition to a state.
Our light bulb example also ignores events.
To change the default transition,
use the `defaulttrans` command.
Our light bulb example might have been written as:
................................................................................
        # code to execute when the On state is entered.
    }
    transition On - Turn_off -> Off
}
----
<1> Note the spaces around the `-` and `->` characters.
This is _syntactic sugar_ intended to be mnemonic of the transition
and its presence is required.

Some find this manner of specifying the state model clearer.
Note also the `defaulttrans` command may appear anywhere and need not
be the first command in the state model definition.

=== Initial state

................................................................................
by the run-time code.
To indicate a final state,
`micca` uses the `final` command.

----
statemodel {
    # state and transition definitions
    # ...

    final Finished
}
----

It is possible to have multiple final states.
It is also possible to use the `final` command several times or
................................................................................
modeled by state models.
We do not discuss all the aspects of polymorphic events here since
our concern is translation.

The usual convention in model diagrams marks polymorphic events by
pre-pending an asterisk, _i.e._ **Run*.
This is done as an aid in keeping track of things in the model.
`Micca` does _not_ use such conventions.

`Micca` requires that a polymorphic event be defined as part of the
class specification for the superclass.
The event can be given any name
(as long as it can be turned into a ``C'' identifier).
When an event by the same name is consumed
(_i.e._ appears in a transition statement)
................................................................................
    # other commands to specify a Torpedo
}
----

Defining a polymorphic event is similar in syntax to defining an ordinary
event.
The main difference is that the polymorphic event is defined as part of
the `class` command script and _not_ as part of the
`statemodel` footnote:[Polymorphic commands have no effect on any
state behavior of the superclass.
The superclass may have its own state model which is unaffected by
any polymorphic events defined in the superclass.
Polymorphic events only affect subclass behavior.].
A child class consumes the polymorphic event,
when an event of the same name as the polymorphic event is used in a
`transition` command within a `statemodel` script.

`Micca` understands that in multi-level generalizations,
polymorphic events not consumed by intermediate level classes are
deferred to child classes.
................................................................................
There is nothing particularly special about the *Go* event in this example.
It is signaled to a newly created instance when an asynchronous
instance creation is requested in an activity.
The name of the creation event must be supplied as part of
the process of asynchronously creating an instance.
The event may have parameters or not depending upon what the analytical
model has specified.
It is also possible that the *Go* event is used in transitions other
than the one from the pseudo-initial state.

=== Assigner state models [[assigner-state-models]]

The nature of some associations between classes is competitive.
The concurrency rules of XUML imply that instances of a competing relationship
must be created by serializing the actions involved.
This is accomplished by associating a state model to the relationship
itself and those state models are called _assigner_ state models.
The archetypal example for assigner state models is the assignment
of store clerks to service customers:

Consider the following model fragment.

["plantuml",title="Clerk / Customer Association"]
----
@startuml
skinparam class {
    BackgroundColor yellow
    BorderColor black
................................................................................
Clerk "0..1" - "0..1" Customer
(Clerk, Customer) .. Service : R16
@enduml
----

Since the state model is bound to the association,
it is specified as part of the association definition.
For this example:

----
domain operations {
    # commands to specify domain characteristics
    # ...

    association R16 -associator Service Clerk 0..1-0..1 Customer {

Changes to micca/doc/howto/howto.txt.

7
8
9
10
11
12
13


14
15
16
17
18
19
20
21
22
include::syntax.txt[]

include::data.txt[]

include::dynamics.txt[]

include::processing.txt[]



include::bridge.txt[]

include::codeorg.txt[]

include::bibliography.txt[]


// vim:syntax=asciidoc:







>
>









7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
include::syntax.txt[]

include::data.txt[]

include::dynamics.txt[]

include::processing.txt[]

include::lesser.txt[]

include::bridge.txt[]

include::codeorg.txt[]

include::bibliography.txt[]


// vim:syntax=asciidoc:

Changes to micca/doc/howto/intro.txt.

197
198
199
200
201
202
203




204
205
206
207
208
209
210
...
214
215
216
217
218
219
220


221
222
223
224
225
226
227
...
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
This seems to be a property of any collection of logic when exceeding a certain
size.footnote::[which size is almost never exceeded by the
simple examples usually presented]

Domain models are precise and detailed and therefore don't have _fuzzy_ parts
that are stubbed out or left open for interpretation or dangling for future
elaboration.




An incomplete or vague model is simply not sufficient to perform a translation
which itself is supposed to be _derived_ from the model.
We consider the following a _minimal_ set of deliverables that
are required before translation can begin.[[model-contents]]

* A class model of the domain data. The class model must contain:
  - A UML class diagram (in accordance with XUML usage of class
................................................................................
    aspect of creating the class model and the presence of the
    descriptions indicates that the analyst has thoroughly considered
    the implications of the model.
  - A description of each model-level data type employed in the
    class model.
    The description must define the set of values (either by formula
    or enumeration) that constitute the data type.


* A state model for each class that has non-trivial lifecycle behavior.
  The state models must contain:
  - A UML state diagram (in accordance with XUML usage).
    The diagram must show the initial state and any final states.
  - A state transition matrix in which every possible transition
    is defined.
    Every transition not shown on the state model diagram must be
................................................................................
anything from the logic of the domain model.
The intent of translation is only to add the necessary software
technology to make the domain run on the intended platform.
Consequently,
a Translator tends to pay little attention to the details of
what a domain actually accomplishes.
It is a somewhat rote undertaking.
Rather the focus is on formulating clear and concise program
statements to reflect the actions of the model.
Translation concerns are those of the computing platform and not
those of the subject matter of the domain.

As described previously,
the purpose of this document is to describe a single step in the
overall workflow, namely,







>
>
>
>







 







>
>







 







|







197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
...
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
...
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
This seems to be a property of any collection of logic when exceeding a certain
size.footnote::[which size is almost never exceeded by the
simple examples usually presented]

Domain models are precise and detailed and therefore don't have _fuzzy_ parts
that are stubbed out or left open for interpretation or dangling for future
elaboration.
We eschew the concept of elaboration,
preferring to view translation as a discontinuous step of taking a logical
statement of a problem and applying computing technology to achieve an
executable solution.
An incomplete or vague model is simply not sufficient to perform a translation
which itself is supposed to be _derived_ from the model.
We consider the following a _minimal_ set of deliverables that
are required before translation can begin.[[model-contents]]

* A class model of the domain data. The class model must contain:
  - A UML class diagram (in accordance with XUML usage of class
................................................................................
    aspect of creating the class model and the presence of the
    descriptions indicates that the analyst has thoroughly considered
    the implications of the model.
  - A description of each model-level data type employed in the
    class model.
    The description must define the set of values (either by formula
    or enumeration) that constitute the data type.
    Data types should also define the set of operations allowed upon
    them if it is not clear from the context.
* A state model for each class that has non-trivial lifecycle behavior.
  The state models must contain:
  - A UML state diagram (in accordance with XUML usage).
    The diagram must show the initial state and any final states.
  - A state transition matrix in which every possible transition
    is defined.
    Every transition not shown on the state model diagram must be
................................................................................
anything from the logic of the domain model.
The intent of translation is only to add the necessary software
technology to make the domain run on the intended platform.
Consequently,
a Translator tends to pay little attention to the details of
what a domain actually accomplishes.
It is a somewhat rote undertaking.
Rather, a Translator's focus is on formulating clear and concise program
statements to reflect the actions of the model.
Translation concerns are those of the computing platform and not
those of the subject matter of the domain.

As described previously,
the purpose of this document is to describe a single step in the
overall workflow, namely,

Added micca/doc/howto/lesser.txt.





>
>
1
2
== Lesser used translation features
Lesser used translation features

Changes to micca/doc/howto/marking.txt.

150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
...
167
168
169
170
171
172
173
174

175
176
177
178
179
180
181


182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
...
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
...
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
...
325
326
327
328
329
330
331










332
333
334
335
336




337
338
339
340





























341
342
343
344
345
346
347
348
349
350
351
352
353


354
355
356

357










358
* Each event signaled.
* Each polymorphic event signaled.
* Any states, other than final states, that have no outgoing transitions.
* Any states, other than an inital state, that have no incoming transitions.

=== Marking mechanics

The following is the suggested way to obtain and record the model metatdata
is:

* Start with a clean printout of the class diagram of the model on the
  largest size sheet of paper that can be conveniently obtained.
  Class diagrams for a cleanly presented model should be partitioned
  into smaller subsystems if the number of classes in the domain
  does not fit on readily available paper sizes.
................................................................................
* Also obtain clean printouts of the state model diagrams for each
  class which has a lifecycle state model.
* Read the action language or data flow diagrams of every processing
  activity in the model.
  This includes the state activites, domain operations and instance-based
  operations.
* While reading the model activities,
  annotate the class diagram with the information previously presented.

  For example,
  when action language statement reads an attribute, place an *R* next to the
  attribute's name.
  Similarly, attribute updates can be marked with a *U* or *W* character.
  The direction of relationship traversal can be annotated as an
  arrow pointing in the direction of the navigation and parallel to the
  relationship line on the class diagram.



The precise details of the notation used for the marking is not as important
as insuring that the previously mentioned information is gathered
and clearly indicated.
A project may choose to standarize the notation.
Do not hesitate to make notes on the diagrams regarding the
behavior implied by the activity processing.
The results of this model marking analysis directly feeds the next steps in the
translation process.

=== Evaluating the marking

After the marking is completed,
it should be evaluated for the following situations
The results of the evaluation should be reported back to the
analyst for the domain.

==== Evaluating attributes

Class attributes play one or more roles in the abstraction of a class.
The roles of an attribute may be broadly classified as:
................................................................................
    no two instances have the same values for both *Manufacturer Name*
    and *Model Name*.
+
Sometimes identifying attributes carry semantically meaningful
information, such as the previous example.
Some identifying attributes are system generated and have no
intrinsic semantic meaning.
The distinction is important in that the translation mechanisms
have to create system generated identifying attribute values.
Identifying attribute values that are semantically meaningful
usually are supplied from outside of the domain.
A fundamental distinction between the two types of identifiers also
relates to where the responsibility for insuring uniqueness lies.

Referential attributes::
    Referential attributes are those attributes which characterize the
    relationships between class instances.
    The real-world associations between classes are formalized by
    a relationship, either an association or a generalization.
................................................................................
    This is an analysis error.
    The only way in XUML to change an instance is to delete it
    and then create a new one with different identifying attribute
    values.
Identifying attributes that are read::
    We make note of identifying attributes that are read and treated
    as descriptive attributes because it will have an impact on
    specifying the platform specifics required for translation.

===== Evaluating referential attributes

For attributes which have a referential role,
the following situations should be noted.

Referential attributes that are written::
................................................................................
    instances and those must be used to change how instances are related.
Referential attributes that are read::
    If an attibute serves both referential and descriptive roles,
    domain activities may read the referential attribute.
    We make specific note this circumstance as it must be accounted for
    in the translation.











==== Evaluating relationships

Relationships that are never navigated::
    Relationships that are never navigated need not be translated and
    should be noted to the domain analyst as a potential error.




Relationships with a constant number of instances::
    Relationships that do not change either in number or in the
    participants are deemed _static_.
    This property allows for some optimizations in the translation.






























==== Evaluating state models

Events that are never signaled::
    Events that are never signaled are an analysis error.
States with no outgoing transitions::
    States with no outgoing transitions are terminal states,
    _i.e._ there is no way to escape the state.
    This may or may not be an analysis error, but its existance should
    be noted.
States with no incoming transitions::
    States with no incoming transitions cannot be reached unless
    the class instances is created in that state.


    This may or may not be an analysis error, and it should be noted to the
    analyst.













// vim:syntax=asciidoc:







|







 







|
>







>
>













|







 







|
|


|







 







|







 







>
>
>
>
>
>
>
>
>
>





>
>
>
>




>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>













>
>



>

>
>
>
>
>
>
>
>
>
>

150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
...
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
...
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
...
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
...
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
* Each event signaled.
* Each polymorphic event signaled.
* Any states, other than final states, that have no outgoing transitions.
* Any states, other than an inital state, that have no incoming transitions.

=== Marking mechanics

The following is the suggested way to obtain and record the model metadata
is:

* Start with a clean printout of the class diagram of the model on the
  largest size sheet of paper that can be conveniently obtained.
  Class diagrams for a cleanly presented model should be partitioned
  into smaller subsystems if the number of classes in the domain
  does not fit on readily available paper sizes.
................................................................................
* Also obtain clean printouts of the state model diagrams for each
  class which has a lifecycle state model.
* Read the action language or data flow diagrams of every processing
  activity in the model.
  This includes the state activites, domain operations and instance-based
  operations.
* While reading the model activities,
  annotate the class and state model diagrams with the information previously
  presented.
  For example,
  when action language statement reads an attribute, place an *R* next to the
  attribute's name.
  Similarly, attribute updates can be marked with a *U* or *W* character.
  The direction of relationship traversal can be annotated as an
  arrow pointing in the direction of the navigation and parallel to the
  relationship line on the class diagram.
  A tick mark next to an event name in a transition matrix can show
  that the event was signaled by some state activity.

The precise details of the notation used for the marking is not as important
as insuring that the previously mentioned information is gathered
and clearly indicated.
A project may choose to standarize the notation.
Do not hesitate to make notes on the diagrams regarding the
behavior implied by the activity processing.
The results of this model marking analysis directly feeds the next steps in the
translation process.

=== Evaluating the marking

After the marking is completed,
it should be evaluated for the following situations.
The results of the evaluation should be reported back to the
analyst for the domain.

==== Evaluating attributes

Class attributes play one or more roles in the abstraction of a class.
The roles of an attribute may be broadly classified as:
................................................................................
    no two instances have the same values for both *Manufacturer Name*
    and *Model Name*.
+
Sometimes identifying attributes carry semantically meaningful
information, such as the previous example.
Some identifying attributes are system generated and have no
intrinsic semantic meaning.
The distinction is important in that the translation mechanism
must create system generated identifying attribute values.
Identifying attribute values that are semantically meaningful
usually are supplied from outside of the domain.
An important distinction between the two types of identifiers
relates to where the responsibility for insuring uniqueness lies.

Referential attributes::
    Referential attributes are those attributes which characterize the
    relationships between class instances.
    The real-world associations between classes are formalized by
    a relationship, either an association or a generalization.
................................................................................
    This is an analysis error.
    The only way in XUML to change an instance is to delete it
    and then create a new one with different identifying attribute
    values.
Identifying attributes that are read::
    We make note of identifying attributes that are read and treated
    as descriptive attributes because it will have an impact on
    how the attribute is treated for translation.

===== Evaluating referential attributes

For attributes which have a referential role,
the following situations should be noted.

Referential attributes that are written::
................................................................................
    instances and those must be used to change how instances are related.
Referential attributes that are read::
    If an attibute serves both referential and descriptive roles,
    domain activities may read the referential attribute.
    We make specific note this circumstance as it must be accounted for
    in the translation.

==== Evaluating instance creation

Attributes for instance creation::
    `Micca` insists that the value of all attributes and all related
    class instances be available at instance creation time.
    Each site of instance creation, either synchronous or asynchronous,
    must be evaluated to insure that a value is available for the
    attribute, the attribute has a default value or the attribute
    is a dependent attribute.

==== Evaluating relationships

Relationships that are never navigated::
    Relationships that are never navigated need not be translated and
    should be noted to the domain analyst as a potential error.
    It might be the case that the analyst has included a relationship
    in the model which will be used in a subsequent iteration.
    The relationship can be added easily when it is later used
    by some activity.
Relationships with a constant number of instances::
    Relationships that do not change either in number or in the
    participants are deemed _static_.
    This property allows for some optimizations in the translation.
    Note that for associations with an associative class, the number of
    instances of the relationship equals the number of instances of the
    associative class.
    For associations realized by referential attibutes in one of the
    participants,
    the number of instances of the relationship equals the number of instances
    of the class that contains the referential attributes.
    The number of instances of a generalization equals the number of instances
    of the class which serves as the superclass of the generalization.
Associations that are partial functions::
    Associations with multiplicity and conditionality of:
    .. 0..1 to 0..1
    .. 0..* to 0..1
    .. 1..* to 0..1

+
are partial functions and `micca` will insists that these relationships
have an association class.
If the analyst did not provide an association class for the association
then one must be constructed.
For relationships with many-to-many multiplicity,
the analyst is expected to provide an association class and it is
an analysis error if one has not been provided.
+
This particular discrepance arises from older formulations of XUML modeling
that allowed using *NULL* value or a _special_ value as a means of specifying
partial functions.
`Micca` does not use any construct that implies the existance of a *NULL*
value.

==== Evaluating state models

Events that are never signaled::
    Events that are never signaled are an analysis error.
States with no outgoing transitions::
    States with no outgoing transitions are terminal states,
    _i.e._ there is no way to escape the state.
    This may or may not be an analysis error, but its existance should
    be noted.
States with no incoming transitions::
    States with no incoming transitions cannot be reached unless
    the class instances is created in that state.
    Any activity specified for a state with on incoming transitions
    is never executed.
    This may or may not be an analysis error, and it should be noted to the
    analyst.

=== Marking summary

Marking the model as has been describe here is the first preparatory
step to translation.
The goal of model marking is to enumerate those aspects of the model
that are actually used by the domain activities when they execute.
Marking also provides a valuable check on the correctness of the
analytical models.
With the model marking in hand,
translation decisions about how to cast the model
semantics into platform specifics are easier to make.

// vim:syntax=asciidoc:

Changes to micca/doc/howto/processing.txt.

100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
...
122
123
124
125
126
127
128


129
130
131
132
133
134
135
...
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
...
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
...
254
255
256
257
258
259
260
261

262
263
264
265
266
267
268
269
270
271
272
library to perform that operation.
There is nothing mysterious about that code.
It is ordinary ``C'' code and can be viewed like any other ``C''
implementation.
The function to signal events is called `mrt_SignalEvent()` and it accepts
arguments required to accomplish the model level action of sending an event
signal to a class instance.
It is possible to write the ``C'' code that invokes `mrt_SignalEvent()`
directly, and that would cause the signal to be generated.

The difficulty of coding directly against the run-time library interfaces is:

. There is a large cognitive burden to understand the details of the
    run-time API.
. Direct coding against the run-time library API strongly couples the
    translation to the run-time interface and could prevent future changes
................................................................................
access to the platform specific model when the code generation happens.
Consequently,
error diagnosis is much improved.
If you attempt to signal an event to a class instance and that instance
does not have such an event,
`micca` is able to diagnose that condition and issue an appropriate error
message.



=== `Micca` embedded command language

An activity in a `micca` translation, _e.g._ a state activity,
appears as ordinary ``C'' code with other commands embedded into the code.
The commands are embedded by surrounding them with the `<%` and `%>`
characters.
................................................................................
    the necessary semicolon punctuation.
    Other embedded commands are intended to be used in expressions and
    so do not place semicolons in the output.
    The reference documentation for the embedded command language states
    which behavior each command has, but you will quickly know
    the difference by the intent of each embedded command.
. During the code generation, the embedded command is removed from the input
    and the results of its execution is placed in the output at the same
    location.
. Since it is unknown how many ``C'' statements a command may generate,
    all statements should be treated as _compound_ statements and surrounded
    by curly braces (as we did in the `if` test of the previous example).

==== Generated code

Most people who perform a model translation using `micca` are curious about
................................................................................
There are several points of interest:

. State activities are turned into ordinary ``C'' functions.
    Most names are made file static to avoid cluttering
    the global space of names and to lessen the chance of a name
    conflict.
    State activities to not return values.
    All of their side effects are recording in the class data.
. Each state activity function has an argument called, `self`, which
    is a reference to the class instance for which the action is
    being run.
. The contents of the state action is placed as a comment at the
    beginning of the function body.
. `MRT_INSTRUMENT_ENTRY` is a macro that can be used for logging
    and instrumentation output or it can be defined to be empty and
................................................................................
for `micca`.
Code generation test cases are
http://repos.modelrealization.com/cgi-bin/fossil/mrtools[available]
for those interested in
the precise details of how the generated output appears.

As we stated previously,
model actions are a mix of ordinary ``C'' code plus embedded commands

to perform model level operations.
In the end,
the result looks like ``C'' but with what can be imagined as
unusually looking function invocations to perform the model level
semantics.

The following sections group the embedded commands based on
model level components such as classes or relationships.
Embedded commands are presented, along with some example action language,
to show how the intent of the action language is rendered into
the embedded commands.







|
|







 







>
>







 







|
|







 







|







 







|
>
|


|







100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
...
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
...
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
...
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
...
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
library to perform that operation.
There is nothing mysterious about that code.
It is ordinary ``C'' code and can be viewed like any other ``C''
implementation.
The function to signal events is called `mrt_SignalEvent()` and it accepts
arguments required to accomplish the model level action of sending an event
signal to a class instance.
It is possible to translate the activity by writing the ``C'' code that invokes
`mrt_SignalEvent()` directly, and that would cause the signal to be generated.

The difficulty of coding directly against the run-time library interfaces is:

. There is a large cognitive burden to understand the details of the
    run-time API.
. Direct coding against the run-time library API strongly couples the
    translation to the run-time interface and could prevent future changes
................................................................................
access to the platform specific model when the code generation happens.
Consequently,
error diagnosis is much improved.
If you attempt to signal an event to a class instance and that instance
does not have such an event,
`micca` is able to diagnose that condition and issue an appropriate error
message.
This help detect errors earlier in the process rather than
relying on the ``C'' compiler.

=== `Micca` embedded command language

An activity in a `micca` translation, _e.g._ a state activity,
appears as ordinary ``C'' code with other commands embedded into the code.
The commands are embedded by surrounding them with the `<%` and `%>`
characters.
................................................................................
    the necessary semicolon punctuation.
    Other embedded commands are intended to be used in expressions and
    so do not place semicolons in the output.
    The reference documentation for the embedded command language states
    which behavior each command has, but you will quickly know
    the difference by the intent of each embedded command.
. During the code generation, the embedded command is removed from the input
    and the semantically equivalent ``C'' code is placed in the output at the
    same location.
. Since it is unknown how many ``C'' statements a command may generate,
    all statements should be treated as _compound_ statements and surrounded
    by curly braces (as we did in the `if` test of the previous example).

==== Generated code

Most people who perform a model translation using `micca` are curious about
................................................................................
There are several points of interest:

. State activities are turned into ordinary ``C'' functions.
    Most names are made file static to avoid cluttering
    the global space of names and to lessen the chance of a name
    conflict.
    State activities to not return values.
    All of their side effects are recorded in the class data.
. Each state activity function has an argument called, `self`, which
    is a reference to the class instance for which the action is
    being run.
. The contents of the state action is placed as a comment at the
    beginning of the function body.
. `MRT_INSTRUMENT_ENTRY` is a macro that can be used for logging
    and instrumentation output or it can be defined to be empty and
................................................................................
for `micca`.
Code generation test cases are
http://repos.modelrealization.com/cgi-bin/fossil/mrtools[available]
for those interested in
the precise details of how the generated output appears.

As we stated previously,
model actions are a mix of ordinary ``C'' code,
used for expression evaluation and flow of control,
plus embedded commands to perform model level operations.
In the end,
the result looks like ``C'' but with what can be imagined as
unusual looking function invocations to perform the model level
semantics.

The following sections group the embedded commands based on
model level components such as classes or relationships.
Embedded commands are presented, along with some example action language,
to show how the intent of the action language is rendered into
the embedded commands.

Changes to micca/doc/howto/syntax.txt.

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
..
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
...
187
188
189
190
191
192
193
194
195
196
197

198
199
200





201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
...
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
...
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
micca -doc
----

causes `micca` to place a copy of the man pages in a sub-directory of the
current directory called, `miccadoc` footnote:[The `micca` executable
contains a number of files that can be copied out.
This insures the files are consistent with the version of `micca`
you are running].
The man pages are in HTML which your favorite browser can render.
In this section,
we discuss some of the syntax of the DSL used to describe an XUML
domain.
This section is _not_ a detailed enumeration of the commands,
the man pages provide the ultimate reference for the DSL.
Rather,
................................................................................
hints for the `micca` DSL.

`Micca` is written in the
http://www.tcl-lang.org[Tcl]
programming language.
Tcl is a command-oriented language,
similar in some ways to a command shell language that you might use to run
programs from a terminal window.
The features of Tcl make it useful for creating domain specific
languages,
especially those that are intended to appear as declarative specifications.
In fact,
the DSL for `micca` is actually a Tcl script.
`Micca` arranges for the script to be executed in an environment
where when the _commands_ in the script are executed,
the platform specific description of an XUML domain is generated.
Fortunately,
little knowledge Tcl syntax is required to work with `micca` and
we cover the points that you need below.

Like many other command-oriented languages,
Tcl syntax is concerned with spliting up a command line into _words_.
Tcl semantics are entirely tied up in the execution of the commands.
Tcl syntax deals with the way a command is split up into words.
Word splitting is done based on whitespace.
................................................................................
}
----
==============


=== Line continuation

Command in Tcl are separated by either newline characters or
by semicolons.
Usually, a single logical command is simply placed on a line by itself.
If the command is longer than you want for a physical line,

then a logical command can be continued onto the next line by
ending the line with a backslash character (`\`).
The backslash character must be immediately followed by the newline





character for the line continuation to have affect.
The result is that the backslash character, newline character and
any leading whitespace on the following line are replaced with a single
space.

In the following example,
the `attribute` command is split over three lines, using two line
continuations.

.Line continuation example
==============
[source,tcl]
----
class Motor {
    attribute\
        Manufacturer int\
        Model int
}
----
................................................................................
Part of the specification of a domain includes ``C'' code for the
activities of the domain.
That ``C'' code is specified in the domain configuration and passed
along to the output and eventually to the ``C'' compiler.
Both Tcl and ``C'' treat some characters as special.
The double quotes character (`"`) and brackets (`[]`) have meaning
both for Tcl and for ``C''.
Since Tcl examines any text first,
if you want to pass quotes or brackets on to the ``C'' compiler,
they must be enclosed in braces.
For example,
if a class has an attribute that is a string,
it might be defined as:

.Special characters example
................................................................................
Note in this case,
we want to define a `Model` instance with the name, `"ar-27-np"`.
It is important that the quote characters get to the ``C'' compiler
since that has a specific meaning in declaring a string literal.
However,
double quotes are meaningful to `micca` and so it is necessary to
enclose the value of the `Model_Name` attribute in braces.
A good rule of thumb is to enclose in brackets anything you want to make sure
gets all the way through to the ``C'' compiler untouched.

=== Other Tcl commands

Since a `micca` description of an XUML domain is actually a Tcl script,
you do have the entire power of the Tcl language available when defining
a domain.
In practice,







|







 







|





|
|

<
|







 







|


|
>
|

|
>
>
>
>
>











<







 







|







 







|
|







11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
..
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

43
44
45
46
47
48
49
50
...
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216

217
218
219
220
221
222
223
...
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
...
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
micca -doc
----

causes `micca` to place a copy of the man pages in a sub-directory of the
current directory called, `miccadoc` footnote:[The `micca` executable
contains a number of files that can be copied out.
This insures the files are consistent with the version of `micca`
you are running.].
The man pages are in HTML which your favorite browser can render.
In this section,
we discuss some of the syntax of the DSL used to describe an XUML
domain.
This section is _not_ a detailed enumeration of the commands,
the man pages provide the ultimate reference for the DSL.
Rather,
................................................................................
hints for the `micca` DSL.

`Micca` is written in the
http://www.tcl-lang.org[Tcl]
programming language.
Tcl is a command-oriented language,
similar in some ways to a command shell language that you might use to run
programs from a command line terminal.
The features of Tcl make it useful for creating domain specific
languages,
especially those that are intended to appear as declarative specifications.
In fact,
the DSL for `micca` is actually a Tcl script.
`Micca` arranges for the script to be executed in an environment where,
when the _commands_ in the script are executed,
the platform specific description of an XUML domain is generated.

Little knowledge Tcl syntax is required to work with `micca` and
we cover the points that you need below.

Like many other command-oriented languages,
Tcl syntax is concerned with spliting up a command line into _words_.
Tcl semantics are entirely tied up in the execution of the commands.
Tcl syntax deals with the way a command is split up into words.
Word splitting is done based on whitespace.
................................................................................
}
----
==============


=== Line continuation

Commands in Tcl are separated by either newline characters or
by semicolons.
Usually, a single logical command is simply placed on a line by itself.
If the command is longer than you want for a physical line
or if you want a particular line layout for emphasis,
then a command line can be continued onto the next physical line by
ending the line with a backslash character (`\`).
The backslash character must be immediately followed by the
newlinefootnote:[We refer the the last character as the _newline_
character. Different environments have different notions of how
the end of an text record is encoded.
Tcl automatically takes these differences into account and we are safe
to think of text records as simply being newline terminated.]
character for the line continuation to have affect.
The result is that the backslash character, newline character and
any leading whitespace on the following line are replaced with a single
space.

In the following example,
the `attribute` command is split over three lines, using two line
continuations.

.Line continuation example
==============

----
class Motor {
    attribute\
        Manufacturer int\
        Model int
}
----
................................................................................
Part of the specification of a domain includes ``C'' code for the
activities of the domain.
That ``C'' code is specified in the domain configuration and passed
along to the output and eventually to the ``C'' compiler.
Both Tcl and ``C'' treat some characters as special.
The double quotes character (`"`) and brackets (`[]`) have meaning
both for Tcl and for ``C''.
Since `micca` examines any text first,
if you want to pass quotes or brackets on to the ``C'' compiler,
they must be enclosed in braces.
For example,
if a class has an attribute that is a string,
it might be defined as:

.Special characters example
................................................................................
Note in this case,
we want to define a `Model` instance with the name, `"ar-27-np"`.
It is important that the quote characters get to the ``C'' compiler
since that has a specific meaning in declaring a string literal.
However,
double quotes are meaningful to `micca` and so it is necessary to
enclose the value of the `Model_Name` attribute in braces.
A good rule of thumb is to enclose in braces anything you want to insure
is passed through untouched to the ``C'' compiler.

=== Other Tcl commands

Since a `micca` description of an XUML domain is actually a Tcl script,
you do have the entire power of the Tcl language available when defining
a domain.
In practice,