Control Message Activity in Stateflow Charts

A message is a Stateflow^® object that communicates data locally or between charts in a Simulink^® model. From a sender chart, you can send or forward a message. In the receiving chart, a queue receives the message and holds it until the chart can evaluate it.

Simulink model with two Stateflow charts that communicate using a message.

Using Stateflow operators, you can access message data, and send, receive, discard, or forward a message. You can also determine whether a message is valid and find the number of messages in a queue. For more information, see Communicate with Stateflow Charts by Sending Messages.

Access Message Data

Stateflow messages have a data field. To read or write to the message data field of a valid message, use dot notation syntax:

message_name.data

If you send a message without first assigning a value to the message data, the default value for numeric data is 0. For enumerated data, the default is the first value listed in the enumeration section of the definition, unless you specify otherwise in the methods section of the definition.

You cannot access message data for messages that are still in the queue or that have already been discarded.

Send a Message

To send an output or local message, use the send operator:

send(message_name)

For example, in this chart, the entry action in state A sends a message M with a data value of 3. If the message scope is Local, then the message goes in the local receiving queue. If the message scope is Output, then the chart sends the message through the output port to another block in the Simulink model.

Stateflow chart that uses the send operator in a state.

In a single time step, you can send multiple messages through an output port or to a local receiving queue.

If a chart sends a message that exceeds the capacity of the receiving queue, a queue overflow occurs. The result of the queue overflow depends on the type of receiving queue.

When an overflow occurs in an internal queue, the Stateflow chart drops the new message. You can control the level of diagnostic action by setting the Queue Overflow Diagnostic property for the message. See Queue Overflow Diagnostic.
When an overflow occurs in an external queue, the Queue (Simulink) block either drops the new message or overwrites the oldest message in the queue, depending on the configuration of the block. See Overwrite the oldest element if queue is full (Simulink). An overflow in an external queue always results in a warning.

Guard Transitions and Actions

Messages can guard transitions or state actions of type on. During a time step, when the guarding message is evaluated for the first time, the chart removes the message from the queue and makes the message valid. While the message is valid, other transitions or actions can access the message data but they do not remove another message from the queue.

Guard a Transition with a Message

In this chart, a message M guards the transition from state A to state B. The transition occurs when both of these conditions are true:

A message is present in the queue.
The data value of the message is equal to 3.

If a message is not present or if the data value is not equal to 3, then the transition does not occur. If a message is present, it is removed from the queue regardless of whether the transition occurs.

Stateflow chart with two states called A and B. The message M guards the transition between the states.

Guard a State `on` Action with a Message

In this chart, a message M guards the on action in state A. When state A becomes active, it increments the value of x if both of these conditions are true:

A message is present in the queue.
The data value of the message is equal to 3.

If a message is not present or if the data value is not equal to 3, then the value of x does not change. If a message is present, it is removed from the queue regardless of whether x is modified.

Stateflow chart with a state called A. The message M guards the on action in the state.

Receive a Message

To extract an input or local message from its receiving queue, use the receive operator:

receive(message_name)

If a valid message M exists, receive(M) returns true. If a valid message does not exist but there is a message in the queue, then the chart removes the message from the queue and receive(M) returns true. If a valid message does not exist and there are no messages in the queue, receive(M) returns false.

For example, in this chart, the during action in state A checks the queue for message M and increments the value of x if both of these conditions are true:

A message is present in the queue.
The data value of the message is equal to 3.

If a message is not present or if the data value is not equal to 3, then the value of x does not change. If a message is present, the chart removes it from the queue regardless of the data value.

Stateflow chart that uses the receive operator.

Discard a Message

To discard a valid input or local message, use the discard operator:

discard(message_name)

After a chart discards a message, it can remove another message from the queue in the same time step. A chart cannot access the data of a discarded message.

For example, in this chart, the during action in state A checks the queue for message M. If a message is present, the chart removes it from the queue. If the message has a data value equal to 3, the chart discards the message.

Stateflow chart that uses the discard operator.

Forward a Message

To forward a valid input or local message to a local queue or an output port, use the forward operator:

forward(message_in_name,message_out_name)

After a chart forwards a message, it can remove another message from the queue in the same time step.

Forward an Input Message

In this chart, state A checks the input queue for message M_in. If a message is present, the chart removes the message from the queue and forwards it to the output port M_out. After the chart forwards the message, the message is no longer valid in state A.

Stateflow chart that uses the forward operator.

Forward a Local Message

In this chart, the transition between state A and state B checks the local queue for message M_local. If a message is present, the transition removes the message from the M_local message queue and forwards it to the output port M_out.

Stateflow chart that uses the forward operator.

Determine if a Message Is Valid

To check if an input or local message is valid, use the isvalid operator:

isvalid(message_name)

A message is valid if the chart has removed it from the receiving queue and has not forwarded or discarded it.

For example, this chart first executes state A, as described in Discard a Message. When the chart executes state B, the during action checks that the message M is valid. If the message is valid and has a data value equal to 6, the chart discards the message.

Stateflow chart that uses the isvalid operator.

Determine the Length of the Queue

To check the number of messages in an internal receiving queue of an input or local message, use the length operator:

length(message_name)

For example, in this chart, the during action in state A checks the queue for message M. If a message is present, the chart removes it from the queue. If exactly seven messages remain in the queue, the chart increments the value of x.

Stateflow chart that uses the length operator.

The length operator is not supported for input messages that use external receiving queues managed by a Queue (Simulink) block.