NI QMH Template

During the CLA Summit in Rome, I was surprised to see only a handful of hands raised when I asked how many people were familiar with the National Instruments Queued Message Handler project template that ships with LabVIEW 2012 and later. I can understand people not looking at the project templates, thinking they are similar to the old VI templates that have been available in the File > New dialog for many years (Producer Consumer, State Machine, etc.). Unlike the old VI templates, which are more instructional, the newer project templates are intended to be starting points for real-world applications. There are also several sample projects which implement some common applications such as continuous acquisition and logging.

A few architects have created their own project templates, some of which started from the old Producer Consumer template. The NI QMH is a good starting point for many applications, and it addresses a lot of issues that aren’t handled by the Producer Consumer VI template, such as stopping the Event Handling Loop (EHL) from the Message Handling Loop (MHL) via a User Event, simple error handling, etc. Nevertheless, there are a few issues to keep in mind when working with the NI QMH project template:

 

User Event Registration wrapped inside a subVI – In the NI QMH, the Register For Events function exists in a subVI, as opposed to the same owning diagram as the Event Handling Loop. There are two issues with this approach. First, since the event registration refnum passes through a subVI boundary, the event case that handles the user event gets a non-descriptive name of “User Event”. The other issue is that less-experienced developers might be tempted to fork the registration wire. There should always be a one-to-one ratio between a Register For Events function and an Event Structure. The main issue with using a single event registration refnum for multiple Register For Events functions is that a single event engine gets created, and this can lead to one of the Event structures missing out on events for which it is registered. If you would like to learn more about this and other nuances of User Events, I recommend taking the National Instruments Customer Education course Advanced Architectures in LabVIEW. [Edit] Rumor has it The Register For Events function is no longer wrapped in a subVI in the LabVIEW 2015 version of the NI QMH project template.

The project template creates your own copy of the User Event library as well as the Message Queue library – This means every new project will have a copy of these libraries. This can be confusing for inexperienced developers, and they might make modifications to one of these libraries in a given QMH project and forget about the modifications when they go start a new QMH project. In addition, all the VIs end up having the same nice icons, making it hard to spot at a glance that these VIs might have been modified. This also means that if there are improvements made to the NI QMH project template, you will have to go back to your existing projects and make the modifications yourself. This is not necessarily a bad thing, but it is something to keep in mind. If you have to support an existing project, do not assume that the original developers left the User Event and Message Queue libraries unchanged.

 

Priority enqueueing (enqueueing at the front of the queue) – This feature is very useful to ensure that the Exit message gets ahead of any other messages in the message queue. However, I have often seen developers make several messages high priority. When there are multiple potential high priority messages, there is no guarantee that the Exit message will stay at the front of the message queue.  An added measure to take if you are using LabVIEW 2014 or later is to make firing the Stop User Event high priority.

 

Using the QMH as a State Machine – Advanced LabVIEW developers and architects have moved away from using the QMH because of bad experiences trying to use it as a state machine. The main issue is trying to enqueue a series of messages that need to be executed back to back without interruption (except for the Exit message). One suggested way around this is to enqueue multiple messages using a For Loop. The NI QMH accomplishes this by providing an “enqueue multiple messages” polymorphic instance of the enqueue VI. However, there is still a slight possibility that a message could get enqueued by a parallel process between two loop iterations within this VI. My suggestion is to use a state machine subVI that is also registered to listen to the stop event. This state machine can be implemented with the Simple State Machine project template with the Event structure in the idle case. Another option is to have the cases of the state machine in the timeout event of the Event structure.

At this point, someone usually asks “Why not implement the QMH as a single loop, just like the JKI State Machine?”. This would make sure that new states are not enqueued until a series of states are executed. This is definitely a good option, and it has the added benefit of keeping all the local data in the loop’s shift register.  It also makes it easier to add data from the event cases. However, the dequeuer needs a timeout that sends the state machine to the “Idle” case to service events, and the Event structure ends up having a timeout as well to ensure no enqueues are missed. This turns the state machine loop into a polling for events/messages machine. In the NI QMH, there is no need for timeouts in the Event structure or in the dequeuer. If there is no interaction from the user with the front panel, then the whole VI is simply dormant until an event from the front panel causes it to wake up.

 

Wrapping Up – If you want to learn more about the NI QMH project template and figure out how you can use it (or not), click Create Project from the Getting Started Window in LabVIEW and then click on the “More Information” link within the QMH project template description. You can also just create your first project based on this template, which will include a copy of the documentation.  Finally, be sure to check out the presentation called Queued Message Handler: Caveats and Design Decisions.

 

We will be sharing our own QMH project template in the near future. We call it the Delacor QMH or DQMH. The main modifications we have done are to address the issue with the event registration and use User Events as our inter-process communication mechanism. We got some of these ideas from Justin Goeres’ 2011 presentation on Private/Public User events. We also decided to wrap the message queue in a class, and make it private to the DQMH module just like I presented at the 2013 European CLA Summit in Paris. But alas, I am getting ahead of myself. Stay tuned to find out more later this year.

 

Happy wiring,

Fab