Queued Message Handler Design Pattern and Reference Design Library

The Queued Message Handler design pattern is a general purpose VI architecture that can be used as the basis for a wide range of LabVIEW VIs. This design pattern can be used to implement state machines, user interfaces for applications, asynchronous communication processors, as well as other tasks and system components within a larger application. This design pattern is similar to other VI architecture implementations often called a queued state machine. As the design pattern can be used for many purposes other than a state machine and state oriented tasks, the name for this reference library has been chosen to be more representative of the implementation of the design pattern.

The two download files above contain the same contents in different installer formats. You only need to download and install one of these.

qmh_107_installer.zip

The Queued Message Handler reference library can be installed into your LabVIEW development environment using the Windows installer contained in the ZIP file above. Unzip the contents of the ZIP file to an empty folder on your system and run setup.exe.

nise_lib_qmh-1.0.7-1.ogp

This VI package is intended for use with VI Package Manager™ (VIPM). VI Package Manager is an installer for LabVIEW VIs and toolkits. It places VIs directly into the palettes, allows you to install VIs into multiple LabVIEW versions, and ensures that any dependency VIs and toolkits (provided in other VI packages) are also installed. VI Package Manager is a trademark and product of JKI Software.

Feedback

This reference design library was created by the NI Systems Engineering group. 

You can give us feedback by posting questions and comments through the QMH reference library discussion thread. 

Overview

The Queued Message Handler (QMH) design pattern is a basic producer-consumer architecture which can be used as the basis for a wide variety of LabVIEW VIs throughout an application. Common uses of the QMH design pattern are the user interface of an application, dialog windows, command and communication parsers, state-based controllers and others.

The general purpose of the QMH design pattern is to receive, store, and then process messages. Messages can be events from a user interface, commands received from a communication interface and more. In general a message is an asynchronous event which requires some action, operation, service, or other response. 

The QMH is implemented using a queue to store messages from one or more message generators or sources. Messages are read from the queue by the message processor. The message processor consists of multiple cases or states, each dedicated to process a specific message coming from the queue.

Figure 1: Queued Message Handler Design Pattern

The message queue can be accessed from multiple message generators who all place messages on the queue for processing by the message handler. However, it is common that only a single message generator exists in a particular implementation such as a user interface VI.

In addition to dedicated message generators, processing routines within the message handler may also place new messages on the message queue while processing other messages. For example, an error in processing one message may cause the message handler to place an error message on the queue to be subsequently processed by another routine in the message handler.

During normal operations of the QMH, messages are typically placed at the end of the queue and processed from the front of the queue in a First-In First-Out (FIFO) fashion.  

Figure 2: QMH normal operation placing new messages at the end of the queue

In some cases it is desirable that a new message on the queue will be processed as soon as possible. In this case the message may be put at the front of the queue and will be processed the next time the message processor retrieves a message from the queue.

Figure 3: QMH priority operation placing a new error message at the front of the queue

Implementation

The LabVIEW Queued Message Handler (QMH) is built around a LabVIEW queue used to store messages and a While Loop/Case Structure-based message processor. To simplify the use of the QMH design pattern in new VI's and applications this tutorial includes a set of VI's, template and examples, packaged as a reference design library. After installation the QMH tools are available in the User Libraries function palette.

Messages Definition

When developing a queued message handler, there are a number of possible ways to define the message stored on the queue. Common implementations include strings, variants and enumerations. Each of these choices offers different advantages and disadvantages. 

This reference design uses a string as the basic data type for messages, as it provides the ability to easily pass any message to the queue without the need to define a set of permissible messages in the VI. This simplifies the process of adding new messages to the application and simplifies using the reference library in a wide range of applications. However, using strings for the message datatype does make it more likely to have a typo in the message name or to add messages to the queue which are not handled properly in the message handler. Care must be taken when specifying messages and a special case in the message handler should be used to detect and report any unhandled messages.

Instead of a string, an enumeration can be used to define a specific set of messages allow by the application. Creating a TypeDef enumeration does make it easier to change the set of allowed messages in an application, while preventing any typos in selecting a message during programming. However, when using an enumeration, the set of allowed messages needs to be adapted for each use of the QMH and therefore one set of VIs to manage the queue, can not be used for multiple applications of the QMH. 

Message Queue

The message queue is implemented as a simple LabVIEW string queue. To make queue operation easier and more consistent throughout an application, a set of QMH VIs is provided with this reference design. These VIs and a template of the queued message handler design pattern are available in the User Libraries function palette.

Figure 4: QMH Function Palette

Creating the Message Queue and Adding Messages 

Before adding messages to the queue it must be created using the QMH Create Queue VI. You can leave the queue name empty or provide it a unique name. As part of creating the queue you can place a number of initial messages on the queue. These messages will be the first messages handled in the message processor. Typically these messages are used for the startup or initialization of the VI.

After creating the queue, messages can be added to the queue using the QMH Add Message to Queue VI. 

In the following diagram  the queue is created and three initial messages are added to the queue. In the user interface event handler the Write Config File message is added to the queue when the operator presses the Save State button on the UI. The message processor is not shown in this diagram.

Figure 5: Message Queue Initialization and UI Event

QMH Add Message to Queue VI is a polymorphic VIs and can be used to add multiple messages to the queue in one operation. Multiple messages are passed as a string array to the VI.

Figure 6: Example of adding multiple messages to the queue

In addition to the messages stored on the queue in some cases it is useful to be able to pass additional data such as parameters along with the messages. This additional data is used in the message processor to customize the processing of the message. Message parameters are passed as a string or string array for multiple messages to QMH Add Message to Queue VI. The previous diagram includes the new value of the Clock Style control as a parameter with the Set Clock Style message.

Adding Messages to the Front of the Queue

To add a new message to the front of the message queue so that is processed during the next iteration of the message processor, set the At Front input of the QMH Add Message to Queue VI to True.

Figure 7: QMH Add Message to Queue.vi

Processing Messages

From the queue, messages are read in the message processor loop and then handled by a separate case for each of the messages used in a message handler. The basic message processor includes the QMH Get Next Message from Queue VI and a case structure with individual cases for each message.

Figure 8: Message processor loop showing one message case 'Set Clock Style'

Reading Messages from the Queue

The QMH Get Next Message from Queue VI includes a few specific features that should be observed in the message processor. The default operation of this VI is to return the next message from the queue and the associated parameter string. The message name is used as the case structure selector for the message processor and the parameter string may be used in the specific message processor case.

Timeout

The timeout value on QMH Get Next Message from Queue determines when the VI returns even if no message is available on the queue. In this case an empty message string is returned from the VI which should be handled in an appropriate case. The message handler template included in the QMH reference library contains a message processor case labelled "", "Wait" which is called if there is a timeout on the Get Next Message VI. This message processor case can be used to handle background tasks necessary in the VI operation such as front panel updates, etc. This case can also be called by placing a Wait message on the queue.

QMH Termination

Terminating the QMH must be handled so that both the message processor and all message generators such as the user interface event loop are shutdown properly. In some cases the message generating loop may continue to run if it also handles other operations in the VI. However, it should not add any more messages to the queue after the message processor has been shutdown.

Typically the QMH will be terminated in response to a user action from the front panel such as a Quit button or a message received from another part of the application. In the message generator a message is added to the queue to indicate to the message processor to shutdown. In addition the message generator loop can be shutdown by passing a True to the While loop conditional Stop terminal.

When the message to shutdown the QMH is received in the message processor, it should execute any necessary operations in the corresponding message case before terminating the message processor loop. The QMH Get Next Message from Queue VI is designed to recognize one or more messages for termination of the QMH and will return a True value on the Stop QMH output which can be used to terminate the message processor loop. The default message to shutdown the QMH is Exit, but it can be changed by passing the desired shutdown message name(s) to the QMH Get Next Message from Queue VI. 

Default Message Processor

Due to the use of strings as the message data type it is possible to make errors or typos when adding messages to the message queue. Any such erroneous messages will not have a corresponding message case in the message processor. Therefore the Case structure default case of the message processor should be used to catch any undefined messages from the queue. Normally any messages passed to this case are the result of a programming error and should be reported as such. Once a VI or application has been completely tested no erroneous message should trigger this message case.

Figure 9: QMH Default Message Case

QMH Template

The Queued Message Handler reference library includes a basic VI template of the QMH reference design. The QMH template can be placed on the diagram from the QMH function palette. The following figure shows the diagram of the QMH template.

[+] Enlarge Image

Figure 10: Queued message handler template available in the QMH function palette

The QMH template is targeted at a UI-based VI whish processes UI events in the message handler. The UI events handled by the VI can be customized in the message generator loop on the left. Message processor cases can be added to the loop on the right. 

The template can be adapted to other types of applications and VIs by modifying the message generator loop. If necessary the message processor may also be adapted. The template should be used as a reference design and customized according to the needs of the individual application.

Examples

The Queued Message Handler reference library includes a couple of examples showing the use of the QMH VIs and template. These example are installed along with the reference library VIs in the ..\<LabVIEW>\user.lib\QMH folder. These examples are accessible as dropable VIs from the QMH function palette.

References

The Queued Message Handler (QMH) design pattern and reference library presented in this article is only one possible implementation of the general concept of a queued message handler or queued state machine. The following links provide references and discussion on similar and related design patterns from a variety of sources.

Developer Zone: Application Design Patterns: State Machines

ExpressionFlow: LabVIEW Queued State Machine Architecture

JKI Software: State Machine

 

Requirements

Filename: nise_lib_qmh-1.0.7-1.ogp

Software Requirements

Application Software: LabVIEW Full Development System 8.5.1
Language(s): LabVIEW

Filename: qmh_107_installer.zip

Software Requirements

Application Software: LabVIEW Full Development System 8.5.1
Language(s): LabVIEW

Reader Comments | Submit a comment »

Hi, I would like to know if there is a QMH library implementation available for LabVIEW FDS or PDS 8.2.1. Many thanks
- Cosimo Micelli, KleisTEK di Cosimo Micelli. c.micelli@kleistek.com - Mar 20, 2009

Hi, very clear and useful! Is there a QMH library available for LV 8.2.1? Many thanks
- Cosimo Micelli, KleisTEK. c.micelli@kleistek.com - Mar 11, 2009

works on OSX
You can manually extract vis from the CAB archive and rename them correctly to have them on OSX. The whole installer is 11MB and VIs are 0.5MB...
- Feb 19, 2009

Make it a VIPM package
I'd like to see this available as a VIPM package (preferrably on the VIPM Package Network: http://jkisoft.com/vi- package-network/)
- Jan 23, 2009