Pin

R2026b

Direct tokens into or out of an action node

Since R2024a

expand all in page
  • Pin Icon

Description

A pin acts as a buffer for object tokens and directs tokens into or out of an action node. The directionality of the pin represents input or output. You can connect pins by object flows.

These are the two types of input and output pins:

  • Streaming pins

    Streaming input pin

  • Non-streaming pins

    Non-streaming input pin

Action nodes with both types of pins begin execution only once all the required input pins hold the minimum number of object tokens specified by the lower bound. Action nodes terminate only once all the required output pins receive the minimum number of tokens specified by the lower bound. Pins with a lower bound of 0 are optional and do not need tokens for the action node to begin or complete execution.

The upper bound limits the number of tokens that a pin can hold. However, the execution starts as soon as the number of tokens satisfy the lower bound. If the lower bound is set to 2, the action begins execution as soon as it receives 2 tokens irrespective of the upper bound. Once the lower bound condition is met, the software does not reevaluate the condition until the nested activity restarts.

Streaming pins and non-streaming pins differ based on how tokens are handled when the action node is executing.

Note

Streaming pins can only be configured for action nodes with a nested activity diagram.

Streaming Pins

Streaming input pins continue to accept and buffer all the tokens that arrive at the pin once the nested activity begins to execute. As the tokens arrive, the software forwards the tokens to the corresponding input parameter node.

Streaming output pins enable the corresponding output parameter nodes to accept and forward incoming tokens. Output parameter nodes can forward the tokens regardless of whether the action is completed.

Non-Streaming Pins

Non-streaming input pins block any incoming object tokens while the action node executes, which causes output object tokens to go into a pending state in the output pins of the previous nodes. If an output pin already has a pending token, any new generated token is discarded. This action is called blocking behavior.

Non-streaming output pins rely on the corresponding output parameter node to hold any incoming tokens. The tokens are forwarded to the output pin only when the action node finishes execution.

Examples

expand all

Open Live Script

This example shows how you can use an activity diagram containing a nested activity with streaming input pins to model a simple weather station.

Explore the Model

Open the model. 

modelname = "weatherforecast_ad";
open_system(modelname);

Snapshot of Weather Station activity diagram

The activity diagram contains three main areas:

  • Atmospheric Pressure — Simulates generation of barometer readings for a region. The readings indicate the general weather conditions.

  • Weather Satellite Images — Simulates generation of satellite images over a region. The images display cloud cover that can help predict short-term weather.

  • Weather Station — Receives atmospheric pressure and image data as input and determines a weather forecast.

The behavior of the action nodes in the activity diagram is dictated by the functions in the MATLAB class file, ws, that is included with the example.

Input Generation for Weather Station

The weather station receives inputs from action nodes in the areas Atmospheric Pressure and Weather Satellite Images.

The Atmospheric Pressure area contains the action node Barometer Data that simulates the continuous generation of barometer readings. After the action node generates a barometer reading, control is passed back to it immediately through a Merge node. The action node generates the next barometer reading, and so on. The next action node, Barometer Data Evaluation, outputs a signal based on different threshold values for the input barometer data.

The Weather Satellite Images area contains the action node Satellite Image that simulates continuous generation of grayscale images depicting cloud cover over a certain region. Grayscale images are represented by a 3-by-3 matrix assigned to the structure GrayPixel in the Types Editor.

Types Editor showing the GrayPixel structure

The next action node, Image Processing, calculates the mean of the grayscale values of the pixels in an image and outputs a signal based on different threshold values for this mean value.

Execution of Weather Station

The Weather Station nested activity in the Weather Station area accepts inputs representing barometer evaluation data and image evaluation data through streaming pins.

The presence of streaming pins allows the nested activity to consume input data while it executes, unlike nonstreaming pins that wait for an action node or nested activity to finish executing for its designated duration.

Streaming pins allow for a nested activity to execute until a desired outcome is achieved, given that the value provided for Stop Time is sufficient. In this example, Weather Station executes until the final weather forecast has a confidence level of 85% or greater, or until the stop time is reached.

In this example, if you use non-streaming pins instead, then the nested activity can execute only one round before it requires more inputs for confidence evaluation (unless the first forecast has high confidence). At this point, non-streaming input pins do not admit more input tokens because the nested activity has not completed execution. Hence, the activity diagram cannot proceed to completion.

The Weather Station nested activity uses its inputs to determine the short-term weather forecast for a region. For example, if the barometer reading is high and the mean of the image pixel values is low, indicating more brightness and less cloudiness, then the weather forecast is Partly Sunny.

Each weather forecast is also associated with a confidence level in a structure named ConfidenceLevel. If the generated confidence level is low or medium, then the corresponding forecast is not displayed. If the confidence generated for a forecast is greater than 0.85, then the forecast is considered final. The final forecast is displayed in the Diagnostic Viewer.

The nested activity terminates when it receives a representative object token at its output activity parameter node. The activity diagram also terminates. At this point, any remaining tokens that arrived to the nested activity are destroyed, and the states of all the nodes are reset.

Run the Model

Simulate the model.

sim("weatherforecast_ad");
    0.6557

Confidence Level for Forecast: Low or Medium.
    0.0318

Confidence Level for Forecast: Low or Medium.
    0.7655

Confidence Level for Forecast: Low or Medium.
    0.1626

Confidence Level for Forecast: Low or Medium.
    0.8909

Confidence Level: High!
Forecast: Partly Sunny.

To clearly view the flow of tokens, you can slow down the animation speed by changing the Animation speed in the Debug tab.

Parameters

expand all

Pin

Pins act as buffers for object tokens during execution of an activity diagram.

Each pin is associated with a certain data type. All tokens of a pin must have the data type associated with the pin.

For an action node with an activity behavior type, the pins represent their corresponding parameter nodes. For more information, see Parameters.

Name of the input or output pin. By default, the pin is called InputPin or OutputPin depending on its configuration. As more input or output pins are added to action nodes, increasing numerical suffixes are added to InputPin or OutputPin, respectively.

The minimum number of tokens required at a pin for the corresponding action node to begin or complete execution. For input pins, the action node begins execution only once the pin holds the minimum number of tokens specified by the lower bound. For output pins, the action node completes execution only once the pin receives the minimum number of tokens specified by the lower bound.

You can set the lower bound to 0 to make a pin optional. This allows the node to begin or complete execution without requiring object tokens on that pin.

The maximum number of tokens that a pin can hold. If a pin has an upper bound greater than one, it can hold multiple tokens. Upon execution, an action node takes in or produces up to the number of object tokens specified by the upper bound.

The upper bound does not affect when the action node begins execution.

In a MATLAB function defined for an action node, each input and output argument corresponds to an input or output pin, respectively, specified by the argument order of the pin.

For example, if the argument order of an input pin is 2, then this pin represents the second input argument of the MATLAB function.

Enable or disable streaming for the input or output pin of an action node with a nested activity. The value of this streaming control automatically applies to the corresponding input or output activity parameter nodes in the nested activity.

This list contains stereotypes from imported profiles. To assign a stereotype to a pin, select the stereotype from the list.

You can also use <new/edit> option to manage profiles using Profile Editor.

Object Type

An input or output pin can handle object tokens of a certain type. In the Property Inspector, the Object Type section for a pin allows you to specify the type and other properties of an object token.

The type of object held by an action node pin.

  • <owned> — Select properties for an object token, such as type, dimension, complexity, and unit from the Property Inspector.

  • <inherit> — Inherit the object type from the previous pin.

  • custom type — Choose from the list of custom types you created using the Types Editor.

The direction of token flow through a pin of an action node. This parameter is automatically set to Input or Output, depending on whether you create an input pin or output pin, respectively.

Data type of the token. For more information on using MATLAB class type, see Model Complex Objects in Activity Diagrams Using MATLAB Class Tokens.

Dependencies

To enable this parameter, set Name to <owned>.

Dimensions of the token, specified as a positive integer or two-element vector.

Specify a positive integer for a vector with the specified number of elements or a two-element vector for a matrix with the specified number of rows and columns.

Dependencies

To enable this parameter, set Name to <owned>.

Custom unit that you assign to the token.

Dependencies

To enable this parameter, set Name to <owned>.

Complexity of the token.

Dependencies

To enable this parameter, set Name to <owned>.

Version History

Introduced in R2024a

expand all

See Also

Functions

Objects

Tools

Blocks

Topics