ALS Domains

Before jumping into the models, let’s take a look at the domains necessary to support the ALS, as shown in Figure 6-2.

Figure 6-2. ALS domain dependencies

• ❶ At the top level, we have the Lubrication domain. It is concerned with the primary purpose of our system, which is to manage the injectors to schedule cyclic lubrication. This domain is modeled.

• ❷ The Lubrication domain needs up-to-date pressure values and events announcing key pressure thresholds. It also needs a way to convert a modeled event such as “Turn injector on” into an appropriate signal or command to the injector solenoids. Signal I/O (SIO) provides this service as indicated by the dashed dependency arrow. The SIO domain is shown in Chapter 7.

• ❸ The Lubrication domain signals alarm conditions, but needs a way to manage systematic setting and clearing of alarms as well as management of alarm categories such as operator warnings, errors, and log items. The Alarms domain handles this job.

• ❹ The Lubrication domain needs to know when to activate and deactivate lubrication schedules. It also needs a way to signal completion of schedules and other events to a human operator. It uses the UI domain for this purpose.

• ❺ The Alarms domain needs to display alarms to a human operator and allow alarms to be cleared. It also uses the UI domain.

• ❻ All modeled domains are translated to run on the Model Execution domain and need its services to implement model-level actions.

• ❼ The Model Execution domain is coded in C. Yes, the C language is also a domain. This might seem strange at first, but C is its own distinct subject matter. It isn’t modeled in Executable UML, of course, but the C language is modeled to some degree as a grammar. The entire interface to the C domain is defined pre-runtime by writing a program. The more you think about it, the more you realize there isn’t anything special at all about a program language as a subject matter.

As you can see, this arrangement of domains creates a complete path from the application-level abstractions of the Lubrication domain through generic utility services, model execution, and ultimately, code. Each domain, modeled or not, represents a distinct subject matter. Note that domains yield a largely platform-independent partitioning. The underlying hardware, devices, and user-interface technology can change, but the subject matter organization remains intact. Contrast this with many traditional high-level software architecture diagrams, which are almost always platform specific.

Whether you view the domain interactions in a layering manner or as dependencies between domains, it is important to realize that neither view represents a functional partitioning of the system, also known as functional decomposition. Subject matter partitioning is based on cohesive classes and relationships without regard to specific functions. Each class model defines a vocabulary and rule set that defines the subject matter of a domain. Dividing a system by common data and rules is markedly different from dividing it by common functions. Domain partitioning is based on subject matter, and the analysis of the subject matter of a domain seeks to find a consistent set of abstractions directed to the role the domain plays in the overall system. The functionality of the system is manifested when the model executes, and any given functional feature of the system generally requires multiple domains, each to play its role. For the ALS, injecting lubricant involves both the Lubrication domain to determine the appropriate time and the SIO domain to actuate the hardware. Both domains use the Model Execution domain to interact and are ultimately coded in C.

In Chapter 8, we show how domain dependencies are specified and then implemented using pycca. For the remainder of this chapter, we examine the models in the Lubrication domain. Bridges to the SIO, Alarms, and UI domain are shown as we examine the state models and activities.

Lubrication Domain

We start by examining the Lubrication domain. This is the application level that addresses the primary business purpose of the system. All other domains are present to provide services directly or indirectly in support of the Lubrication domain’s needs. Because our purpose is to coordinate and manage lubricant injection, we would expect the application level to know about the injection equipment and the lubrication scheduling subject matter.

Lubrication Class Model

For a more readable illustration, we break the Lubrication class diagram into two adjacent pieces, Equipment and Schedule. This split is strictly for presentation purposes and has no implications on the model itself.

Figure 6-3 shows the equipment part of the class model, which focuses on physical components.

Figure 6-3. Lubrication equipment classes

Lubricant is delivered to some type of equipment. This could be anything from a robot, to a jet engine, to a heavy-lifting construction vehicle. From the perspective of the ALS, the function of the lubricated equipment is not relevant, so it is represented as generic “machinery.” The particular values established for the Lubrication Schedule and Injection Spec attributes are determined, in part, by the specific needs and function of the lubricated Machinery. But this model is not concerned with the specifics of the Machinery and leaves it to a human to define acceptable values for the attributes to meet those needs. Those attribute values appear in the initial instance population for the domain.

A Single Injection

We have enough of the model to consider the behavior of a single injection. To reduce the load on power and the local computer and network resources, an injector sits quietly until commanded. It does not even monitor internal pressure because it is unlikely that dangerous pressure will build up when the injector is inactive. Figure 6-4 shows a typical injection sequence.

Figure 6-4. Example good and bad injection sequences

The Wakeup command causes the injector to begin monitoring pressure for error-reporting reasons. Ideally, the pressure built up from the previous injection will have dissipated by now, but that is not always the case. If any high pressure is detected, we want to report a warning. Regardless of how much the pressure fluctuates, at most one warning should be issued.

This monitoring interval ends when the Start command arrives. Now it’s time to inject lubricant. To do this, the Injector Design.Min delivery pressure must be achieved and maintained for the Injector Design.Good injection duration. Upon success, a good injection is reported, and the injector goes inactive again. Otherwise, each time the pressure drops too low, it is necessary to wait until it builds up and try again. If a Stop command is received, it means that too much time has elapsed. A bad injection is logged, and the injector goes inactive.

Controlling Lubrication Cycles

Now that we have a model of the equipment, we need to consider the cyclic schedule by which the injectors are controlled. At its simplest, a cycle of injection repeats with a specified delay between injections. A period of time must also be specified to allow the injector to begin monitoring pressure. We can also specify whether the cycle should run for a default count or continuously until stopped manually. A maximum number of low-lube cycles that will be tolerated before shutting off lubrication is also part of the lubrication program. Figure 6-5 illustrates the typical cyclic control session.

Figure 6-5. A cyclic schedule of lubrication

With these concepts in mind, we can move on to the other half of thee Lubrication domain class model, which covers cyclic scheduling and control of injection. Figure 6-6 introduces two new classes to cover the scheduling requirements.

Figure 6-6. The lubrication cycle classes

Example Population

The scenario illustrated in Figure 6-1 is represented by the population shown in Figure 6-7.

Figure 6-7. Scenario’s initial instance population

Injector State Model

Figure 6-8 shows the top half of the Injector state model.

Figure 6-8. Injector state model excerpt: Sleeping to Active

• ❶ The Injector is in the SLEEPING state when it receives a Wakeup event, which will be sent from the Autocycle Session. The SIO domain is told to start monitoring sensor values for this Injector.

• ❷ In the MONITORING state, the Injector isn’t doing anything, because SIO is doing all the sensor detection work. But, from this state, we react to the Above dissipation pressure event supplied by the SIO domain when it detects that pressure has risen above the Injector Design.Max dissipation pressure.

• ❸ A Dissipation error should never be triggered more than once per cycle. To avoid raising multiple Dissipation error alarms, this state checks and sets the Injector.Dissipation error Boolean attribute value.

• ❹ When the Start event is received from the Autocycle Session, it is necessary to verify that the target Machinery is not locked out before proceeding to inject.

• ❺ Either a Lockout or a Stop event will put the Injector back to sleep.

Figure 6-9 shows the bottom half of the Injector state model.

Figure 6-9. Injector state model excerpt: Active to Sleeping

• ❶ The Injector solenoid is energized by sending the Inject signal to the SIO domain. From there, the Injector waits until the Injector Design.Min delivery pressure is attained.

• ❷ This event can be triggered as a result of the check in the BUILDING PRESSURE state or supplied by SIO when the condition is detected.

• ❸ When the pressure is high enough, lubrication is occurring. To get a good injection, this pressure must be maintained for the Injector Design.Good injection duration. This delayed event will be sent if all goes well while the Injector is in this state.

• ❹ Otherwise, SIO will send the Below inject pressure event, which leads to the Not enough pressure state, where the delayed event is canceled and the Reservoir is notified. From there, the Injector continues to wait for the pressure to build in the next state.

• ❺ If a long enough continuous injection is not achieved soon enough, the Autocycle Session will trigger the Stop event, which moves the Injector to the Quit low pressure injection state, possibly via the Cancel injection state, which cancels the Good injection delayed event.

• ❻ But if all goes well, the Good injection delayed event occurs, the solenoid is de-energized via SIO, and the Injector goes back to sleep.

Autocycle Session State Model

The Autocycle Session state model is a bit large to display here, so we walk through a summary without the action language visible. Figure 6-10 highlights the primary part of the life cycle. All of the grayed-out areas pertain to suspend/resume and deactivation behavior.

Figure 6-10. Autocycle Session state model overview

• ❶ Let’s start with an active Autocycle Session in the WAIT INTERVAL state. Here, we are waiting for the delay between cycles to expire. According to R2 on the class model, there will be one such session instance per Injector at all times.

• ❷ It is possible during this state that the session may be suspended. If this happens, we will go sit in the WAIT SUSPENDED state until resumed or deactivated. We must cancel the pending Get ready to lubricate delayed event, but not before saving the time remaining. Upon resuming, we will reschedule the Get ready to lubricate event for whatever time was remaining when we were suspended.

• ❸ The scheduled event occurs, and we advance to the MONITOR INTERVAL state. This is where we send the Wakeup event to our Injector so it begins monitoring pressure. We now schedule the delayed Lubricate event for the interval defined in our Lubrication Schedule and wait. If suspension occurs in this state, the logic is similar to the previous, except that the intermediate time waited will not be saved.

• ❹ The Lubricate event occurs, and we advance to the LUBE INTERVAL state. We send the Start event to our Injector and wait for one of two events. Either our Injector succeeds and it sends us the Good injection event, or too much time elapses and our scheduled Lube interval ended event occurs. The lubrication interval is determined by the value of Injector Design.Delivery window. In the first case, we can cancel the pending Lube interval ended event.

• ❺ In the time-out case, we advance to the LOW PRESSURE LUBRICATION state, where we tell the Injector to stop and increment the Failed cycles count. The Injector will respond with either a Good injection or a Low pressure injection event. The first one can happen if our Lube Interval times out at roughly the same instant that the Injector succeeds. Either way, it is critical that we wait here for confirmation that the Injector has stopped before proceeding so that we don’t lose synchronization with the Injector states.

• ❻ Either way, we advance to the Count cycle state, where the cycle is counted, and we check to see whether too many failed (low-lube) cycles have occurred. If so, we send the Too many low lube cycles event to our Reservoir so it can update its status. If we are operating in a continuous mode (nonstop repeating cycles), we go on to the next cycle. Otherwise, we see whether all requested cycles have been completed. If not, we also go on to the next cycle. Otherwise, with all requested cycles completed, we proceed to the NOT ACTIVE state.

• ❼ Now let’s say that the user decides to run a different Lubrication Schedule on this Injector. We will require that the session is in the NOT ACTIVE state for this request to be processed. (It’s ignored in all other states.) A Change Schedule event will be received with the name of the new Lubrication Schedule. This puts us in a deletion state, where we fire off the New session creation event just before the present instance disappears. Entry into the NOT ACTIVE state will always start by comparing the currently controlling Lubrication Schedule with the default on R1. If they don’t match, it means that a temporary schedule has been running. This will result in a New session creation back to the designated default Lubrication Schedule.

• ❽ A new instance of Autocycle Session is created with the input Schedule and Injector instances linked together and placed in the NOT ACTIVE state.

• ❾ The user issues an Activate event along with the desired mode (continuous or not) and a desired cycle count, which should be greater than zero if the continuous mode was not requested. We’ll verify that we aren’t locked out by our Machinery before proceeding. If not locked out, we’ll set the appropriate attributes and jump into the WAIT INTERVAL state. Note that a lockout that occurs in any other state will be detected by the Machinery that signals the Deactivate event to us.

Reservoir State Model

The Reservoir keeps track of its fill states to provide useful alarms to maintenance. During an ordinary fluid cycle, we start out with a normal level of fluid and then, driven by Injector events, descend through the states of LOW, VERY LOW, and EMPTY. Figure 6-11 shows the complete state model for the Reservoir class.

Figure 6-11. Reservoir state model diagram

Class Collaboration

The class collaboration diagram provides a nice overview of asynchronous (signal/event) and synchronous (methods invocation) interactions among state models within a domain. Class collaboration is not considered a separate facet of a domain model, because it can be derived from the contents of the three facets. But it is quite useful for devising a clean pattern of control within a domain (see Figure 14.8 on p. 245 of Executable UML: A Foundation for Model-Driven Architecture for a more complex example of control collaboration). Figure 6-12 shows how the classes of the Lubrication domain interact.

Figure 6-12. Class collaboration within the Lubrication domain

• ❶ These are events signaled in the Autocycle Session state model and detected in the Injector state model.

• ❷ This is a method defined on the Autocycle Session class. See Figure 6-13 for the method activities.

  

  Figure 6-13. Class method activities

• ❸ These are signals issued by Injector actions that are translated to corresponding SIO elements. The collaboration diagram makes no assumptions about the internal elements or interfaces of external domains beyond basic services provided. All we can tell from this diagram is that the events must be mapped to something in the SIO domain.

• ❹ These events occur in the Injector state model and must be triggered by SIO. The specific mechanisms within SIO that accomplish this are unknown in the Lubrication domain.

• ❺ Events from an instance to itself are not shown on the collaboration diagram. In this case, however, the event is sent from one instance of Autocycle Session to a different, newly created instance of the same class.

• ❻ A processed signal value in the SIO domain is mapped to the Pressure attribute across the domain boundary. This attribute is read-only within the Lubrication domain.

Class Method and Other Activities

Activities in a domain are not limited to those within states. A class method is an instance-based activity defined on a class. A domain operation is an activity defined as part of a domain interface. An external domain can invoke another domain’s operation to invoke a class method, for example, without interacting with any state machine.

Figure 6-13 shows the methods defined on each of the Lubrication domain classes.

State Tables

A table for each state model must be completed before we are ready for pycca. The tables are filled out during the modeling process, and they must be complete before we begin specifying the translation. Some drawing tools will do this work for you.

As the Autocycle Session and Injector state tables are rather large, we examine selected excerpts in this chapter. You can download the tables as fully commented spreadsheets from the book’s website if you wish to study them further.

Figure 6-14 is the first excerpt from the Injector state table.

Figure 6-14. Injector wait states

You may have noticed that some state names in the diagrams are named with all uppercase letters, whereas others are mixed case. This is an informal style for distinguishing wait and transitory states. A wait state is a state with an activity that does not send an event to itself to force a transition to another state. Instead, an instance that has completed its activity will either process a pending nonlocal event (an event not from this instance or delayed) or just wait for such an event to occur. Less formally, you can think of wait states as those in which an instance is waiting on a process to complete in the physical world, in some other domain or in some other instance, or for a delayed event to happen.

This means that all local events (nondelayed, self-to-self events) are marked Can’t Happen (CH) for wait states. That’s because a local event is generated in another state and processed by that same state, so it can’t happen here. So we can exclude all the local events, obtaining a smaller state table, and concentrate on nonlocal events.

Note the inclusion of the single delayed Good injection event. We can mark it as Can’t Happen in all states other than INJECTING AT PRESSURE if we can demonstrate that the event will either expire or be canceled before entering any of those other states. The format of the state table forces consideration of this possibility that is so easily overlooked otherwise!

Figure 6-15 shows the second state table excerpt for the Injector.

Figure 6-15. Injector transitory states

All states in the preceding table are transitory, which means that each state is exited on a local (nondelayed, self-to-self) event. A transitory state makes it possible to execute an activity on one transition path leading to a wait state, thus allowing the possibility of other transition paths to that same state where different or possibly no activities are performed. Often transitory states are used to perform if-then logic leading to alternate exit transitions.

Note that each transitory state responds only to an event it sends to itself, for the following reasons:

• The event will always be signaled by the state activity.

• Events that an instance signals to itself are dispatched before any other event.

This means that all other events may be marked CH, as shown in the preceding table excerpt. Because CH will be marked for all the nonlocal events shown in the first excerpt, there isn’t much insight to be gained from viewing that part of the table.

Figure 6-16 shows the wait state excerpt of the Autocycle Session class.

Figure 6-16. Autocycle Session wait states

The three delayed events are highlighted in the rightmost columns. Care has been taken to ensure that each delayed event is managed so that it does not occur in any state where it is not helpful.

Finally, Figure 6-17 shows the transitory states of the Autocycle Session class.

Figure 6-17. Autocycle Session transitory states

The Reservoir state table is small enough to show entirely in Figure 6-18.

Figure 6-18. Reservoir state table

Translating Association Classes

In Chapter 3, we discussed implementing associations by decomposing the link storage based on each direction of traversal of the association. This was illustrated in the case of a simple association in Figure 3-5.

Referring to Figure 6-6, R2 is formalized by the Autocycle Session class. Not only does this class have referential attributes to formalize R2, but it has descriptive attributes and a state model. Figure 6-19 shows how R2 is decomposed into two sides with the Autocycle Session class serving as an intermediary.

Figure 6-19. Decomposition with an association class

The R2 association has several interesting properties:

• Each Autocycle Session instance corresponds to an instance of the R2 association itself.

• Autocycle Session has two singular, unconditional references, one to Injector and one to Lubrication Schedule.

• The conditionality and multiplicity of the two sides are inverted in the decomposition. So Lubrication Schedule is related to Autocycle Session as “0..*” and Injector is related to Autocycle Session as 1. This is a consequence of the singular, unconditional reference from Autocycle Session to each participant of R2.

When translating the Lubrication domain, we use the decomposed form of R2 to determine how to set up the references. For the Autocycle Session class, this appears as follows:

class Autocycle_Session
    reference R2_INJ -> Injector
    reference R2_LBS -> Lubrication_Schedule

    # Other attributes and state model for Autocycle Session
End

Navigating the R2 association is also a two-step action. So, to navigate from an instance of Injector to an instance of Lubrication Schedule requires the following:

// Assuming inj holds are reference to an injector instance.

ClassRefVar(Lubrication_Schedule, sched) = inj->R2->R2_LBS ;

Navigating Associative Relationships

In the previous section, we showed a simple example of navigating an associative relationship. In that case, the multiplicity from the participating class to the association class was singular. In this section, we show a many-to-many associative relationship using a linked list to implement the linkage with the association class. Recall that in pycca, we treat associative relationships as being composed of two separate paths. Consequently, the translation of navigation for an associative relationship requires two parts. Consider the association shown in Figure 6-20.

Figure 6-20. Navigating an associative relationship

The decomposition of the associative relationship results in singular references to each participant in the association class:

class Track
    reference R2_Satellite -> Satellite
    reference R2_Station -> Station
end

The participants have their own links to the association class. Here we have chosen linked lists in anticipation that the association is dynamic:

class Satellite
    attribute (char const *ID)
    reference R2_Satellite ->>l Track
end

class Station
    attribute (char const *Name)
    reference R2_Station ->>l Track
end

Note that we have appended the class name to the reference names for each participant. We need to have different reference names because pycca will use those names directly in the generated structure, and we don’t want to have a naming conflict. We have chosen to append the class name because it is a convenient convention that lets us easily keep track of where the references originate or terminate.

Pycca will generate the following structures for the participants:

struct Satellite {
    struct mechinstance common_ ; // must be first !
    char const *ID ;
    rlink_t R2_Satellite ;
}

struct Station {
    struct mechinstance common_ ; // must be first !
    char const *Name ;
    rlink_t R2_Station ;
}

The preceding rlink_t R2_XX members serve as the terminus of a linked list and have the following structure:

typedef struct rlink {
    struct rlink *next ;
    struct rlink *prev ;
} rlink_t ;

The Track structure will have linked list pointers inserted into its structure for the linked list references defined by both the Satellite and Station classes:

struct Track {
    struct mechinstance common_ ; // must be first !
    struct Satellite *R2_Satellite ;
    struct Station *R2_Station ;
    rlink_t R2_Satellite__links ;   // ❶
    rlink_t R2_Station__links ;     // ❷
} ;

• ❶ Track instances are linked together from the Satellite side, and this list contains those instances of Track related to an instance of Satellite.

• ❷ Likewise for the Station instances. Note that the two linked lists plus the singular reference to the other participant gives us the many-to-many representation required by the association.

To navigate the association from Satellite to Station, we must first navigate to Track instances and from there follow the singular reference to a Station instance. Because the R2 association is many-to-many, we can have many Track instances related to a given Station instance, and so we need an iteration loop as we navigate from a Satellite instance to the related Track instances.

For a given instance of Satellite, to print the names of all the Stations, we would use the following code:

// ... assuming self is a reference to a Satellite instance ...

rlink_t *tracklink ;                                                                  // ❶

PYCCA_forAllLinkedInst(self, R2_Satellite, tracklink) {                               // ❷
    ClassRefVar(Track, tracki) = PYCCA_linkToInstRef(tracklink,Track, R2_Satellite) ; // ❸
    ClassRefVar(Station, stationi) = tracki->R2_Station ;                             // ❹
    printf("Satellite, %s, is being tracked by, %s
",
        self->ID, stationi->Name) ;
}

• ❶ When using linked lists, we need a linked list pointer variable to hold our place in the iteration.

• ❷ Pycca supplies a macro to set up the iteration loop.

• ❸ The pointers in the linked list from the Satellite instance point to the R2_Satellite__links member of the Track instance and not to the beginning of the Track instance. What we really want is the pointer to the beginning of the instance element, because that is what an instance reference truly is. Pycca supplies a macro to perform the address arithmetic to get us from the R2_Satellite__links member back to the Track instance reference. This is a common idiom when an object can be linked onto multiple linked lists.

• ❹ Finally, we can follow the singular link in the Station direction.

Creation Events

The two techniques for creating a class instance are synchronous creation and asynchronous creation. In synchronous creation, an activity makes a direct request to the MX runtime to create an instance, and that request is fulfilled immediately. The pycca macro that supports this is PYCCA_createInstance(). Class instances created this way are placed in their default initial state (if they have a state model), but the activity of the state is not executed. For example, all the instances that make up the initial instance population are considered to have been created in this way (there is no runtime cost for creating the initial instance population, because pycca arranges for the initial values to be placed in memory at compile time).

For the asynchronous case, instance creation is triggered by signaling a special creation event. The activity that signals this event continues to execute to completion (as per our usual execution rules). At some time in the future, when the event is dispatched, a new class instance is created, and the event is received by the newly created instance. From the newly created instance’s perspective, this is just a normal event. Consequently, the newly created instance makes a state transition, and the activity associated with the new state is executed (again per our usual execution rules of state machines).

From the modeling point of view, both techniques for instance creation have their uses. For the Lubrication domain, asynchronous creation is used to switch lubrication sessions. If you look back at Figure 6-10, at the top of the diagram the New session event causes a transition from a solid circle into the Creating state. The solid circle represents an initial pseudo-state, and the New session event is a creation event. The MX runtime will ensure that when the New session event is dispatched, an instance of Autocycle Session is created, it is placed in the initial pseudo-state, and the transition to the Creating state is taken, causing the activity to be executed.

Pycca has direct support for specifying a creation event. Next we show the required pycca statements. We have omitted much of the surrounding domain definition as well as the details of the Autocycle Session class definition to focus on the creation event:

# ... other parts of the Lube domain

class Autocycle_Session
    # ... attribute definitions, reference definitions, etc.

    machine
        default transition CH                            # ❶
        initial state Creating                           # ❷

        transition . - New_session -> Creating           # ❸

        # ... remaining parts of the state model definition
    end
end

# ... other parts of the Lube domain

• ❶ As usual, we specify a default transition of CH and the ignored transitions explicitly.

• ❷ Just because a state model has creation events does not mean it cannot be created synchronously. We have to specify the default initial state when instances of Autocycle Session are synchronously created.

• ❸ The . (period) character designates the initial pseudo-state. Here we say that the New_session event transitions from the initial pseudo-state to the Creating state, and that makes it a creation event.

It is possible for a state model to have multiple creation events, although that is not a common situation. It is also possible to signal New_session as an ordinary transitioning event, although that does not happen in the Autocycle Session state model. It is also possible to signal an ordinary transitioning event as a creation event. That results in a CH transition, and the pycca runtime will respond with a fatal error.

Signaling a creation event translates to a slightly different code sequence. In the Autocycle Session state model, it is the Spawn new session state that signals the New session event:

New session(  in.Schedule,
    Injector: /R2/Injector.ID ) -> Autocycle Session
 // This event will create, and be delivered to,
 // a  new  instance  of  Autocycle  Session  to  replace
 // this one being deleted.

The action language uses syntax to imply that the New session event is signaled directly to the Autocycle Session class. This is a convenient way to distinguish a creation event, as signals are normally directed at class instances. The translation of this action language follows:

# ... other parts of the Lube domain

class Autocycle_Session
    # ... Autocycle Session attribute definitions, reference definitions, etc.

    machine
        # ... other parts of the Autocycle Session state model definition

        state Spawn_new_session(
            char const *schedule)
        {
            MechEcb new_session =
                    PYCCA_newCreationEventForThisClass(New_session, self) ;            // ❶
            PYCCA_eventParam(new_session, Autocycle_Session, New_session, schedule) =
                    rcvd_evt->schedule ;                                               // ❷
            PYCCA_eventParam(new_session, Autocycle_Session, New_session, injector) =
                    PYCCA_idOfRef(Injector, self->R2_INJ) ;
            PYCCA_postEvent(new_session) ;                                             // ❸

            self->R2_INJ->R2 = NULL ;                                                  // ❹
        }
        # ... remaining parts of the state model definition
    end
end

# ... other parts of the Lube domain

• ❶ This allocates an ECB and marks the event as a creation event.

• ❷ Because the event carries parameters, we need to fill in the values. When there are no parameters, we use the pycca macro PYCCA_generateCreation() to handle the entire operation.

• ❸ Posting the event finishes the event-signaling process.

• ❹ We need to clean up a reference from the Injector instance because this Autocycle_Session instance is about to be deleted. The next section discusses this automatic instance deletion.

Asynchronous Instance Deletion

Just as there are two ways to create class instances, there are also two ways to delete them. An activity may synchronously delete an instance by using the PYCCA_destroyInstance() macro. When the underlying runtime function returns, the instance no longer exists.

Referring to Figure 6-10 again, we notice that there is a transition from Spawn new session to a small circle and that the transition has no event label. The small circle represents a final pseudo-state. The transition to a final pseudo-state designates the Spawn new session as a final state. When an instance enters a final state, it is deleted after its activity is run. The MX runtime handles deleting the instance automatically. Pycca supports declaring any state to be a final state. For the Autocycle Session class, it appears as follows:

# ... other parts of the Lube domain

class Autocycle_Session
    # ... attribute definitions, reference definitions, etc.

    machine
        # ... other parts of the state model definition

        final state Spawn_new_session

        # ... remaining parts of the state model definition
    end
end

# ... other parts of the Lube domain

Because the instance is deleted when a final state activity is run, outgoing transitions from a final state are not allowed, and pycca will flag an error if one is defined.

Finally, we can return to the last line of code in the Spawn_new_session activity:

self->R2_INJ->R2 = NULL ;

It is necessary to NULL out the reference from the Injector instance to the Autocycle_Session because Spawn_new_session is a final state and about to be deleted. We do not want the Injector instance referring to something that is about to go away. We don’t have to deal with the references made by the Autocycle_Session instance because it will be deleted and therefore can’t refer to anything.

When the creation event is dispatched and a new Autocycle_Session instance is created, the activity of the Creating state will set the new references properly. In a time window between the end of the Spawn_new_session activity and the dispatch of the New_session creation event, the conditionality of the references implied by the R2 association is violated. That is, there is a time when the Injector instance is not controlled by any Lubrication Schedule. This does not violate our execution rules, because we have signaled the event that, when it is dispatched, will bring all the references back to a consistent state. You can think of this sequence as being part of a larger transaction on the data model, and any integrity rule checks are deferred until the transaction is completed, which occurs when the creation event is dispatched. The ST/MX runtime code does not actually perform any of these integrity checks, but other, more capable model execution domains might. For example, a model execution domain that uses a relational database management system to manage the domain data can easily provide transaction-based integrity checking.

Operations

Most of the algorithmic processing in a domain happens in the state activities. However, there are other means to factor processing into invocable units. For example, common code executed in multiple state activities should be factored into a single place. In this section, we show how code can be grouped into various types of operations.

Injector.Max system pressure()

    ALARM. Set pressure error()
    /R2/Autocycle Session.Deactivate()

# ... other parts of the Lube domain

class Injector
    # ... Injector attribute definitions, reference definitions, etc.

    instance operation Max_system_pressure() {
        ExternalOp(ALARM_Set_pressure_error)(PYCCA_idOfSelf) ;  // ❶
        ClassRefVar(Autocycle_Session, acs) = self->R2 ;        // ❷
        InstOp(Autocycle_Session, Deactivate)(acs) ;            // ❸
    }

    # ... remaining parts of the Injector definition
end

# ... other parts of the Lube domain

# ... other parts of the Lube domain

domain operation
Injector_max_pressure(
    InstId_t injId)
{
    PYCCA_checkId(Injector, injId) ;                              // ❶
    ClassRefVar(Injector, inj) = PYCCA_refOfId(Injector, injId) ; // ❷
    if (IsInstInUse(inj)) {                                       // ❸
        InstOp(Injector, Max_system_pressure)(inj) ;
    }
}

# ... other parts of the Lube domain

# ... other parts of the Lube domain

external operation
SIO_Inject(InstId_t injectorId)
{
}

external operation
SIO_Stop_injecting(InstId_t injectorId)
{
}

# ... other parts of the Lube domain

// Link Schedule and Injector together to create this instance
Lubrication Schedule( Name: in.Schedule ) &R2 Injector( ID: in.Injector )
Created -> me

# ... other parts of the Lube domain

class Lubrication_Schedule
    # ... Lubrication Schedule attribute definitions, reference definitions, etc.

    class operation findByName(char const *name) : (struct Lubrication_Schedule *) {  // ❶
        ThisClassRefVar(ls) ;                                                         // ❷
        PYCCA_selectOneStaticInstOfThisClassWhere(ls, strcmp(ls->Name, name) == 0)    // ❸
        return ls == ThisClassEndStorage ? NULL : ls ;                                // ❹
    }

    # ... remaining parts of the Lubrication Schedule definition
end

# ... other parts of the Lube domain

# ... other parts of the Lube domain

class Autocycle_Session
    # ... attribute definitions, reference definitions, etc.

    machine
        # ... other parts of the state model definition
        state Creating(
            char const *schedule,
            unsigned injector)
        {
            ClassRefVar(Lubrication_Schedule, ls) =
                ClassOp(Lubrication_Schedule, findByName)(rcvd_evt->schedule) ;       // ❶
            assert(ls != NULL) ;                                                      // ❷
            ClassRefVar(Injector, inj) = PYCCA_refOfId(Injector, rcvd_evt->injector) ;
            self->R2_LBS = ls ;
            self->R2_INJ = inj ;
            inj->R2 = self ;

            PYCCA_generateToSelf(Created) ;
        }

        # ... remaining parts of the state model definition
    end
end

# ... other parts of the Lube domain