DiagramElements-Pin/en

Introduction

Pins are the data interfaces between steps. They are used to read and pass data such as parameters, results and measurement data, documents or simple control information and represent the inputs and outputs of an activity. Output values of one activity are transported via a connection from the output pin to one or multiple input pins of other processing steps. When all required inputs of a processing step are available, an activity is created, which processes the input values, computes one or multiple result values, and transfers them via the output pins to further processing steps.

Individual Input Pin Attributes

Each regular (data) input pin can individually be configured to be one of the following builtin stereotypes, which affect its triggering and value consumation behavior:

• triggering, consuming ("regular")
• non-triggering, non-consuming ("parameter")
• non-triggering, pass-through ("mailbox")
• triggering, pass-through mailbox ("telegram")

Actually, there are 8 possible combinations of the triggering/non-triggering, consuming/non-consuming and mailbox/non-mailbox attributes. However, in practice, only the four combinations listed above are useful. Therefore, those have been given special names and they have special menu items in the network editor's popup menu for pins.

Trigger vs. Non-Trigger

The trigger / non-trigger attribute affects if a new activity is to be created for the step. Each triggering pin is considered by the input-fetcher algorithm (as described below). A step without any triggering data input pin must be activated by either an autostart attribute, or by explicit trigger via the trigger-input pin.

Consuming vs. Non-Consuming

The consuming / non-consuming attribute defines if incoming values are read-out from the pins input basket (consuming) or stay there. Consuming baskets show the normal producer-consumer behavior. Non-comsuming pins are used for parameter values: these are stored in the pin and kept remembered for the next activity, until changed. Frozen pins are always configured to be non-triggering, non-consuming pins (by the diagram editor, when a freeze value is defined).

Mailbox vs. Non-Mailbox

The pass-through (mailbox) pin stereotype specifies that input values are not latched and remembered in the activity, but instead are passed through to either the underlying elementary action or the internal network of a compound activity. This means, that these pins, when receiving a value, are forwarded to an already executing activity (all of them, if there are multiple). Mailbox pins can therefore pass information into an already running action.

Notice for consuming pins:
If a triggering pin's input value is to be reused in a loop, it must be configured as a non-consuming pin. Otherwise the input data value is already consumed when the second iteration is due, and the step would not be triggered. Because this is so common an error (to "eat" the input value in a loop), there is an extra check-entry for that in the tree-pane's error-search tab. Be especially careful when using a compound action's input pin value inside the network as input to a step which is part of a loop.

Triggering Behavior when Multiple Inputs are Present

The trigger behavior is specified in a blocks schema definition - not at the step in a diagram. The reason is that the implementor of an action block (especially if it is an elementary block) would know better what the intended and appropriate behavior will be, and if the action can or should deal with unconnected pins or pins which have not received a datum.

When multiple triggering pins are present in a step, the overall trigger behavior can be specified to be one of:

• AND-connected
• AND
• OR

AND-connected Triggering Behavior

All connected triggering pins must have a value for the trigger to happen. Disconnected, parameter- and mailbox-pins are ignored. This is the default behavior, when new blocks are created.

AND Triggering Behavior

All triggering pins must be connected and have a value for the trigger to happen. Parameter- and mailbox-pins are excluded from this test.

OR Triggering Behavior

Any triggering pin with a value will trigger the activity. This is useful if a step receives values from multiple sources (i.e. to implement join of alternative branches). Unconnected pins and pins with no value are ignored and provide no value when referred to inside a network or elementary action code.

Notice:
In a traditional Petri Net, synchronization of values is done at explicit transition points. Ta make the diagram easier to read and understand, expecco has merged the transition functionality into the action steps. Thus, every step with multiple input pins has an implicit transition behavior already builtin. In situations, where explicit transition points are preferred or required (for semantic or didactic reasons), the standard library also provides a number of synchronization blocks, which can be used to model the tradition join, merge and fork transition primitives.

Different Types of Pins

The different types of pins are shown in this image in clockwise order:

Inputs:

• Data-Input (at the left, named "in1")
• Enable-Input (also called "Trigger Input" at top-left),
• Cancel,
• Timelimit,
• Repeatcount,
• Performer,

Outputs:

• Data-Output (at the right, named "out1"),
• Exception (at bottom-right)
• Enable-Output (triggerOutput).

The Execution-Time output pin, which has been added to expecco version 1.8, is not shown in the above picture.

Input Pins

Input pins are located at the left and/or at the top of a step. They receive data and process this depending on their type.

Special Input Pins

The following special input pins are optional and not automatically present at a step, when it is initially created in a diagram. You have to explicitly create them via the step's popup menu or via one of the toolbar shortcut action buttons in the diagram editor.

Enable Input Pin

The enable input pin is used to trigger an activity. If connected, it is used like an additional triggering, required input. Trigger inputs are needed if either all of a step's inputs are frozen to static values, or if the execution has to be synchronized to be after another step's execution. Trigger input pins are consuming.

Cancel Pin

The cancel pin can be used to cancel (abort) an ongoing activity. A long-running activity can be cancelled, by passing any data to a step's cancel pin. The dataflow-behavior of a cancel input is different from other input pins' behavior: cancel input pins behave like a mailbox-input pin; this means that input values are not fetched and remembered at triggering time, as is the case with normal input pins. Instead, an incoming value is immediately handled at any time during the execution of the step and forces the activity to stop. If a cancel pin receives a value before the steps activity has started or after it has finished, nothing happens. Especially a cancel value arriving before the activity has started is ignored. If uncertain, make sure that no race conditions arise, by inserting appropriate delay steps.

Timelimit Pin

The timelimit pin can be used to cancel an activity after a given maximum eecution time. The timelimit value can either come from another step's output, frozen to a constant value, or read from an environment variable. In most real-world applications, environment variables are used. The timelimit pin is a non-triggering, non-consuming parameter pin.

Repeatcount Pin

The repeatcount pin (also called: "iteration-count") can be used to execute a step's action multiple times. The iteration value can originate from another step's output or from a constant freeze-value, or from an environment variable. This is a non-triggering, non-consuming parameter pin. If used together with a timelimit pin, the timelimit is applied to the overall execution (i.e. NOT applied to each individual iteration).

Performer Pin

The performer pin is only present at a virtual block's step. It can be used to dynamically specify a concrete action block to be performed by the virtual block. If a virtual block's performer input is left unconnected, the environment is consulted for a binding of the virtual action or the virtual action's library (see virtual library). This is a non-consuming, non-triggering pin.

Output Pins

Output pins are located on the right (data output) and at the bottom of a step (control output). They pass data/control information to other steps.

Special Output Pins

Enable Output Pin

The optional enable output pin (also sometimes called "trigger-out") is activated after the execution of a step is finished successfully. The enable output pin is NOT given a value, if an exception is raised AND an exception output pin is present. However, it is triggered, if an exception is ignored.

Exception Output Pin

The optional exception pin is used for exception handling and reporting. Whenever an execution leads to an error, and the exception output is connected, an exception information datum is generated and passed to that output. Ususally the value is used to trigger or cancel other activities by their cancel or enable input pins. Steps which do not handle the exception (i.e. those without an exception output and not ignoring the exception) pass the exception up to their enclosing network's step. If nowhere handled, this exception forwarding will continue up to the top-level testcase, and lead to an ERROR verdict there.

Notice, that by connecting both the exception-out and the enable-out pins to different followup steps, conditional execution based on a step's success is possible.

Also note that if the "Ignore Exceptions" option is set for a step, both enable output pin AND the exception output pins are triggered.

Exception Pin Example 1: Depending on the success or failure of Step1, either Step2 or Step3 is executed.

Exception Pin Example 2: Both are started in parallel (due to the autostart flag). If the execution of the first step fails, the second will be cancelled via its cancel pin (if it has not finished by that time).

ExecutionTime Output Pin

This pin, if present, will provide the step's execution time (as a TimeDuration value).

---

For elementary code API to pins see: Expecco API
For other diagram elements see: Diagram Elements
Back to the full online documentation: Online Documentation

---

Copyright © 2014-2024 eXept Software AG